<!--
{
  "documentType" : "article",
  "framework" : "AppStoreConnectAPI",
  "identifier" : "/documentation/AppStoreConnectAPI/creating-auto-renewable-subscription-groups",
  "metadataVersion" : "0.1.0",
  "role" : "article",
  "title" : "Creating auto-renewable subscription groups"
}
-->

# Creating auto-renewable subscription groups

Configure subscription groups with the App Store Connect API.

## Discussion

The App Store Connect API lets you create and configure auto-renewable subscriptions for your app. After you create an auto-renewable subscription, you can add metadata, such as a display name, description, and duration. You can also choose your subscription pricing, create promotional and introductory offers, and set up subscription offer codes. When your app is fully configured, you can submit your subscription for review. After you receive approval, you can make pricing changes and edit some metadata for your subscription.

### Review App Store Connect API usage

If you’re new to the App Store Connect API, start with [Creating API Keys for App Store Connect API](/documentation/AppStoreConnectAPI/creating-api-keys-for-app-store-connect-api), [Generating Tokens for API Requests](/documentation/AppStoreConnectAPI/generating-tokens-for-api-requests), and [Identifying Rate Limits](/documentation/AppStoreConnectAPI/identifying-rate-limits).

To create and manage auto-renewable subscriptions, 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`](/documentation/AppStoreConnectAPI/UserRole) and [Program Roles](https://developer.apple.com/support/roles).

### Plan your subscription offerings

Before you get started with creating your subscription, first identify which app to include this subscription in. To get the Apple ID of the app, use `GET /v1/apps` ([`List apps`](/documentation/AppStoreConnectAPI/GET-v1-apps)) and search the resulting pages for the name of the app you want to use. In the response, make note of the `id` of that app, which appears in the following format:

```json
{
"data" : [ {
"type" : "apps",
"id" : "525463029",
....
```

> Tip:
> You can also get the Apple ID of the app in App Store Connect.

To arrange your subscription groups, make sure to map out all your offerings clearly. The following table shows an example for planning your subscriptions in a subscription group. The example uses subscriptions for a series of ukulele lessons with different levels of instructor feedback and detail, available for various time periods.

|Subscription Name       |Duration|Level of Detail (1 is greatest)|Price (in USD)|
|------------------------|--------|-------------------------------|--------------|
|All Access              |1 Month |1                              |24.99         |
|All Access              |1 Year  |1                              |149.99        |
|Ukulele Beginner Lessons|1 Month |3                              |9.99          |
|Ukulele Beginner Lessons|1 Year  |3                              |49.99         |
|Ukulele Advanced Lessons|1 Month |2                              |19.99         |
|Ukulele Advanced Lessons|1 Year  |2                              |99.99         |

### Create your subscription group

After you plan your subscription offerings, create a subscription group, which is the container for your subscriptions. You can create your subscription group by using `POST /v1/subscriptionGroups` ([`Create a subscription group`](/documentation/AppStoreConnectAPI/POST-v1-subscriptionGroups)) with a payload.

Here’s an example payload:

```json
{
  "data": {
    "type": "subscriptionGroups",
    "attributes": {
      "referenceName": "Ukulele Lessons"
    },
    "relationships": {
      "app": {
        "data": {
          "type": "apps",
          "id": "6446148572"
        }
      }
    }
  }
}
```

> Note:
> The `referenceName` field is internal and isn’t displayed to people. Use a descriptive string that’s useful for your own organization and recognition purposes.

Here’s an example response, truncated for clarity:

```json
{
  "data" : {
    "type" : "subscriptionGroups",
    "id" : "2000036297",
    "attributes" : {
      "referenceName" : "Ukulele Lessons"
    },
```

The response contains an `id` field in the primary `data` object. You need this ID for subsequent steps.

### Create a version for your subscription group

Localized names for a subscription group live on a *subscription group version* — a draft container for the metadata that goes through App Review together. Create a version first, then attach localizations to it. 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.

Create a draft version with `POST /v1/subscriptionGroupVersions` ([`Create a subscription group version`](/documentation/AppStoreConnectAPI/POST-v1-subscriptionGroupVersions)), relating it to the subscription group you just created:

```json
{
  "data": {
    "type": "subscriptionGroupVersions",
    "relationships": {
      "subscriptionGroup": {
        "data": {
          "type": "subscriptionGroups",
          "id": "2000036297"
        }
      }
    }
  }
}
```

Note the version `id` in the response. You use it to attach localizations in the next step.

### Create your subscription group localization

Your localized subscription group name shows up in your app when someone reviews or purchases your auto-renewable subscription. To add a localization, use `POST /v2/subscriptionGroupLocalizations` ([`Create a subscription group localization`](/documentation/AppStoreConnectAPI/POST-v2-subscriptionGroupLocalizations)) with a payload that specifies the localized name of the subscription group, the locale, and an optional custom app name. The payload relates the localization to the *version* — not the parent subscription group.

Here’s an example payload:

```json
{
  "data": {
    "type": "subscriptionGroupLocalizations",
    "attributes": {
      "name": "Ukulele Lessons",
      "locale": "en-AU",
      "customAppName": "The Best Ukulele Lessons"
    },
    "relationships": {
      "version": {
        "data": {
          "type": "subscriptionGroupVersions",
          "id": "${subscriptionGroupVersionId}"
        }
      }
    }
  }
}
```

Add each locale you support with its own `POST`. To list every localization attached to a version, use `GET /v1/subscriptionGroupVersions/{id}/localizations` ([`List the localizations of a subscription group version`](/documentation/AppStoreConnectAPI/GET-v1-subscriptionGroupVersions-_id_-localizations)). To list every version on the parent subscription group, use `GET /v1/subscriptionGroups/{id}/versions` ([`List the versions of a subscription group`](/documentation/AppStoreConnectAPI/GET-v1-subscriptionGroups-_id_-versions)).

After you configure your subscription group, create your subscription following the steps in [Managing auto-renewable subscriptions](/documentation/AppStoreConnectAPI/managing-auto-renewable-subscriptions).

---

Copyright &copy; 2026 Apple Inc. All rights reserved. | [Terms of Use](https://www.apple.com/legal/internet-services/terms/site.html) | [Privacy Policy](https://www.apple.com/privacy/privacy-policy)