Skip to main content
API docs by Redocly

Developer API (2.0.0)

Download OpenAPI specification:Download

Subscription

Operations about subscriptions.

Get a subscription

This endpoint requires the following permission(s): customer_information:subscriptions:read. This endpoint belongs to the Customer Information domain, which has a default rate limit of 480 requests per minute.

Authorizations:
BearerAuth
path Parameters
project_id
required
string <= 255 characters
Example: proj1ab2c3d4

ID of the project

subscription_id
required
string [ 1 .. 255 ] characters
Example: sub1a2b3c4d5e

ID of the subscription

query Parameters
expand
Array of strings[ items [ 1 .. 5000 ] characters ]
Items Value: "redemption"
Example: expand=redemption

Specifies which fields in the response should be expanded. Accepted values are: redemption (requires customer_information:subscriptions:read permission).

Responses

Response samples

Content type
application/json
{
  • "object": "subscription",
  • "id": "sub1ab2c3d4e5",
  • "customer_id": "19b8de26-77c1-49f1-aa18-019a391603e2",
  • "original_customer_id": "19b8de26-77c1-49f1-aa18-019a391603e2",
  • "product_id": "prod1a2b3c4d5e",
  • "starts_at": 1658399423658,
  • "current_period_starts_at": 1658399423658,
  • "current_period_ends_at": 1658399423658,
  • "ends_at": 1658399423658,
  • "gives_access": true,
  • "pending_payment": true,
  • "auto_renewal_status": "will_renew",
  • "status": "trialing",
  • "total_revenue_in_usd": {
    },
  • "presented_offering_id": "ofrnge1a2b3c4d5",
  • "entitlements": {
    },
  • "environment": "production",
  • "store": "amazon",
  • "store_subscription_identifier": 12345678,
  • "ownership": "purchased",
  • "pending_changes": {
    },
  • "country": "US",
  • "management_url": "https://apps.apple.com/account/subscriptions",
  • "redemption": {
    }
}

Get a Play Store or App Store subscription's transactions

This endpoint requires the following permission(s): customer_information:subscriptions:read. This endpoint belongs to the Customer Information domain, which has a default rate limit of 480 requests per minute.

Authorizations:
BearerAuth
path Parameters
project_id
required
string <= 255 characters
Example: proj1ab2c3d4

ID of the project

subscription_id
required
string [ 1 .. 255 ] characters
Example: sub1a2b3c4d5e

ID of the subscription

query Parameters
starting_after
string
Example: starting_after=ent12354

Pagination cursor. Pass the id of the last item from the previous page to fetch the next page; omit for the first page.

limit
integer
Default: 20
Example: limit=10

Maximum number of items to return per page. Values below 1 or above 100 are clamped to that range rather than rejected.

sort
string
Default: "id"
Enum: "id" "purchased_at"
Example: sort=purchased_at

Column to sort the result list by.

direction
string
Default: "asc"
Enum: "asc" "desc"
Example: direction=desc

Sort direction for the result list.

Responses

Response samples

Content type
application/json
{
  • "object": "list",
  • "items": [
    ],
  • "next_page": "/v2/projects/proj123/subscriptions/sub123/transactions?starting_after=GPA.0000-0000-0000-00000",
  • "url": "/v2/projects/proj123/subscriptions/sub123/transactions"
}

Refund a Play Store or Galaxy subscription's transaction

Refund and cancel a Play Store or Galaxy subscription's transaction. Access to the subscription will be revoked. This endpoint requires the following permission(s): customer_information:subscriptions:read_write. This endpoint belongs to the Subscription Transactions Refunds domain, which has a default rate limit of 480 requests per minute.

Authorizations:
BearerAuth
path Parameters
project_id
required
string <= 255 characters
Example: proj1ab2c3d4

ID of the project

subscription_id
required
string [ 1 .. 255 ] characters
Example: sub1a2b3c4d5e

ID of the subscription

transaction_id
required
string [ 1 .. 255 ] characters
Example: GPA.000-000-000-000

Identifier of the transaction in the store

Responses

Response samples

Content type
application/json
{
  • "object": "subscription_transaction",
  • "id": "GPA.0000-0000-0000-00000",
  • "purchased_at": 1658399423658,
  • "product_store_identifier": "com.example.product",
  • "revenue_in_local_currency": {
    },
  • "revenue_in_usd": {
    },
  • "expiration_date": 1658399423658,
  • "effective_expiration_date": 1658399423658
}

Get a list of entitlements associated with a subscription

Lists all Entitlements granted by a Subscription. This endpoint requires the following permission(s): customer_information:subscriptions:read. This endpoint belongs to the Customer Information domain, which has a default rate limit of 480 requests per minute.

