--- title: Configuring subscription prices across territories framework: App Store Connect API role: article role_heading: Article path: appstoreconnectapi/configuring-subscription-prices-across-territories --- # Configuring subscription prices across territories Set plan types and equalized prices for an auto-renewable subscription with the App Store Connect API. ## Overview Overview The App Store Connect API lets you choose which plan type — monthly or up-front — is available for an auto-renewable subscription in each territory, and then set a consistent price for that subscription everywhere you offer it. Rather than calculating a comparable price for every territory yourself, you can read the adjusted equalizations of a base price point and reuse the equalized price points the API returns. This workflow assumes you already created a subscription in a subscription group. To create one, see Managing auto-renewable subscriptions. Review App Store Connect API usage To manage auto-renewable subscriptions with the App Store Connect API, you need to understand key concepts for using the API. If you’re new to using the App Store Connect API, make sure to read the documentation in the Essentials section of App Store Connect API and learn how to create API keys, generate JWTs, identify rate limits, and more. To configure subscription plan types and prices, be sure you have one of the following user roles: ACCOUNT_HOLDER ADMIN APP_MANAGER For the full list of App Store Connect user roles, see UserRole and Program Roles. Plan your pricing Before you set prices, decide which plan type you offer in each territory and which territory’s price anchors the rest. A subscription plan type controls how a customer pays for the subscription period: MONTHLY — the customer pays month to month over a 12-month commitment. UPFRONT — the customer pays the full subscription price up front. For the complete definition, see SubscriptionPlanType. Equalization keeps a subscription’s price comparable across currencies. When you pick a price in your base territory, the API can return the equalized price point in every other territory — the closest local-currency equivalent. Adjusted equalizations extend this to plan types, so the equalized prices stay consistent whether a territory offers the monthly or the up-front plan. Map out your offering before you start. The following example plans a single subscription across three territories. | | | | | | | | Set plan type availability Declare which plan type is available for the subscription in each territory by using POST /v1/subscriptionPlanAvailabilities (Create a subscription plan availability). The request requires a planType attribute and relationships to the subscription and the availableTerritories the plan type applies to. Here’s an example payload: { "data": { "type": "subscriptionPlanAvailabilities", "attributes": { "planType": "MONTHLY", "availableInNewTerritories": true }, "relationships": { "subscription": { "data": { "type": "subscriptions", "id": "6447497832" } }, "availableTerritories": { "data": [ { "type": "territories", "id": "USA" }, { "type": "territories", "id": "CAN" }, { "type": "territories", "id": "JPN" } ] } } } } To review or change which territories offer a plan type later, use List plan availabilities for a subscription to list the plan availabilities on a subscription, then Replace the available territories for a subscription plan availability to update the territories. For more detail, see Subscription plan availability. Look up a base price point Choose the base price for your subscription in your anchor territory, then look up the price point ID that represents it. Use GET /v1/subscriptions/{id}/pricePoints (List all price points for a subscription) and filter by territory to keep the response small. GET /v1/subscriptions/6447497832/pricePoints?filter[territory]=USA&include=territory&limit=200 tip: Filter the endpoint by territory to reduce the amount of data you review. Always include filter[territory] on this endpoint — it’s required in a future release. Here’s an example response, truncated for clarity: { "data": [ { "type": "subscriptionPricePoints", "id": "eyJzIjoiNjQ0NzQ5NzgzMiIsInQiOiJVU0EiLCJwIjoiMTAxMjcifQ", "attributes": { "customerPrice": "9.99", "proceeds": "6.99" }, "relationships": { "territory": { "data": { "type": "territories", "id": "USA" } } } } ] } Note the id of the price point whose customerPrice matches the base price you planned. You use it as the base price point in the next step. Equalize the price across territories With your base price point, read its adjusted equalizations to get the comparable price point in every other territory. Use GET /v1/subscriptionPricePoints/{id}/adjustedEqualizations (List adjusted equalizations for a subscription price point), where {id} is the base price point ID from the previous step. note: Use this endpoint with filters to identify a specific adjusted equalization. Provide the filter[upfrontPricePointId] and filter[planType] query parameters: GET /v1/subscriptionPricePoints/{pricePointId}/adjustedEqualizations?filter[upfrontPricePointId]=$id&filter[planType]=MONTHLY Add include=territory so each returned price point carries its territory, and filter by territory when you only need a subset: GET /v1/subscriptionPricePoints/eyJzIjoiNjQ0NzQ5NzgzMiIsInQiOiJVU0EiLCJwIjoiMTAxMjcifQ/adjustedEqualizations?filter[upfrontPricePointId]=eyJzIjoiNjQ0NzQ5NzgzMiIsInQiOiJVU0EiLCJwIjoiMTAxMjcifQ&filter[planType]=MONTHLY&include=territory&limit=200 Here’s an example response, truncated for clarity: { "data": [ { "type": "subscriptionPricePoints", "id": "eyJzIjoiNjQ0NzQ5NzgzMiIsInQiOiJDQU4iLCJwIjoiMTAxNDIifQ", "attributes": { "customerPrice": "12.99", "proceeds": "9.09" }, "relationships": { "territory": { "data": { "type": "territories", "id": "CAN" } } } }, { "type": "subscriptionPricePoints", "id": "eyJzIjoiNjQ0NzQ5NzgzMiIsInQiOiJKUE4iLCJwIjoiMTAxNTUifQ", "attributes": { "customerPrice": "1500", "proceeds": "1050" }, "relationships": { "territory": { "data": { "type": "territories", "id": "JPN" } } } } ] } Each entry is the equalized price point for one territory. Note the id of each price point — you assign these when you set prices. Set prices per territory Assign a price point to the subscription in each territory by using POST /v1/subscriptionPrices (Create a subscription price change). The request requires relationships to the subscription and the subscriptionPricePoint. Set startDate to null to apply the price immediately, or to a future date to schedule the change. Include planType to match the plan you made available. important: Review price changes carefully. Once a price change goes into effect, you can’t revert it. For guidance on price changes, see App Store Connect for iPhone and iPad. Here’s an example payload that sets the equalized Canadian price point: { "data": { "type": "subscriptionPrices", "attributes": { "startDate": null, "planType": "MONTHLY" }, "relationships": { "subscription": { "data": { "type": "subscriptions", "id": "6447497832" } }, "subscriptionPricePoint": { "data": { "type": "subscriptionPricePoints", "id": "eyJzIjoiNjQ0NzQ5NzgzMiIsInQiOiJDQU4iLCJwIjoiMTAxNDIifQ" } } } } } Repeat this call for each territory, using the equalized price point ID you noted for that territory. There’s no bulk endpoint that applies equalized prices in a single call. Verify your prices Confirm the prices you set by using GET /v1/subscriptions/{id}/prices (List all prices for a subscription). Filter by plan type and territory to check a specific configuration. GET /v1/subscriptions/6447497832/prices?filter[planType]=MONTHLY&filter[territory]=CAN&include=subscriptionPricePoint,territory If you set a price you no longer want — for example, a scheduled change that hasn’t taken effect — remove it with DELETE /v1/subscriptionPrices/{id} (Delete subscription prices). For more information about subscription price points and prices, see Subscription price points and subscription prices. ## See Also ### Managing Auto-Renewable Subscriptions - [Managing auto-renewable subscriptions](appstoreconnectapi/managing-auto-renewable-subscriptions.md) - [Working with subscription versions](appstoreconnectapi/working-with-subscription-versions.md) - [Querying adjusted subscription price equalizations](appstoreconnectapi/querying-adjusted-subscription-price-equalizations.md) - [Subscription Versions](appstoreconnectapi/subscription-versions.md) - [Subscriptions](appstoreconnectapi/subscriptions.md) - [Subscription Localizations](appstoreconnectapi/subscription-localizations.md) - [Subscription localizations (v1)](appstoreconnectapi/subscription-localizations-v1.md) - [Subscription price points and subscription prices](appstoreconnectapi/subscription-price-points-and-subscription-prices.md) - [Subscription images](appstoreconnectapi/subscription-images.md) - [Subscription images (v1)](appstoreconnectapi/subscription-images-v1.md) - [Subscription availability](appstoreconnectapi/subscription-availability.md) - [Subscription plan availability](appstoreconnectapi/subscription-plan-availability.md) - [Billing Grace Periods](appstoreconnectapi/billing-grace-periods.md)