Skip to main content
Zuora Logo

Configure Apple Appstore Connector

Zuora

Configure Apple Appstore Connector

  1. Last updated
  2. Save as PDF

After installing the Zuora to Apple Appstore Sync app, take the following steps to set up the app:

  1. Configure the product rate plan
  2. Add custom field
  3. Create a Zuora account and subscription
  4. Configure the schedule of the Sync

Configure Product Rate Plan

You must ensure the product rate plans in Zuora are configured to match the pricing or free trial periods defined in the Apple app. Each Apple receipt should include only one Zuora subscription to a product. Currently, the Apple Appstore Connector does not support discounts or the use case where multiple products are included in one Apple receipt.

Add Custom Field

Take the following steps to add the custom field for Apple Appstore Connector:

  1. In your Zuora tenant, navigate to Settings > Billing > Manage Custom Fields. 
  2. Click Subscription Fields.
  3. In the Subscription Custom Fields & Relationships ( Non-Indexed ) section, click add new field.
  4. Add a custom field with the following information:
    • Field Type: Picklist
    • Field Label: SourceSystem
    • Picklist Values: Apple
    • (Optional) Description: Custom field for Apple Appstore Connector.
    • Do not select the Required check box and select the UI Read Only check box.

      Note that the SourceSystem custom field should only be created once for all Appstore Connectors, including Amazon, Apple, and Google Play. If the SourceSystem custom field already exists, add Apple to the Picklist values.

  5. Click save to save the field.

Create Zuora Account and Subscription

When an end-user purchases an Apple app, their Apple user credentials are validated. A subscription in Apple App Store is created and a receipt ID is generated after the validation. The Apple app will then make a request to Zuora through the Subscribe API to create the end user’s Zuora subscription ID. The SourceSystem__c custom field is included in the Subscribe request. The subscription ID is then transferred back to the Apple app and aligned with the Apple receipt ID. 

The Apple app will then use the configured Create API request to the Appstore Connector to create the receipt in the Appstore Connector app. A curl request is provided in the Sample curl request (API Token) section in the Settings tab. Use this curl request to send the subscription number and receipt ID in Apple to the Appstore Connector app. 

Note that neither Zuora nor the Appstore Connector app processes any payment. All payments are handled through the Apple App Store. 

 AppleAppstore Connector Flow Chart

Apple Receipts and Zuora Subscriptions

The execution of the Appstore Connector depends on if the term-start and term-end dates of Zuora invoice items match the set period in Apple. You should ensure that the non-renewable subscriptions and their auto-renew settings align with the app's charge periods. Failure to align the subscription charges and the resulting invoice items with the charges on Apple receipts may stop the app from running as expected.

The following table describes the mapping relationships between the receipts in the Apple App Store and Zuora subscriptions:

Apple Receipt Description Zuora Subscription Settings
Auto-renewable Apple Receipts Charges will happen multiple times over the lifetime of Apple receipt.
  • Evergreen subscriptions

       or

  • Termed subscriptions with the Auto Renew field set to yes
Non-renewable (Termed) Apple Receipts Charges such as one-time charges happen only once during the lifetime of the Apple receipt. Termed subscriptions with the Auto Renew field set to no

Example of Invoice in Zuora and Corresponding Apple Receipt

The charge dates of the invoice items should match the receipt date in the corresponding Apple receipt.

Example invoice in Zuora

Example Apple Receipt

Configure Appstore Connector Schedule

  1. Launch the installed Appstore Connector app instance.
  2. Click the Settings tab. 
  3. Complete the schedule details:
    1. Select Apple for Connector Types. If you are using multiple connectors, more than one connector can be selected.
    2. Enter or select a date in the Ignore Invoices Due Before field. The source system will ignore the invoices that were processed before this date. In addition, optionally select the following check boxes as needed:
      • Support Discounts - Allows the connector to correctly parse discount objects.
      • Use Both Date and Time for Cancellations Instead of Exclusively Date - Using both date and time allows subscriptions to be cancelled at the exact date and time instead of just the date. 
    3. Select one of the following days to be used as the payment date from the Payment Date dropdown list:
      • Invoice due date - The day where the invoice is due.
      • Day of Processing - The day where the payment starts processing.
    4. In the Apple section, complete the following configuration:
      1. (Optional) Select the Cancel Test Receipts check box to remove all Apple test receipts from the Apple environment.
      2. Select one of the following subscription cancellation types from the Cancellation Type dropdown list:
        • Specific Date -  Subscriptions are cancelled on a specific date.
        • End of Last Invoice Period - Subscriptions are cancelled at the end of the last invoice period.
        • Blocked - Subscriptions are cancelled because they get blocked.
    5. (Optional) Select the Enable Orders check box if your Zuora tenant uses Orders. If this check box is not selected but the Orders feature is used, the app will not operate as intended. 
      See the Zuora Knowledge Center for more information related to the Orders feature.
    6. Select Other in the Payment Method drop-down list. 
    7. Select the time zone from the Timezone drop-down list. Zuora strongly recommends you to select the same time zone as for your Zuora tenant to avoid payment errors.
    8. In the drop-down list next to Timezone, select the time frame of the schedule and complete the details of the selected time frame. The Timezone field and schedule builder are used to set how frequently the data is synchronized. It is recommended to set a Daily schedule and align the timezone to your Zuora tenant, which can align operations and ensure the app displays the latest data. The Interval field displays the specified schedules as a Cron expression and needs no further configuration.  

      If you have enabled multiple connectors, they will execute based on the same schedule but be processed separately by the Source System identified in the subscription. 

  4. Click Update. 

After the details have been updated, the date and time of the Next Execution will be displayed and the Running status will be updated to Yes.