iOS In-App Purchases SDK Implementation

The iOS SDK (ZSInAppPurchaseKit) connects your app to Zoho Billing for subscription lifecycle syncing.

Pro Tip:

Before starting, review Best Practices for SDK Implementation.

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.

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

Initialise the SDK

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

// 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, Map Subscriptions to the Correct Product, and Configure the Correct Data Centre.

Fetch Plans

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

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.

// 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.

// 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

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.

Response Example

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

{
    "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:

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.

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

If your app supports multiple subscription groups:

Restore all purchases:

ZSKit.restoreAllPurchases(customFields: CUSTOM_FIELDS_IF_ANY)

Restore a specific purchase:

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