Creating auto-renewable subscription groups

Overview

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

To manage auto-renewable subscriptions with the App Store Connect API, you need to understand key concepts for using the API. If you’re new to using the App Store Connect API, make sure to read the documentation in the Essentials section of App Store Connect API and learn how to create API keys, generate JWTs, identify rate limits, and more.

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 and Program 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) 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:

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

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.

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) with a payload.

Here’s an example payload:

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

Here’s an example response, truncated for clarity:

{
  "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 your subscription group localization

Your localized subscription group name shows up in your app when a user goes through the process of reviewing or purchasing your auto-renewable subscription. To add a localization to your subscription group, you need the id of the subscription group from the previous step.

Use POST /v1/subscriptionGroupLocalizations (Create a Subscription Group Localization) with a payload that specifies the localized name of the subscription group, the locale that you’re adding, and an optional custom app name. Depending on your app and subscriptions, you might need to add many localizations. If that’s the case, you can add many in one call to /v1/subscriptionGroupLocalizations.

Here’s an example payload:

{
  "data": {
    "type": "subscriptionGroupLocalizations",
    "attributes": {
      "name": "Ukulele Lessons",
      "locale": "en-AU",
      "customAppName": "The Best Ukulele Lessons"
    },
    "relationships": {
      "subscriptionGroup": {
        "data": {
          "type": "subscriptionGroups",
          "id": "2000036297"
        }
      }
    }
  }
}

After you configure your subscription group, create your subscription following the steps in Managing auto-renewable subscriptions.

See Also

Managing Subscription Groups

• Subscription Groups
• Subscription Group Localizations