Authorizations:
BearerAuth
path Parameters
project_id
required
string <= 255 characters
Example: proj1ab2c3d4

ID of the project

subscription_id
required
string [ 1 .. 255 ] characters
Example: sub1a2b3c4d5e

ID of the subscription

query Parameters
starting_after
string
Example: starting_after=ent12354

Pagination cursor. Pass the id of the last item from the previous page to fetch the next page; omit for the first page.

limit
integer
Default: 20
Example: limit=10

Maximum number of items to return per page. Values below 1 or above 100 are clamped to that range rather than rejected.

Responses

Response samples

Content type
application/json
{
  • "object": "list",
  • "items": [
    ],
  • "next_page": "/v2/projects/proj1ab2c3d4/entitlements?starting_after=entlab21dac",
  • "url": "/v2/projects/proj1ab2c3d4/entitlements"
}

Cancel an active Web Billing subscription

Cancel an active Web Billing subscription. The customer will lose access to the associated entitlements at the end of the current period. This endpoint requires the following permission(s): customer_information:subscriptions:read_write. This endpoint belongs to the Customer Information domain, which has a default rate limit of 480 requests per minute.

Authorizations:
BearerAuth
path Parameters
project_id
required
string <= 255 characters
Example: proj1ab2c3d4

ID of the project

subscription_id
required
string [ 1 .. 255 ] characters
Example: sub1a2b3c4d5e

ID of the subscription

Responses

Response samples

Content type
application/json
{
  • "object": "subscription",
  • "id": "sub1ab2c3d4e5",
  • "customer_id": "19b8de26-77c1-49f1-aa18-019a391603e2",
  • "original_customer_id": "19b8de26-77c1-49f1-aa18-019a391603e2",
  • "product_id": "prod1a2b3c4d5e",
  • "starts_at": 1658399423658,
  • "current_period_starts_at": 1658399423658,
  • "current_period_ends_at": 1658399423658,
  • "ends_at": 1658399423658,
  • "gives_access": true,
  • "pending_payment": true,
  • "auto_renewal_status": "will_renew",
  • "status": "trialing",
  • "total_revenue_in_usd": {
    },
  • "presented_offering_id": "ofrnge1a2b3c4d5",
  • "entitlements": {
    },
  • "environment": "production",
  • "store": "amazon",
  • "store_subscription_identifier": 12345678,
  • "ownership": "purchased",
  • "pending_changes": {
    },
  • "country": "US",
  • "management_url": "https://apps.apple.com/account/subscriptions",
  • "redemption": {
    }
}

Extend the current billing period of a subscription

Extend the current billing period of a subscription. Provide either extend_by_days to extend by a number of days, or extend_until_ms to extend to an absolute epoch-millisecond timestamp. Supported on Apple Store, Google Play Store, and Web Billing subscriptions. For Apple Store subscriptions, extend_reason_code is required and the extension is capped at 90 days. This endpoint requires the following permission(s): customer_information:subscriptions:read_write. This endpoint belongs to the Customer Information domain, which has a default rate limit of 480 requests per minute.

Authorizations:
BearerAuth
path Parameters
project_id
required
string <= 255 characters
Example: proj1ab2c3d4

ID of the project

subscription_id
required
string [ 1 .. 255 ] characters
Example: sub1a2b3c4d5e

ID of the subscription

Request Body schema: application/json
required
One of
extend_by_days
required
integer >= 1

Number of days to extend the current billing period by. For Apple Store subscriptions, the maximum allowed value is 90.

extend_reason_code
string
Enum: "undeclared" "customer_satisfaction" "other" "service_issue_or_outage"

Reason for the extension. Required for Apple Store subscriptions; ignored for Google Play and Web Billing subscriptions.

Responses

Request samples

Content type
application/json
Example
{
  • "extend_by_days": 14,
  • "extend_reason_code": "customer_satisfaction"
}

Response samples

Content type
application/json
{
  • "object": "subscription",
  • "id": "sub1ab2c3d4e5",
  • "customer_id": "19b8de26-77c1-49f1-aa18-019a391603e2",
  • "original_customer_id": "19b8de26-77c1-49f1-aa18-019a391603e2",
  • "product_id": "prod1a2b3c4d5e",
  • "starts_at": 1658399423658,
  • "current_period_starts_at": 1658399423658,
  • "current_period_ends_at": 1658399423658,
  • "ends_at": 1658399423658,
  • "gives_access": true,
  • "pending_payment": true,
  • "auto_renewal_status": "will_renew",
  • "status": "trialing",
  • "total_revenue_in_usd": {
    },
  • "presented_offering_id": "ofrnge1a2b3c4d5",
  • "entitlements": {
    },
  • "environment": "production",
  • "store": "amazon",
  • "store_subscription_identifier": 12345678,
  • "ownership": "purchased",
  • "pending_changes": {
    },
  • "country": "US",
  • "management_url": "https://apps.apple.com/account/subscriptions",
  • "redemption": {
    }
}

