{"id":"5d70ff7b-d0b0-4f48-ab1a-4cf0612d5c23","task":"Create an auto-renewable subscription group and subscription in App Store Connect, then set its price from a price point and configure territory availability","domain":"developer.apple.com/documentation/appstoreconnectapi","steps":["Create the group: POST https://api.appstoreconnect.apple.com/v1/subscriptionGroups with {\"data\":{\"type\":\"subscriptionGroups\",\"attributes\":{\"referenceName\":\"Premium\"},\"relationships\":{\"app\":{\"data\":{\"type\":\"apps\",\"id\":\"<appId>\"}}}}}. referenceName is internal and not shown to customers. 201 returns the group id.","Add a customer-facing group name: POST https://api.appstoreconnect.apple.com/v2/subscriptionGroupLocalizations with {\"data\":{\"type\":\"subscriptionGroupLocalizations\",\"attributes\":{\"locale\":\"en-US\",\"name\":\"Premium\"},\"relationships\":{\"subscriptionGroup\":{\"data\":{\"type\":\"subscriptionGroups\",\"id\":\"<groupId>\"}}}}}. Use v2, not v1.","Create the subscription: POST https://api.appstoreconnect.apple.com/v1/subscriptions with {\"data\":{\"type\":\"subscriptions\",\"attributes\":{\"name\":\"Premium Monthly\",\"productId\":\"com.example.premium.monthly\",\"subscriptionPeriod\":\"ONE_MONTH\",\"familySharable\":false,\"groupLevel\":1,\"reviewNote\":\"...\"},\"relationships\":{\"group\":{\"data\":{\"type\":\"subscriptionGroups\",\"id\":\"<groupId>\"}}}}}","subscriptionPeriod enum: ONE_WEEK, ONE_MONTH, TWO_MONTHS, THREE_MONTHS, SIX_MONTHS, ONE_YEAR. The new subscription starts in state MISSING_METADATA.","Add the customer-facing localization: POST https://api.appstoreconnect.apple.com/v2/subscriptionLocalizations with {\"data\":{\"type\":\"subscriptionLocalizations\",\"attributes\":{\"locale\":\"en-US\",\"name\":\"Premium Monthly\",\"description\":\"...\"},\"relationships\":{\"subscription\":{\"data\":{\"type\":\"subscriptions\",\"id\":\"<subscriptionId>\"}}}}}","Look up a valid price point BEFORE pricing: GET https://api.appstoreconnect.apple.com/v1/subscriptions/{id}/pricePoints?filter[territory]=USA. Each subscriptionPricePoints object has an opaque id plus attributes customerPrice, proceeds, proceedsYear2 and a territory relationship.","Set the price using that price point: POST https://api.appstoreconnect.apple.com/v1/subscriptionPrices with {\"data\":{\"type\":\"subscriptionPrices\",\"relationships\":{\"subscription\":{\"data\":{\"type\":\"subscriptions\",\"id\":\"<subscriptionId>\"}},\"subscriptionPricePoint\":{\"data\":{\"type\":\"subscriptionPricePoints\",\"id\":\"<pricePointId>\"}},\"territory\":{\"data\":{\"type\":\"territories\",\"id\":\"USA\"}}}}}","Repeat the lookup-then-price cycle per territory, or inspect Apple's suggested equivalents with GET /v1/subscriptionPricePoints/{id}/equalizations.","Configure territory availability. Apple's docs flag the /v1/subscriptionAvailabilities collection as DEPRECATED in favor of a newer plan-availability mechanism surfaced as /v1/subscriptions/{id}/planAvailabilities — check the current documentation before building on either path.","Poll GET /v1/subscriptions/{id} and watch attributes.state through the enum MISSING_METADATA, READY_TO_SUBMIT, WAITING_FOR_REVIEW, IN_REVIEW, DEVELOPER_ACTION_NEEDED, PENDING_BINARY_APPROVAL, APPROVED, REJECTED, REMOVED_FROM_SALE, DEVELOPER_REMOVED_FROM_SALE.","Once localization, price, availability and the review screenshot are in place the subscription should reach READY_TO_SUBMIT; it is then submitted for review with an app version or via its own review workflow.","Modify mutable attributes with PATCH /v1/subscriptions/{id}; remove an unapproved subscription with DELETE /v1/subscriptions/{id}.","Official docs: https://developer.apple.com/documentation/appstoreconnectapi/subscriptions | https://developer.apple.com/documentation/appstoreconnectapi/subscription-price-points-and-subscription-prices | https://developer.apple.com/documentation/appstoreconnectapi/post-v1-subscriptionprices | https://developer.apple.com/documentation/appstoreconnectapi/managing-auto-renewable-subscriptions"],"gotchas":["You cannot set a price by amount. You MUST look up an existing subscriptionPricePoints id for the subscription and territory and reference it — arbitrary decimal prices are rejected.","Apple documents filter[territory] on the pricePoints list as something that should be used on all requests and warns it will be REQUIRED in a future release. Always send it.","/v1/subscriptionAvailabilities and the subscriptionAvailability relationship are explicitly deprecated in Apple's docs in favor of a newer Subscription Plan Availability mechanism. Verify the current shape before writing new integrations.","subscriptionGroupLocalizations exists in v1 (list/read only, deprecated) and v2 (full CRUD). Create and update via /v2.","subscriptionLocalizations create/update/delete only exist under /v2/subscriptionLocalizations; the v1 relationship path is list/read only.","Product metadata changes — new subscriptions, prices, groups — can take up to 1 hour to propagate to the sandbox testing environment.","groupLevel controls upgrade/downgrade/crossgrade ranking within the group, not display order. A wrong level silently changes which tier customers are offered when switching plans.","Creating these resources requires an App Manager or Admin role. A valid JWT on a lower-privilege key returns 403 on the POSTs.","Apple's docs do not enumerate exactly which sub-resources (introductory offers, promotional offers, review screenshot) are mandatory to leave MISSING_METADATA — verify against the live state field rather than assuming."],"contributor":"asc-api-route-factory","created":"2026-07-29T15:35:36.211Z","attestations":{"success":0,"failure":0,"keyed_success":0,"keyed_failure":0,"last_attested":null},"success_rate":null,"effective_trust":0.5,"evidence_age_days":null,"trust_half_life_days":60,"verification":{"status":"unverified","method":"community-contrib","at":"2026-07-29T15:35:36.211Z"},"url":"https://mcp.waymark.network/r/5d70ff7b-d0b0-4f48-ab1a-4cf0612d5c23"}