--- title: Working with subscription versions framework: App Store Connect API role: article role_heading: Article path: appstoreconnectapi/working-with-subscription-versions --- # Working with subscription versions Manage draft versions of an auto-renewable subscription’s localized metadata and review images before submitting for App Review. ## Overview Overview A subscription version is a draft container that groups the localized metadata and review images that go through App Review together. Create a version, attach localizations and images to it, then submit the version through the review submissions workflow. The parent subscription resource holds properties that stay stable across versions — its product ID, subscription duration, group, and pricing — while each version captures the reviewable metadata for a single review cycle. note: The pre-4.4.1 workflow that posts localizations and images directly to the subscription (POST /v1/subscriptionLocalizations, POST /v1/subscriptionImages) is deprecated as of 4.4.1 but remains available for existing integrations. For guidance on moving to the version-based workflow, see Migrating in-app purchase metadata to v2. Understand the version lifecycle A version moves through these states, exposed on SubscriptionVersion/Attributes/state: PREPARE_FOR_SUBMISSION: the version is being edited. Localizations and images can be added, changed, or removed. READY_FOR_REVIEW: the version is attached to a review submission and awaiting the submission to be marked submitted. WAITING_FOR_REVIEW: the review submission has been submitted and the version is queued. IN_REVIEW: App Review is actively reviewing the version. ACCEPTED or APPROVED: the version passed review. REJECTED or DEVELOPER_REJECTED: the version was rejected by App Review or withdrawn by the developer. REPLACED_WITH_NEW_VERSION: a newer version supersedes this one. Versions are read-only after creation. To change a version’s contents, create a new version. Create a version Create a draft version with POST /v1/subscriptionVersions (Create a subscription version). Relate it to the subscription whose metadata you’re updating: { "data": { "type": "subscriptionVersions", "relationships": { "subscription": { "data": { "type": "subscriptions", "id": "6446671421" } } } } } The response returns the new version’s id and a state of PREPARE_FOR_SUBMISSION. Note the id — every subsequent step references it. Attach a localization to the version Add a localized display name and description with POST /v2/subscriptionLocalizations (Create a subscription localization). The payload relates the localization to the version, not the parent subscription: { "data": { "type": "subscriptionLocalizations", "attributes": { "locale": "en-US", "name": "All Access — Monthly", "description": "Unlimited lessons across every instrument." }, "relationships": { "version": { "data": { "type": "subscriptionVersions", "id": "${subscriptionVersionId}" } } } } } Repeat for each locale you support. To list the localizations attached to a version, use GET /v1/subscriptionVersions/{id}/localizations (List localizations for a subscription version). Attach a review image to the version A subscription version can carry review images that show the promotion image customers see on the App Store product page. Reserve, upload, and commit each image in three steps. Reserve an image with POST /v2/subscriptionImages (Create a subscription image): { "data": { "type": "subscriptionImages", "attributes": { "fileName": "all-access-promo.png", "fileSize": 245670 }, "relationships": { "version": { "data": { "type": "subscriptionVersions", "id": "${subscriptionVersionId}" } } } } } The response returns an id for the image and a set of uploadOperations describing how to PUT the file bytes. Upload the image bytes to the URL from uploadOperations. Then commit the upload with PATCH /v2/subscriptionImages/{id} (Modify a subscription image): { "data": { "type": "subscriptionImages", "id": "${subscriptionImageId}", "attributes": { "uploaded": true } } } Read image metadata with GET /v2/subscriptionImages/{id} (Read subscription image information). Remove an image with DELETE /v2/subscriptionImages/{id} (Delete a subscription image). For more on the reserve-upload-commit pattern, see Uploading Assets to App Store Connect. List all versions for a subscription To see every version on a parent subscription, use GET /v1/subscriptions/{id}/versions (List versions for a subscription). The response includes each version’s state, so you can find the current draft, the most recently approved version, and any versions currently in review. Submit the version Submit a completed version through the review submissions workflow. Create a review submission for the app, add the version as an item, and mark the submission as submitted. For step-by-step instructions, see Submitting subscriptions and subscription groups for App Review. When you mark the submission submitted, the version moves from READY_FOR_REVIEW to WAITING_FOR_REVIEW. Poll GET /v1/subscriptionVersions/{id} (Read subscription version information) to watch it continue to IN_REVIEW and then APPROVED or REJECTED. ## See Also ### Managing Auto-Renewable Subscriptions - [Managing auto-renewable subscriptions](appstoreconnectapi/managing-auto-renewable-subscriptions.md) - [Configuring subscription prices across territories](appstoreconnectapi/configuring-subscription-prices-across-territories.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)