Refund an active Web Billing subscription

Cancel a Web Billing subscription by refunding the most recent payment. The customer will immediately lose access to the associated entitlements. This endpoint requires the following permission(s): customer_information:subscriptions:read_write. This endpoint belongs to the Customer Information domain, which has a default rate limit of 480 requests per minute.

Authorizations:
BearerAuth
path Parameters
project_id
required
string <= 255 characters
Example: proj1ab2c3d4

ID of the project

subscription_id
required
string [ 1 .. 255 ] characters
Example: sub1a2b3c4d5e

ID of the subscription

Responses

Response samples

Content type
application/json
{
  • "object": "subscription",
  • "id": "sub1ab2c3d4e5",
  • "customer_id": "19b8de26-77c1-49f1-aa18-019a391603e2",
  • "original_customer_id": "19b8de26-77c1-49f1-aa18-019a391603e2",
  • "product_id": "prod1a2b3c4d5e",
  • "starts_at": 1658399423658,
  • "current_period_starts_at": 1658399423658,
  • "current_period_ends_at": 1658399423658,
  • "ends_at": 1658399423658,
  • "gives_access": true,
  • "pending_payment": true,
  • "auto_renewal_status": "will_renew",
  • "status": "trialing",
  • "total_revenue_in_usd": {
    },
  • "presented_offering_id": "ofrnge1a2b3c4d5",
  • "entitlements": {
    },
  • "environment": "production",
  • "store": "amazon",
  • "store_subscription_identifier": 12345678,
  • "ownership": "purchased",
  • "pending_changes": {
    },
  • "country": "US",
  • "management_url": "https://apps.apple.com/account/subscriptions",
  • "redemption": {
    }
}

Get an authenticated subscription management URL

Get a secure, single-use URL that allows customers to access their Web Billing customer portal. This endpoint requires the following permission(s): customer_information:subscriptions:read. This endpoint belongs to the Customer Information domain, which has a default rate limit of 480 requests per minute.

Authorizations:
BearerAuth
path Parameters
project_id
required
string <= 255 characters
Example: proj1ab2c3d4

ID of the project

subscription_id
required
string [ 1 .. 255 ] characters
Example: sub1a2b3c4d5e

ID of the subscription

Responses

Response samples

Content type
application/json
{}

Search subscriptions by store subscription identifier

Search for a subscription by any of its associated store_subscription_identifier values, whether from a past or current subscription period.

For example, this may include the transactionId of any transaction in an Apple App Store subscription, or any order ID from a Google Play Store subscription. This endpoint requires the following permission(s): customer_information:subscriptions:read. This endpoint belongs to the Customer Information domain, which has a default rate limit of 480 requests per minute.

Authorizations:
BearerAuth
path Parameters
project_id
required
string <= 255 characters
Example: proj1ab2c3d4

ID of the project

query Parameters
store_subscription_identifier
required
string [ 1 .. 255 ] characters
Examples:
  • store_subscription_identifier=9aJscueFTxLPZXXo-AlBTkI0OnFXR2qiH14C1aqWnOT=:3:11..8 - Amazon Appstore
  • store_subscription_identifier=100001234567890 - Apple App Store
  • store_subscription_identifier=txn_01jss4bz50g1z5yw121npeb3ag - Paddle
  • store_subscription_identifier=GPA.1234-5678-9012-34567..0 - Google Play Store
  • store_subscription_identifier=txRcb553a54d4738816a63f1a05cfcb1723e3..1746748685 - RevenueCat Web Billing
  • store_subscription_identifier=4ab8df12-3003-11f0-9646-8ac68bcdcaed - Roku
  • store_subscription_identifier=si_Rww1psqupbKxmt - Stripe

Store ID associated with the subscription for the current or next period.

include_scheduled
boolean
Default: false
Example: include_scheduled=true

When true, includes subscriptions scheduled to start in the future in the response.

expand
Array of strings[ items [ 1 .. 5000 ] characters ]
Items Value: "items.redemption"
Example: expand=items.redemption

Specifies which fields in the response should be expanded. Accepted values are: items.redemption (requires customer_information:subscriptions:read permission).

Responses

Response samples

Content type
application/json
{
  • "object": "list",
  • "items": [
    ],
  • "next_page": "/v2/projects/proj1ab2c3d4/customers/19b8de26-77c1-49f1-aa18-019a391603e2/subscriptions?starting_after=sub1a2b3c4d",
  • "url": "/v2/projects/proj1ab2c3d4/customers/19b8de26-77c1-49f1-aa18-019a391603e2/subscriptions"
}