## Zoho Billing - Product, solutions, integrations, support, and resources Index

Access the complete documentation index at:
https://www.zoho.com/om/billing/llms.txt

Use this file to discover all available documentation pages before proceeding.

# iOS In-App Purchases SDK Implementation

The [iOS SDK](https://zoho.github.io/zsinappkit-docs/apple/) (`ZSInAppPurchaseKit`) connects your app to Zoho Billing for subscription lifecycle syncing.

**Pro Tip:**

Before starting, review [Best Practices for SDK Implementation](/om/billing/help/omnichannel-subscription/sdk-configuration.html).

* * *

## Install the SDK

Install `ZSInAppPurchaseKit` using Swift Package Manager.

*   In Xcode, go to **File** > **Swift Packages** > **Add Package Dependency**.
*   Enter the package URL.
*   Select the required version.
*   Click **Add Package**.
*   Add `import ZSInAppPurchaseKit` at the top of your Swift file.

```text
https://github.com/zoho/ZSInAppPurchaseKit.git
```

* * *

## Initialise the SDK

Initialise the SDK early in your app launch flow, after user details are available.

```swift
// apiKey: Key generated in Zoho Billing App Store integration.
// zsProductId: Product identifier from Zoho Billing.
// domain: Data centre domain for your Zoho Billing organisation.
let zsConfiguration = ZSConfiguration(
    apiKey: YOUR_API_KEY,
    zsProductId: YOUR_PRODUCT_ID,
    domain: DOMAIN
)

// userId: Your app user identifier. Map this to channel_customer_id.
// email: User email.
// displayName: User display name.
zsConfiguration.setUserInfo(
    userId: APP_USER_ID,
    email: APP_USER_EMAIL,
    displayName: APP_USER_DISPLAY_NAME
)
ZSKit.initialize(configuration: zsConfiguration)
```

**Note:**

For best practice guidance on the `userId`, `zsProductId`, and `domain` parameters, see [Match Customers Across Channels](/om/billing/help/omnichannel-subscription/sdk-configuration.html#match-customers-across-channels), [Map Subscriptions to the Correct Product](/om/billing/help/omnichannel-subscription/sdk-configuration.html#map-subscriptions-to-the-correct-product), and [Configure the Correct Data Centre](/om/billing/help/omnichannel-subscription/sdk-configuration.html#configure-the-correct-data-center).

* * *

## Fetch Plans

Use `getPlans` to fetch plan details from Zoho Billing and App Store.

```swift
ZSKit.getPlans { plans, error in
    // Display plans in your UI.
    // Use plan.skProduct?.displayPrice for App Store price display.
}
```

* * *

## Initiate a Purchase

Call `initiatePurchase` when a user selects a plan.

```swift
// product: skProduct from selected ZSPlan.
// customFields: Optional custom metadata.
ZSKit.initiatePurchase(product: USER_SELECTED_PRODUCT) { subsDetail, error in
    // Handle subscription response.
}
```

* * *

## Offers

The SDK supports introductory and promotional offers.

### Introductory Offers

Check eligibility before showing introductory offers.

```swift
// Eligibility for a specific product.
ZSKit.isUserEligibleForIntroductoryOffer(product: SK_PRODUCT_OBJECT)

// Eligibility for a subscription group.
ZSKit.isUserEligibleForIntroductoryOffer(groupId: SUBSCRIPTION_GROUP_ID)
```

If eligible, App Store applies the introductory offer automatically at checkout. Zoho Billing records the subscription with the offer details:

*   **Free trial** - The subscription is created in trial status. Billing starts after the trial period ends.
*   **Pay as you go** - The subscription is created at the discounted price. Billing transitions to regular price after the offer period.
*   **Pay up front** - The subscription is created with upfront payment. The next billing date is calculated based on the offer duration, and regular pricing applies after the offer ends.

### Promotional Offers

Promotional offers require a backend-generated acknowledgement. Use this Zoho Billing endpoint to fetch the signature using your backend system:

#### Request Example

```bash
curl --request GET \
  --url 'https://www.zohoapis.com/billing/v1/appstore/offers/sign?organisation_id=YOUR_ORG_ID&bundle_id=APP_BUNDLE_ID&product_id=PLAN_CODE_TO_APPLY_OFFER&offer_id=PROMOTIONAL_OFFER_ID' \
  --header 'Authorization: Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2'
```

Learn more about [Zoho Billing API documentation](https://www.zoho.com/billing/api/v1/introduction/).

#### Response Example

The response will include the signature, keyID, nonce and timestamp details.

```json
{
    "code": 0,
    "message": "success",
    "data": {
        "signature": "MEUCIQDxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx==",
        "keyID": "ABC1234XYZ",
        "nonce": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
        "timestamp": "1756886400000"
    }
}
```

When a promotional offer is applied, Zoho Billing records the subscription with the offer details:

```swift
ZSKit.initiatePurchase(product: USER_SELECTED_PRODUCT, promotionalOfferDetails: OFFER_DETAILS) { subsDetail, error in
    // Handle subscription response.
    // Zoho Billing records the offer type and applies the pricing accordingly.
}
```

After the offer period expires, the subscription automatically transitions to the regular plan pricing in both Zoho Billing and App Store.

* * *

## Restore a Purchase

Provide a restore option for cases where a purchase completed in App Store but did not sync due to network or transient issues.

```swift
// Restores latest purchase to Zoho Billing.
ZSKit.restorePurchase(customFields: CUSTOM_FIELDS_IF_ANY)
```

If your app supports multiple subscription groups:

*   Restore all purchases:

```swift
ZSKit.restoreAllPurchases(customFields: CUSTOM_FIELDS_IF_ANY)
```

*   Restore a specific purchase:

```swift
// Fetch active transactions first, then restore a selected one.
ZSKit.restoreSubscription(transaction: SELECTED_TRANSACTION, customFields: CUSTOM_FIELDS_IF_ANY)
```

* * *

## Fetch Current Purchase Details from the Store

Use `getCurrentEntitlements` to get active purchases directly from App Store.

```swift
ZSKit.getCurrentEntitlements()
```

* * *

## Clear User Info

Clear SDK user data when a user logs out.

```swift
ZSKit.clearUserInfo()
```