Omnichannel One-Time Orders for Apple App Store

The Apple App Store integration helps you record in-app purchases for consumable and non-consumable products made on the Apple App Store in Chargebee. Learn more about in-app purchases.

• Consumable: This represents a one-time order that provides users with in-app benefits that can be consumed or depleted over time, such as lives, gems, boosts, or digital tips. Once consumed, the purchased item is no longer available and must be repurchased to obtain its benefits again.

• Non-consumable: This represents a one-time order that provides a permanent benefit to the user and can be purchased once without expiration. This type of purchase is typically used to offer premium features or content that enhance the app's user experience, such as additional filters or cosmetic items in a game.

What You Need To Know

• To monetize digital products/services as one-time orders, you can configure the in-app purchase products to be consumable or non-consumable in the App Store Connect. Visit this page for detailed guidance on various business models the App Store offers.

• You can record in-app purchases made on the Apple App Store in Chargebee by using the record a purchase API. The parameter item_type_at_source represents the type of one-time order, i.e., consumable or non-consumable.

• An Omnichannel One-Time Order is created in Chargebee upon successful purchase recording.

• To test new purchases from the same device, create different Apple sandbox accounts and sign in with those accounts. You may also need to delete and reinstall your app to clear the purchase history associated with a sandbox account.

• Ensure that the prerequisites are completed before attempting to record a purchase in Chargebee and that Chargebee's notifications URL is configured in App Store Connect so that Chargebee can listen to Apple notifications related to one-time orders.

• Unlike Omnichannel subscriptions, there's no state associated with Omnichannel one-time orders, so if a one-time order is cancelled on the App Store, we recommend listening to the event omnichannel_one_time_order_item_cancelled.

Prerequisites

You need to complete these steps to make your app ready for in-app purchases.

Configure in-app purchase products

Configure the consumable or non-consumable in-app products that your app merchandises in App Store Connect. Learn more about configuring in-app purchase products in App Store Connect. If you are a developer building a test app with sample in-app products, you can configure the products in the StoreKit configuration file.

Implement in-app purchases

Apple's StoreKit 2.0 framework offers the entire set of Swift APIs that help you retrieve the in-app purchase products configured in Apple App Store Connect, make a purchase using the purchase method, track the purchase using the account token, and get the purchase and verification result.

Since StoreKit 2.0 does the transaction verification, no additional server verification is needed. So, every time your app receives a transaction from StoreKit 2, the transaction has passed through the verification process, and thus, you can grant the end user access to the paid content.

Go through this WWDC link and Apple developer guide to implement the purchase flow in your app. For every transaction made using the StoreKit 2.0 framework, Apple will return a signed JSON Web Signature (JWS) token. The transaction type contains the signed JWS payload, which represents the signed transaction. You need to pass this signed transaction to Chargebee to record the purchase in Chargebee.

If you are using the deprecated StoreKit 1.0 APIs, make sure that you invoke the record a purchase API using the receipt and product_id. Chargebee will fetch the corresponding transaction_id and will record the one-time order.

Create an Omnichannel One-Time Order

Once you have an active Chargebee test or live site, follow these steps to start recording one-time in-app purchases made on the Apple App Store in Chargebee.

Step 1: Connect the Apple App to Chargebee to generate a unique App ID & Notifications URL

Connect your apps listed in the Apple App Store to Chargebee to record and manage your App Store subscriptions or one-time orders through Chargebee. Once your app is connected, Chargebee will generate a unique App ID that can be used for recording purchases and a unique Notifications URL that can be used to relay the Apple in-app subscription / one time purchase change events to Chargebee.. Learn more.

Step 2: Record an Apple purchase using the App ID and create an Omnichannel One-Time Order.

To view one-time orders made on the Apple App Store in Chargebee, you must record these purchases using the Record a Purchase API. You need the App ID to invoke this API. Learn more.

Step 3: Set Up Notification URL in App Store Connect

Configure the notification URL in App Store Connect to sync the Apple notifications related to one-time orders with Chargebee. Learn more.

Step 4: Subscribe to Omnichannel webhook events

Once Chargebee's notification URL is successfully set in App Store Connect, Chargebee will receive Apple server notifications for cancellation/refund and generate the corresponding omnichannel event, omnichannel_one_time_order_item_cancelled.

View Omnichannel One-Time Orders in Chargebee

As a customer care, marketing, or revenue growth professional, you can use Chargebee's Omnichannel One-Time Orders page to view all the one-time orders. App-specific filters can be applied to view one-time orders corresponding to specific apps. You can click any omnichannel One Time Order ID and access the omnichannel one-time order details page to check the one-time order details.

To view an omnichannel one-time order corresponding to a customer in Chargebee, follow these steps:

1. Log in to your Chargebee site and navigate to Omnichannel.

2. Click on Omnichannel > One Time Orders to access the one-time orders

3. Click on the Omnichannel One Time Order ID to open the one-time order details page.

   1. The Transactions tab shows the transaction ID created in Chargebee and the corresponding transaction ID created in the App Store.
      
   2. The Events tab shows Chargebee's event ID, type, triggering time, and status.
      

View Apple In-App Purchases in Chargebee

As an app developer, you may want to track the status of a one-time order that you attempted to record in Chargebee and view the details of the transaction made on the Apple App Store. The Purchases page in Chargebee displays all Apple one-time orders that you attempted to record under the respective status tab, with the purchase type as One-Time Order.

All the successfully recorded one-time orders will appear under the Succeeded tab, and purchases that failed recording in Chargebee will appear under the Failed tab, along with the error details. Purchases for which recording is in process will appear under the In process tab, and the ones that Chargebee ignores will appear under the Ignored tab with a reason.

Click on a successfully recorded purchase to view the purchase details and events related to that purchase.

To view in-app purchases and the details of the purchase in Chargebee, follow these steps:

1. Log in to your Chargebee site and navigate to Apps on the left menu.

2. Click the Apple App Store.

3. Click on the application for which you want to view in-app purchases.

4. You will view all the purchases split under four statuses: Succeeded, In process, Failed, and Ignored. The purchase type column field indicates whether the purchase is a Subscription or One-Time Order.

   

5. Click the purchase for which you want to check the events

   

Limitations

1. Apple also offers non-renewing subscriptions, through which users can purchase access to services or content for a limited duration, such as a season pass to streaming content. Chargebee currently doesn't support this.

2. In-app purchase items configured in the Apple store cannot be mapped to any product catalog item in Chargebee. So entitlements cannot be associated with them.

3. In the UI, there's no timeline view available for one-time orders, as these purchases don't undergo frequent changes.

4. There's no status associated with a one-time order, so if a one-time order is cancelled or a refund is issued, then you need to rely on the omnichannel_one_time_order_item_cancelled event to check if the purchase is cancelled.

5. Omnichannel one-time orders will not appear under the Customers tab in the Chargebee UI.