Subscriptions API

Create and manage auto-renewable subscriptions, subscription groups, introductory offers, and promotional offers.

Subscriptions are organized into subscription groups. Each group can contain multiple subscription tiers (e.g., monthly, annual) that users can upgrade or downgrade between.

Get all subscription groups and their subscriptions for a project.

GET /subscriptions/groups

Authentication

Requires API key with Authorization: Bearer <api_key> header

URL Parameters

Name	Type	Required	Description
`projectId`	`string`	Yes	The project ID

Response Example

{
  "groups": [
    {
      "id": "group_abc123",
      "referenceName": "Premium Access",
      "appStoreId": "12345678",
      "subscriptions": [
        {
          "id": "sub_xyz",
          "productId": "com.app.premium_monthly",
          "name": "Premium Monthly",
          "subscriptionPeriod": "ONE_MONTH",
          "groupLevel": 1
        },
        {
          "id": "sub_abc",
          "productId": "com.app.premium_annual",
          "name": "Premium Annual",
          "subscriptionPeriod": "ONE_YEAR",
          "groupLevel": 2
        }
      ]
    }
  ]
}

Create a new subscription group.

POST /subscriptions/groups

Authentication

Requires API key with Authorization: Bearer <api_key> header

Request Body

Name	Type	Required	Description
`projectId`	`string`	Yes	The project ID
`referenceName`	`string`	Yes	Internal reference name for the group

Response Example

{
  "success": true,
  "group": {
    "id": "group_abc123",
    "referenceName": "Premium Access",
    "syncStatus": "pending_creation"
  }
}

Create a new auto-renewable subscription within a group.

POST /subscriptions

Authentication

Requires API key with Authorization: Bearer <api_key> header

Request Body

Name	Type	Required	Description
`projectId`	`string`	Yes	The project ID
`groupId`	`string`	Yes	The subscription group ID
`productId`	`string`	Yes	Unique product identifier
`name`	`string`	Yes	Display name for the subscription
`subscriptionPeriod`	`string`	Yes	ONE_WEEK, ONE_MONTH, TWO_MONTHS, THREE_MONTHS, SIX_MONTHS, or ONE_YEAR
`groupLevel`	`number`	No	Service level within group (1 = highest tier) (default: `1`)
`familyShareable`	`boolean`	No	Allow family sharing (default: `false`)

Get detailed information about a subscription including localizations and offers.

GET /subscriptions/:subId

Authentication

Requires API key with Authorization: Bearer <api_key> header

URL Parameters

Name	Type	Required	Description
`projectId`	`string`	Yes	The project ID

Set an introductory offer for new subscribers.

POST /subscriptions/:subId/intro-offer

Authentication

Requires API key with Authorization: Bearer <api_key> header

Request Body

Name	Type	Required	Description
`projectId`	`string`	Yes	The project ID
`offerMode`	`string`	Yes	FREE_TRIAL, PAY_UP_FRONT, or PAY_AS_YOU_GO
`duration`	`string`	Yes	Offer duration (e.g., P1W for 1 week, P1M for 1 month)
`territories`	`string[]`	No	Territory codes (all territories if not specified)

Response Example

{
  "success": true,
  "introOffer": {
    "offerMode": "FREE_TRIAL",
    "duration": "P1W",
    "territories": ["USA", "GBR", "DEU"]
  }
}

Remove the introductory offer from a subscription.

DELETE /subscriptions/:subId/intro-offer

Authentication

Requires API key with Authorization: Bearer <api_key> header

URL Parameters

Name	Type	Required	Description
`projectId`	`string`	Yes	The project ID

Get all promotional offers for a subscription.

GET /subscriptions/:subId/offers

Authentication

Requires API key with Authorization: Bearer <api_key> header

URL Parameters

Name	Type	Required	Description
`projectId`	`string`	Yes	The project ID

Response Example

{
  "offers": [
    {
      "id": "offer_abc",
      "name": "Win-back Offer",
      "offerCode": "COMEBACK20",
      "offerMode": "PAY_AS_YOU_GO",
      "duration": "P3M",
      "numberOfPeriods": 3
    }
  ]
}

Create a promotional offer with optional offer code.

POST /subscriptions/:subId/offers

Authentication

Requires API key with Authorization: Bearer <api_key> header

Request Body

Name	Type	Required	Description
`projectId`	`string`	Yes	The project ID
`name`	`string`	Yes	Internal name for the offer
`offerCode`	`string`	No	Customer-facing offer code
`offerMode`	`string`	Yes	FREE_TRIAL, PAY_UP_FRONT, or PAY_AS_YOU_GO
`duration`	`string`	Yes	Offer duration
`numberOfPeriods`	`number`	No	Number of periods for PAY_AS_YOU_GO (default: `1`)

AI-translate subscription name and description to target locales.

POST /subscriptions/translate

Authentication

Requires API key with Authorization: Bearer <api_key> header

Request Body

Name	Type	Required	Description
`projectId`	`string`	Yes	The project ID
`subscriptionId`	`string`	Yes	The subscription ID
`targetLocales`	`string[]`	Yes	Target locale codes

AI-translate subscription group display name to target locales.

POST /subscriptions/groups/translate

Authentication

Requires API key with Authorization: Bearer <api_key> header

Request Body

Name	Type	Required	Description
`projectId`	`string`	Yes	The project ID
`groupId`	`string`	Yes	The subscription group ID
`targetLocales`	`string[]`	Yes	Target locale codes