---
title: Working with subscription group versions
framework: App Store Connect API
role: article
role_heading: Article
path: appstoreconnectapi/working-with-subscription-group-versions
---

# Working with subscription group versions

Manage draft versions of a subscription group’s localized metadata before submitting for App Review.

## Overview

Overview A subscription group version is a draft container for the group’s localized names — the display names and optional custom app names that customers see for the whole subscription group. Group versions carry only localizations; they don’t have review images. Create a version, attach localizations to it, then submit the version through the review submissions workflow. The parent subscription group holds properties that stay stable across versions — its reference name and app relationship — while each version captures the reviewable metadata for a single review cycle. note: The pre-4.4.1 workflow that posts localizations directly to the subscription group (POST /v1/subscriptionGroupLocalizations) 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. Group-level localizations submit to App Review with the subscriptions they belong to. Submit a subscription group version independently only when you change group-level localization without changing any subscription in the group. Understand the version lifecycle A version moves through these states, exposed on SubscriptionGroupVersion/Attributes/state: PREPARE_FOR_SUBMISSION: the version is being edited. Localizations 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/subscriptionGroupVersions (Create a subscription group version). Relate it to the subscription group whose metadata you’re updating: {   "data": {     "type": "subscriptionGroupVersions",     "relationships": {       "subscriptionGroup": {         "data": {           "type": "subscriptionGroups",           "id": "2000036297"         }       }     }   } } 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 optional custom app name with POST /v2/subscriptionGroupLocalizations (Create a subscription group localization). The payload relates the localization to the version, not the parent subscription group: {   "data": {     "type": "subscriptionGroupLocalizations",     "attributes": {       "locale": "en-AU",       "name": "Ukulele Lessons",       "customAppName": "The Best Ukulele Lessons"     },     "relationships": {       "version": {         "data": {           "type": "subscriptionGroupVersions",           "id": "${subscriptionGroupVersionId}"         }       }     }   } } Repeat for each locale you support. To list the localizations attached to a version, use GET /v1/subscriptionGroupVersions/{id}/localizations (List the localizations of a subscription group version). List all versions for a subscription group To see every version on a parent subscription group, use GET /v1/subscriptionGroups/{id}/versions (List the versions of a subscription group). 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/subscriptionGroupVersions/{id} (Read subscription group version information) to watch it continue to IN_REVIEW and then APPROVED or REJECTED.

## See Also

### Managing Subscription Groups

- [Creating auto-renewable subscription groups](appstoreconnectapi/creating-auto-renewable-subscription-groups.md)
- [Subscription Group Versions](appstoreconnectapi/subscription-group-versions.md)
- [Subscription Groups](appstoreconnectapi/subscription-groups.md)
- [Subscription Group Localizations](appstoreconnectapi/subscription-group-localizations.md)
- [Subscription group localizations (v1)](appstoreconnectapi/subscription-group-localizations-v1.md)