Working with subscription group versions

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

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.

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.