Handling subscription price changes

Overview

The Advanced Commerce API provides a standard UI to facilitate price increases for subscriptions and manage the subscriber consent process.

Implement the Advanced Commerce Subscription price change API

Use the Change Subscription Price endpoint in the Advanced Commerce API (ACA) to initiate a price change for an individual subscription item. The UI the framework provides manages all of the necessary interactions and communication with a person using your app, including:

• Consent management for price increases.

• Notifications about price increases when the price increase doesn’t requite explicit consent.

• A standard UI sheet that App Store displays to obtain explicit user consent, if required, or an acknowledgment of the price increase if explicit consent isn’t required. Examples of these sheets and an explanation of the information they display about your app and the subscription are shown below.

[Image]

[Image]

Understand consent management and price change communication

The App Store checks if a price increase requires consent, and follows different paths depending on whether a subscriber needs to explicitly consent to a price increase or not.

Follow the consent-needed path

The App Store requests explicit consent from the subscriber if the price increase meets any of the following criteria:

• The subscriber is located in a region that requires consent for any price changes. For more information about these regions, see Auto-renewable subscription price increase thresholds.

• The price increase is:

  • More than 50 percent of the current price; and

  • The difference in price exceeds 5 United States Dollars (USD) per period for nonannual subscriptions, or 50 USD per year for annual subscriptions. International equivalents for prices not in USD are based on current exchange rates with specific thresholds subject to change based on changes in taxes or foreign exchange rates.

• The subscriber had a price increase for the same subscription within the past 12 months.

• The subscriber converts from trials or offers in South Korea. In these cases, Apple collects consent via email, in-app sheets, or push notifications. The timing and frequency of these communications may differ from those shown for standard subscription price increases, as noted in Consent for subscription offer conversions.

When conditions require consent, the App Store notifies subscribers via email, price increase sheet, and push notification, according to the timelines below. If a subscriber doesn’t take any action, the App Store continues to request consent no more than once per week for each method. You can’t raise the price until you receive the subscriber’s consent.

[Image]

Follow the consent not-needed path

When a price increase doesn’t need the subscriber’s consent, the App Store only notifies subscribers about the new price. When the App Store increases the price of multiple items within a bundle, none of which require consent, it uses a single API request so the subscriber receives a summary of the price increases. The App Store combines notifications into a single communication per method (a single email, one price increase sheet, and a single push notification).

The App Store uses the following communication methods and timelines to notify subscribers:

Email

For all subscription durations, the App Store sends an email 27 days before the renewal date. Note that for weekly subscriptions, the App Store calls the Change Subscription Price endpoint on the fourth consecutive renewal to increase the price.

Price increase sheet

The App Store displays a price increase sheet at the first app launch after the subscriber enters the notice period.

Push notification

The App Store displays a push notification seven days before the renewal date if the subscriber hasn’t viewed the price increase sheet in-app.

Understand change subscription conditions and limitations

Several conditions may affect your ability to change or update a subscription, including:

• During the price increase window, the renewal uses the increased price that the developer has specified using Change Subscription Price if you make any of the following changes to the subscription:

  • Add an item

  • Remove an item

  • Change an item

  • Resubscribe using the Subscription Modification API or the Subscription Reactivation API

• If the subscription status is auto-renew = false or if the subscription is in a grace period or billing retry state, you can’t call the Change Subscription Price endpoint.

• If the SubscriptionPriceChangeItem is currently in the offer period, you can’t call Change Subscription Price.

Understand interactions with other ACA operations

Several conditions can affect your ability to update a subscription. There may be specific interactions and rules that apply to price increases, depending on which Advanced Commerce API you need to use.

If you need to reactivate items, call the SubscriptionReactivateInAppRequest API. The following conditions apply to reactivations:

• If the App Store communicated the price increase, it reactivates the items you provide through the items key in the properties you supply to the SubscriptionReactivateInAppRequest request at the higher price. Failing to explicitly reactivate an item doesn’t result in the App Store activating the higher price because the App Store needs to communicate the price increase and receive consent through the normal process.

• If the App Store hasn’t communicated the price increase, it schedules the price increase communications for the next eligible date.

If you need to modify a subscription, call the SubscriptionModifyInAppRequest API. Price increases interact with the ACA in a specific way depending on if the call resets or retains the billing cycle.

If the price increase takes place during a retain billing cycle, the following rules apply:

• If the App Store communicated the price increase:

  • If the price increase is pending consent, the Payment Sheet shows the higher price, and the user must consent to the price increase via the in-app sheet that appears, or via Manage Subscriptions.

  • If the subscriber consented to the price increase, or the price increase doesn’t require consent, the Payment Sheet shows the higher price.

  • If the subscriber declined the price increase, the item doesn’t appear in the Payment Sheet.

• If the item’s SKU is changing to a different product SKU (such as from SKU BASIC to SKU PREMIUM), the change invalidates the price increase because the new SKU represents a different product.

• When the App Store sends an offer with an item subject to a price increase, it’s a special consideration; in this case, you send the higher price of the item, and the App Store reschedules the price increase for after the offer period completes, at which point, the item renews at the higher price.

If the price increase takes place during a reset billing cycle, the following rules apply:

• If the App Store hasn’t communicated the price increase, the price increase is invalidated.

• If the the App Store communicated the price increase, the App Store applies the new price only if the item is sent with the higher price, using the SubscriptionModifyChangeItem.

  • As described above, changing the item to a different product (such as changing from BASIC SKU to a Premium SKU) invalidates the price increase, as the item represents a different product.

If you need to change a subscription’s metadata, call the Change Subscription Metadata. Metadata-only changes, such as changing the SKU from SKU A to SKU B, preserve the price increase because it isn’t a change in product, but rather a change to the product SKU.

If you need to call the ACA Migration API to migrate a subscription that a subscriber purchased through In-App Purchase to a subscription you manage using the Advanced Commerce API, the following rules apply:

• If the In-App purchase product has a pending price increase through App Store Connect, the App Store doesn’t allow the migration if it already communicated the price increase to the subscriber.

• The App Store doesn’t allow migrations if the item is currently subject to a price increase, and the App Store already sent price increase communications to the subscriber.

• If there’s an upcoming price increase, the App Store migrates the pending price increase as well.

Understand price increase status and update values

The following table describes the meaning of price increase status values:

The following table describes the notifications and status values for a subscription price change item that requires consent:

The following table describes the notifications and status values for a subscription price change item that doesn’t require consent:

The following table describes the notifications and status values for a subscription price change item that decreases a price:

Understand conditional cancellations and dependent SKUs

To create a contingency for a situation in which a person doesn’t agree to a price increase and the App Store cancels other bundled services (the “dependent SKUs”), you can provide an array of the SKUs through the dependentSKUs property. If the price increase requires a person’s consent, and they don’t consent to the price increase (through a cancellation from the Manage Subscriptions view, or by failing to consent before the renewal date), the App Store cancels the dependent SKUs.

Test price increases in the sandbox

To test subscription price increases, call the Change Subscription Price API in the sandbox to test the API responses. The sandbox environment — and TestFlight — support the full price increase cycle, with the exception of the email and push notifications. The in-app sheet still appears, and price increase management appears on the Manage Subscriptions page.

You can test granting consent or declining a price increase through the in-app sheet or by navigating to the Manage Subscription page in the sandbox. For more information, see Testing disabling auto-renew.

In the sandbox, the first renewal after calling Change Subscription Price uses the existing price to assist in testing states prior to when the App Store communicates the price increase. After the first renewal, the App Store simulates communicating the price increase for the next appropriate renewal.

See Also

Tax codes and pricing

• Specifying prices for Advanced Commerce SKUs
• Choosing tax codes for your SKUs