---
title: "Subscription"
permalink: "/docs/api-v2/subscription"
description: "Open API Reference Docs for the API"
original_source: "openapi-spec/api-v2.yaml"
---

> **AI agents:** This is the Markdown version of a RevenueCat documentation page. For the complete documentation index, see [llms.txt](https://www.revenuecat.com/docs/llms.txt).


# Developer API (2.0.0)

Download OpenAPI specification:[Download](https://www.revenuecat.com/docs/redocusaurus/openapi-v2-subscription.yaml)

## <a id="tag/Subscription"></a>Subscription

Part of the [REST API v2 Reference](/docs/api-v2).

Operations about subscriptions.

#### Endpoints

-   [Search subscriptions by store subscription identifier](#tag/Subscription/operation/search-subscriptions) — `GET /projects/{project_id}/subscriptions`
-   [Get a subscription](#tag/Subscription/operation/get-subscription) — `GET /projects/{project_id}/subscriptions/{subscription_id}`
-   [Cancel an active Web Billing subscription](#tag/Subscription/operation/cancel-subscription) — `POST /projects/{project_id}/subscriptions/{subscription_id}/actions/cancel`
-   [Extend the current billing period of a subscription](#tag/Subscription/operation/extend-subscription) — `POST /projects/{project_id}/subscriptions/{subscription_id}/actions/extend`
-   [Refund an active Web Billing subscription](#tag/Subscription/operation/refund-subscription) — `POST /projects/{project_id}/subscriptions/{subscription_id}/actions/refund`
-   [Get an authenticated subscription management URL](#tag/Subscription/operation/get-authorized-subscription-management-url) — `GET /projects/{project_id}/subscriptions/{subscription_id}/authenticated_management_url`
-   [Get a list of entitlements associated with a subscription](#tag/Subscription/operation/list-subscription-entitlements) — `GET /projects/{project_id}/subscriptions/{subscription_id}/entitlements`

## <a id="tag/Subscription/operation/search-subscriptions"></a>Search subscriptions by store subscription identifier

get/projects/{project_id}/subscriptions

https://api.revenuecat.com/v2/projects/{project_id}/subscriptions

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

**200**

Success

**400**

Bad request

**401**

Unauthorized

**403**

Access denied

**404**

Not found

**423**

Locked

**429**

The request could not be completed because the rate limiting domain for this endpoint is currently at its limit for this project.

**500**

Internal server error

**503**

Internal server error

### Response samples

Content type

application/json

 

```json
{
  "object": "list",
  "items": [
    {
      "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": {
        "currency": "USD",
        "gross": 9.99,
        "commission": 2.99,
        "tax": 0.75,
        "proceeds": 6.25
      },
      "presented_offering_id": "ofrnge1a2b3c4d5",
      "entitlements": {
        "object": "list",
        "items": [
          {
            "state": "active",
            "object": "entitlement",
            "project_id": "proj1ab2c3d4",
            "id": "entla1b2c3d4e5",
            "lookup_key": "premium",
            "display_name": "Premium",
            "created_at": 1658399423658,
            "products": {
              "object": "list",
              "items": [
                {
                  "state": "active",
                  "object": "product",
                  "id": "prod1a2b3c4d5e",
                  "store_identifier": "rc_1w_199",
                  "type": "subscription",
                  "subscription": {
                    "duration": null,
                    "grace_period_duration": null,
                    "trial_duration": null
                  },
                  "one_time": {
                    "is_consumable": null
                  },
                  "created_at": 1658399423658,
                  "app_id": "app1a2b3c4",
                  "app": {
                    "object": null,
                    "id": null,
                    "name": null,
                    "created_at": null,
                    "type": null,
                    "project_id": null,
                    "custom_url_scheme": null,
                    "amazon": { }
                  },
                  "indicative_price": {
                    "object": null,
                    "currency": null,
                    "country": null,
                    "amount_micros": null
                  },
                  "display_name": "Premium Monthly 2023"
                }
              ],
              "next_page": "/v2/projects/proj1ab2c3d4/entitlements/entle1a2b3c4d5/products?starting_after=prodeab21dac",
              "url": "/v2/projects/proj1ab2c3d4/entitlements/entle1a2b3c4d5/products"
            }
          }
        ],
        "next_page": "/v2/projects/proj1ab2c3d4/subscriptions/sub1a2b3c4d5e/entitlements?status=active&starting_after=entlab21dac",
        "url": "/v2/projects/proj1ab2c3d4/subscriptions/sub1a2b3c4d5e/entitlements"
      },
      "environment": "production",
      "store": "amazon",
      "store_subscription_identifier": 12345678,
      "ownership": "purchased",
      "pending_changes": {
        "product": {
          "state": "active",
          "object": "product",
          "id": "prod1a2b3c4d5e",
          "store_identifier": "rc_1w_199",
          "type": "subscription",
          "subscription": {
            "duration": "P1M",
            "grace_period_duration": "P3D",
            "trial_duration": "P1W"
          },
          "one_time": {
            "is_consumable": true
          },
          "created_at": 1658399423658,
          "app_id": "app1a2b3c4",
          "app": {
            "object": "app",
            "id": "app1a2b3c4",
            "name": "string",
            "created_at": 1658399423658,
            "type": "amazon",
            "project_id": "proj1a2b3c4",
            "custom_url_scheme": "rc-1a2b3c4",
            "amazon": {
              "package_name": "string"
            }
          },
          "indicative_price": {
            "object": "indicative_price",
            "currency": "USD",
            "country": "US",
            "amount_micros": "For 99.99, the value should be 99990000"
          },
          "display_name": "Premium Monthly 2023"
        },
        "current_period_starts_at": 1658399423658,
        "current_period_ends_at": 1660991423658,
        "store_subscription_identifier": 12345679,
        "auto_renewal_status": "will_renew",
        "status": "active",
        "pending_payment": false,
        "gives_access": true
      },
      "country": "US",
      "management_url": "https://apps.apple.com/account/subscriptions",
      "redemption": {
        "object": "redemption",
        "redeemed_at": 1658399423658
      },
      "product_change": {
        "status": "pending",
        "product_id": "prod1a2b3c4d5e"
      }
    }
  ],
  "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"
}
```

## <a id="tag/Subscription/operation/get-subscription"></a>Get a subscription

get/projects/{project_id}/subscriptions/{subscription_id}

https://api.revenuecat.com/v2/projects/{project_id}/subscriptions/{subscription_id}

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

**200**

Success

**400**

Bad request

**401**

Unauthorized

**403**

Access denied

**404**

Not found

**423**

Locked

**429**

The request could not be completed because the rate limiting domain for this endpoint is currently at its limit for this project.

**500**

Internal server error

**503**

Internal server error

### Response samples

Content type

application/json

 

```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": {
    "currency": "USD",
    "gross": 9.99,
    "commission": 2.99,
    "tax": 0.75,
    "proceeds": 6.25
  },
  "presented_offering_id": "ofrnge1a2b3c4d5",
  "entitlements": {
    "object": "list",
    "items": [
      {
        "state": "active",
        "object": "entitlement",
        "project_id": "proj1ab2c3d4",
        "id": "entla1b2c3d4e5",
        "lookup_key": "premium",
        "display_name": "Premium",
        "created_at": 1658399423658,
        "products": {
          "object": "list",
          "items": [
            {
              "state": "active",
              "object": "product",
              "id": "prod1a2b3c4d5e",
              "store_identifier": "rc_1w_199",
              "type": "subscription",
              "subscription": {
                "duration": "P1M",
                "grace_period_duration": "P3D",
                "trial_duration": "P1W"
              },
              "one_time": {
                "is_consumable": true
              },
              "created_at": 1658399423658,
              "app_id": "app1a2b3c4",
              "app": {
                "object": "app",
                "id": "app1a2b3c4",
                "name": "string",
                "created_at": 1658399423658,
                "type": "amazon",
                "project_id": "proj1a2b3c4",
                "custom_url_scheme": "rc-1a2b3c4",
                "amazon": {
                  "package_name": "string"
                }
              },
              "indicative_price": {
                "object": "indicative_price",
                "currency": "USD",
                "country": "US",
                "amount_micros": "For 99.99, the value should be 99990000"
              },
              "display_name": "Premium Monthly 2023"
            }
          ],
          "next_page": "/v2/projects/proj1ab2c3d4/entitlements/entle1a2b3c4d5/products?starting_after=prodeab21dac",
          "url": "/v2/projects/proj1ab2c3d4/entitlements/entle1a2b3c4d5/products"
        }
      }
    ],
    "next_page": "/v2/projects/proj1ab2c3d4/subscriptions/sub1a2b3c4d5e/entitlements?status=active&starting_after=entlab21dac",
    "url": "/v2/projects/proj1ab2c3d4/subscriptions/sub1a2b3c4d5e/entitlements"
  },
  "environment": "production",
  "store": "amazon",
  "store_subscription_identifier": 12345678,
  "ownership": "purchased",
  "pending_changes": {
    "product": {
      "state": "active",
      "object": "product",
      "id": "prod1a2b3c4d5e",
      "store_identifier": "rc_1w_199",
      "type": "subscription",
      "subscription": {
        "duration": "P1M",
        "grace_period_duration": "P3D",
        "trial_duration": "P1W"
      },
      "one_time": {
        "is_consumable": true
      },
      "created_at": 1658399423658,
      "app_id": "app1a2b3c4",
      "app": {
        "object": "app",
        "id": "app1a2b3c4",
        "name": "string",
        "created_at": 1658399423658,
        "type": "amazon",
        "project_id": "proj1a2b3c4",
        "custom_url_scheme": "rc-1a2b3c4",
        "amazon": {
          "package_name": "string"
        }
      },
      "indicative_price": {
        "object": "indicative_price",
        "currency": "USD",
        "country": "US",
        "amount_micros": "For 99.99, the value should be 99990000"
      },
      "display_name": "Premium Monthly 2023"
    },
    "current_period_starts_at": 1658399423658,
    "current_period_ends_at": 1660991423658,
    "store_subscription_identifier": 12345679,
    "auto_renewal_status": "will_renew",
    "status": "active",
    "pending_payment": false,
    "gives_access": true
  },
  "country": "US",
  "management_url": "https://apps.apple.com/account/subscriptions",
  "redemption": {
    "object": "redemption",
    "redeemed_at": 1658399423658
  },
  "product_change": {
    "status": "pending",
    "product_id": "prod1a2b3c4d5e"
  }
}
```

## <a id="tag/Subscription/operation/cancel-subscription"></a>Cancel an active Web Billing subscription

post/projects/{project_id}/subscriptions/{subscription_id}/actions/cancel

https://api.revenuecat.com/v2/projects/{project_id}/subscriptions/{subscription_id}/actions/cancel

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

**200**

Success. The subscription has been successfully canceled.

**400**

Bad request

**401**

Unauthorized

**403**

Access denied

**404**

Not found

**409**

Conflict

**422**

Unprocessable entity

**423**

Locked

**429**

The request could not be completed because the rate limiting domain for this endpoint is currently at its limit for this project.

**500**

Internal server error

**503**

Internal server error

### Response samples

Content type

application/json

 

```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": {
    "currency": "USD",
    "gross": 9.99,
    "commission": 2.99,
    "tax": 0.75,
    "proceeds": 6.25
  },
  "presented_offering_id": "ofrnge1a2b3c4d5",
  "entitlements": {
    "object": "list",
    "items": [
      {
        "state": "active",
        "object": "entitlement",
        "project_id": "proj1ab2c3d4",
        "id": "entla1b2c3d4e5",
        "lookup_key": "premium",
        "display_name": "Premium",
        "created_at": 1658399423658,
        "products": {
          "object": "list",
          "items": [
            {
              "state": "active",
              "object": "product",
              "id": "prod1a2b3c4d5e",
              "store_identifier": "rc_1w_199",
              "type": "subscription",
              "subscription": {
                "duration": "P1M",
                "grace_period_duration": "P3D",
                "trial_duration": "P1W"
              },
              "one_time": {
                "is_consumable": true
              },
              "created_at": 1658399423658,
              "app_id": "app1a2b3c4",
              "app": {
                "object": "app",
                "id": "app1a2b3c4",
                "name": "string",
                "created_at": 1658399423658,
                "type": "amazon",
                "project_id": "proj1a2b3c4",
                "custom_url_scheme": "rc-1a2b3c4",
                "amazon": {
                  "package_name": "string"
                }
              },
              "indicative_price": {
                "object": "indicative_price",
                "currency": "USD",
                "country": "US",
                "amount_micros": "For 99.99, the value should be 99990000"
              },
              "display_name": "Premium Monthly 2023"
            }
          ],
          "next_page": "/v2/projects/proj1ab2c3d4/entitlements/entle1a2b3c4d5/products?starting_after=prodeab21dac",
          "url": "/v2/projects/proj1ab2c3d4/entitlements/entle1a2b3c4d5/products"
        }
      }
    ],
    "next_page": "/v2/projects/proj1ab2c3d4/subscriptions/sub1a2b3c4d5e/entitlements?status=active&starting_after=entlab21dac",
    "url": "/v2/projects/proj1ab2c3d4/subscriptions/sub1a2b3c4d5e/entitlements"
  },
  "environment": "production",
  "store": "amazon",
  "store_subscription_identifier": 12345678,
  "ownership": "purchased",
  "pending_changes": {
    "product": {
      "state": "active",
      "object": "product",
      "id": "prod1a2b3c4d5e",
      "store_identifier": "rc_1w_199",
      "type": "subscription",
      "subscription": {
        "duration": "P1M",
        "grace_period_duration": "P3D",
        "trial_duration": "P1W"
      },
      "one_time": {
        "is_consumable": true
      },
      "created_at": 1658399423658,
      "app_id": "app1a2b3c4",
      "app": {
        "object": "app",
        "id": "app1a2b3c4",
        "name": "string",
        "created_at": 1658399423658,
        "type": "amazon",
        "project_id": "proj1a2b3c4",
        "custom_url_scheme": "rc-1a2b3c4",
        "amazon": {
          "package_name": "string"
        }
      },
      "indicative_price": {
        "object": "indicative_price",
        "currency": "USD",
        "country": "US",
        "amount_micros": "For 99.99, the value should be 99990000"
      },
      "display_name": "Premium Monthly 2023"
    },
    "current_period_starts_at": 1658399423658,
    "current_period_ends_at": 1660991423658,
    "store_subscription_identifier": 12345679,
    "auto_renewal_status": "will_renew",
    "status": "active",
    "pending_payment": false,
    "gives_access": true
  },
  "country": "US",
  "management_url": "https://apps.apple.com/account/subscriptions",
  "redemption": {
    "object": "redemption",
    "redeemed_at": 1658399423658
  },
  "product_change": {
    "status": "pending",
    "product_id": "prod1a2b3c4d5e"
  }
}
```

## <a id="tag/Subscription/operation/extend-subscription"></a>Extend the current billing period of a subscription

post/projects/{project_id}/subscriptions/{subscription_id}/actions/extend

https://api.revenuecat.com/v2/projects/{project_id}/subscriptions/{subscription_id}/actions/extend

Extend the current billing period of a subscription. Provide either `extend_by_days` or `extend_until_ms`.

Supported on Apple App Store, Google Play, and Web Billing only. Not supported for promotional subscriptions.

For Apple, `extend_reason_code` is required and extensions are 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

ExtendSubscriptionByDurationExtendSubscriptionUntilDate

- `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

**200**

Success. The subscription's current billing period has been extended.

**400**

Bad request

**401**

Unauthorized

**403**

Access denied

**404**

Not found

**409**

Conflict

**422**

Unprocessable entity

**423**

Locked

**429**

The request could not be completed because the rate limiting domain for this endpoint is currently at its limit for this project.

**500**

Internal server error

**503**

Internal server error

### Request samples

Content type

application/json

Example

ExtendSubscriptionByDurationExtendSubscriptionUntilDateExtendSubscriptionByDuration

```json
{
  "extend_by_days": 14,
  "extend_reason_code": "customer_satisfaction"
}
```

### Response samples

Content type

application/json

 

```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": {
    "currency": "USD",
    "gross": 9.99,
    "commission": 2.99,
    "tax": 0.75,
    "proceeds": 6.25
  },
  "presented_offering_id": "ofrnge1a2b3c4d5",
  "entitlements": {
    "object": "list",
    "items": [
      {
        "state": "active",
        "object": "entitlement",
        "project_id": "proj1ab2c3d4",
        "id": "entla1b2c3d4e5",
        "lookup_key": "premium",
        "display_name": "Premium",
        "created_at": 1658399423658,
        "products": {
          "object": "list",
          "items": [
            {
              "state": "active",
              "object": "product",
              "id": "prod1a2b3c4d5e",
              "store_identifier": "rc_1w_199",
              "type": "subscription",
              "subscription": {
                "duration": "P1M",
                "grace_period_duration": "P3D",
                "trial_duration": "P1W"
              },
              "one_time": {
                "is_consumable": true
              },
              "created_at": 1658399423658,
              "app_id": "app1a2b3c4",
              "app": {
                "object": "app",
                "id": "app1a2b3c4",
                "name": "string",
                "created_at": 1658399423658,
                "type": "amazon",
                "project_id": "proj1a2b3c4",
                "custom_url_scheme": "rc-1a2b3c4",
                "amazon": {
                  "package_name": "string"
                }
              },
              "indicative_price": {
                "object": "indicative_price",
                "currency": "USD",
                "country": "US",
                "amount_micros": "For 99.99, the value should be 99990000"
              },
              "display_name": "Premium Monthly 2023"
            }
          ],
          "next_page": "/v2/projects/proj1ab2c3d4/entitlements/entle1a2b3c4d5/products?starting_after=prodeab21dac",
          "url": "/v2/projects/proj1ab2c3d4/entitlements/entle1a2b3c4d5/products"
        }
      }
    ],
    "next_page": "/v2/projects/proj1ab2c3d4/subscriptions/sub1a2b3c4d5e/entitlements?status=active&starting_after=entlab21dac",
    "url": "/v2/projects/proj1ab2c3d4/subscriptions/sub1a2b3c4d5e/entitlements"
  },
  "environment": "production",
  "store": "amazon",
  "store_subscription_identifier": 12345678,
  "ownership": "purchased",
  "pending_changes": {
    "product": {
      "state": "active",
      "object": "product",
      "id": "prod1a2b3c4d5e",
      "store_identifier": "rc_1w_199",
      "type": "subscription",
      "subscription": {
        "duration": "P1M",
        "grace_period_duration": "P3D",
        "trial_duration": "P1W"
      },
      "one_time": {
        "is_consumable": true
      },
      "created_at": 1658399423658,
      "app_id": "app1a2b3c4",
      "app": {
        "object": "app",
        "id": "app1a2b3c4",
        "name": "string",
        "created_at": 1658399423658,
        "type": "amazon",
        "project_id": "proj1a2b3c4",
        "custom_url_scheme": "rc-1a2b3c4",
        "amazon": {
          "package_name": "string"
        }
      },
      "indicative_price": {
        "object": "indicative_price",
        "currency": "USD",
        "country": "US",
        "amount_micros": "For 99.99, the value should be 99990000"
      },
      "display_name": "Premium Monthly 2023"
    },
    "current_period_starts_at": 1658399423658,
    "current_period_ends_at": 1660991423658,
    "store_subscription_identifier": 12345679,
    "auto_renewal_status": "will_renew",
    "status": "active",
    "pending_payment": false,
    "gives_access": true
  },
  "country": "US",
  "management_url": "https://apps.apple.com/account/subscriptions",
  "redemption": {
    "object": "redemption",
    "redeemed_at": 1658399423658
  },
  "product_change": {
    "status": "pending",
    "product_id": "prod1a2b3c4d5e"
  }
}
```

## <a id="tag/Subscription/operation/refund-subscription"></a>Refund an active Web Billing subscription

post/projects/{project_id}/subscriptions/{subscription_id}/actions/refund

https://api.revenuecat.com/v2/projects/{project_id}/subscriptions/{subscription_id}/actions/refund

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

**200**

Success. The subscription has been successfully refunded.

**400**

Bad request

**401**

Unauthorized

**403**

Access denied

**404**

Not found

**409**

Conflict

**422**

Unprocessable entity

**423**

Locked

**429**

The request could not be completed because the rate limiting domain for this endpoint is currently at its limit for this project.

**500**

Internal server error

**503**

Internal server error

### Response samples

Content type

application/json

 

```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": {
    "currency": "USD",
    "gross": 9.99,
    "commission": 2.99,
    "tax": 0.75,
    "proceeds": 6.25
  },
  "presented_offering_id": "ofrnge1a2b3c4d5",
  "entitlements": {
    "object": "list",
    "items": [
      {
        "state": "active",
        "object": "entitlement",
        "project_id": "proj1ab2c3d4",
        "id": "entla1b2c3d4e5",
        "lookup_key": "premium",
        "display_name": "Premium",
        "created_at": 1658399423658,
        "products": {
          "object": "list",
          "items": [
            {
              "state": "active",
              "object": "product",
              "id": "prod1a2b3c4d5e",
              "store_identifier": "rc_1w_199",
              "type": "subscription",
              "subscription": {
                "duration": "P1M",
                "grace_period_duration": "P3D",
                "trial_duration": "P1W"
              },
              "one_time": {
                "is_consumable": true
              },
              "created_at": 1658399423658,
              "app_id": "app1a2b3c4",
              "app": {
                "object": "app",
                "id": "app1a2b3c4",
                "name": "string",
                "created_at": 1658399423658,
                "type": "amazon",
                "project_id": "proj1a2b3c4",
                "custom_url_scheme": "rc-1a2b3c4",
                "amazon": {
                  "package_name": "string"
                }
              },
              "indicative_price": {
                "object": "indicative_price",
                "currency": "USD",
                "country": "US",
                "amount_micros": "For 99.99, the value should be 99990000"
              },
              "display_name": "Premium Monthly 2023"
            }
          ],
          "next_page": "/v2/projects/proj1ab2c3d4/entitlements/entle1a2b3c4d5/products?starting_after=prodeab21dac",
          "url": "/v2/projects/proj1ab2c3d4/entitlements/entle1a2b3c4d5/products"
        }
      }
    ],
    "next_page": "/v2/projects/proj1ab2c3d4/subscriptions/sub1a2b3c4d5e/entitlements?status=active&starting_after=entlab21dac",
    "url": "/v2/projects/proj1ab2c3d4/subscriptions/sub1a2b3c4d5e/entitlements"
  },
  "environment": "production",
  "store": "amazon",
  "store_subscription_identifier": 12345678,
  "ownership": "purchased",
  "pending_changes": {
    "product": {
      "state": "active",
      "object": "product",
      "id": "prod1a2b3c4d5e",
      "store_identifier": "rc_1w_199",
      "type": "subscription",
      "subscription": {
        "duration": "P1M",
        "grace_period_duration": "P3D",
        "trial_duration": "P1W"
      },
      "one_time": {
        "is_consumable": true
      },
      "created_at": 1658399423658,
      "app_id": "app1a2b3c4",
      "app": {
        "object": "app",
        "id": "app1a2b3c4",
        "name": "string",
        "created_at": 1658399423658,
        "type": "amazon",
        "project_id": "proj1a2b3c4",
        "custom_url_scheme": "rc-1a2b3c4",
        "amazon": {
          "package_name": "string"
        }
      },
      "indicative_price": {
        "object": "indicative_price",
        "currency": "USD",
        "country": "US",
        "amount_micros": "For 99.99, the value should be 99990000"
      },
      "display_name": "Premium Monthly 2023"
    },
    "current_period_starts_at": 1658399423658,
    "current_period_ends_at": 1660991423658,
    "store_subscription_identifier": 12345679,
    "auto_renewal_status": "will_renew",
    "status": "active",
    "pending_payment": false,
    "gives_access": true
  },
  "country": "US",
  "management_url": "https://apps.apple.com/account/subscriptions",
  "redemption": {
    "object": "redemption",
    "redeemed_at": 1658399423658
  },
  "product_change": {
    "status": "pending",
    "product_id": "prod1a2b3c4d5e"
  }
}
```

## <a id="tag/Subscription/operation/get-authorized-subscription-management-url"></a>Get an authenticated subscription management URL

get/projects/{project_id}/subscriptions/{subscription_id}/authenticated_management_url

https://api.revenuecat.com/v2/projects/{project_id}/subscriptions/{subscription_id}/authenticated_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

**200**

Success

**400**

Bad request

**401**

Unauthorized

**403**

Access denied

**404**

Not found

**423**

Locked

**429**

The request could not be completed because the rate limiting domain for this endpoint is currently at its limit for this project.

**500**

Internal server error

**502**

Bad gateway

**503**

Internal server error

### Response samples

Content type

application/json

```json
{
  "object": "authenticated_management_url",
  "management_url": "https://billing.revenuecat.com/app1a2b3c4/sub1ab2c3d4e5?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9"
}
```

## <a id="tag/Subscription/operation/list-subscription-entitlements"></a>Get a list of entitlements associated with a subscription

get/projects/{project_id}/subscriptions/{subscription_id}/entitlements

https://api.revenuecat.com/v2/projects/{project_id}/subscriptions/{subscription_id}/entitlements

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

**200**

Success

**400**

Bad request

**401**

Unauthorized

**403**

Access denied

**404**

Not found

**423**

Locked

**429**

The request could not be completed because the rate limiting domain for this endpoint is currently at its limit for this project.

**500**

Internal server error

**503**

Internal server error

### Response samples

Content type

application/json

 

```json
{
  "object": "list",
  "items": [
    {
      "state": "active",
      "object": "entitlement",
      "project_id": "proj1ab2c3d4",
      "id": "entla1b2c3d4e5",
      "lookup_key": "premium",
      "display_name": "Premium",
      "created_at": 1658399423658,
      "products": {
        "object": "list",
        "items": [
          {
            "state": "active",
            "object": "product",
            "id": "prod1a2b3c4d5e",
            "store_identifier": "rc_1w_199",
            "type": "subscription",
            "subscription": {
              "duration": "P1M",
              "grace_period_duration": "P3D",
              "trial_duration": "P1W"
            },
            "one_time": {
              "is_consumable": true
            },
            "created_at": 1658399423658,
            "app_id": "app1a2b3c4",
            "app": {
              "object": "app",
              "id": "app1a2b3c4",
              "name": "string",
              "created_at": 1658399423658,
              "type": "amazon",
              "project_id": "proj1a2b3c4",
              "custom_url_scheme": "rc-1a2b3c4",
              "amazon": {
                "package_name": "string"
              }
            },
            "indicative_price": {
              "object": "indicative_price",
              "currency": "USD",
              "country": "US",
              "amount_micros": "For 99.99, the value should be 99990000"
            },
            "display_name": "Premium Monthly 2023"
          }
        ],
        "next_page": "/v2/projects/proj1ab2c3d4/entitlements/entle1a2b3c4d5/products?starting_after=prodeab21dac",
        "url": "/v2/projects/proj1ab2c3d4/entitlements/entle1a2b3c4d5/products"
      }
    }
  ],
  "next_page": "/v2/projects/proj1ab2c3d4/entitlements?starting_after=entlab21dac",
  "url": "/v2/projects/proj1ab2c3d4/entitlements"
}
```

## <a id="tag/Endpoint-Reference"></a>Endpoint Reference

All API v2 resources, one page each. General concepts (authentication, pagination, rate limits, error handling) live on the [API v2 overview](/docs/api-v2).

-   [App](/docs/api-v2/app) — 7 endpoints
-   [Audience](/docs/api-v2/audience) — 6 endpoints
-   [Audit Log](/docs/api-v2/audit-log) — 1 endpoint
-   [Charts & Metrics](/docs/api-v2/charts-and-metrics) — 4 endpoints
-   [Collaborator](/docs/api-v2/collaborator) — 1 endpoint
-   [Customer](/docs/api-v2/customer) — 12 endpoints
-   [Customer Resources](/docs/api-v2/customer/resources) — 5 endpoints
-   [Discount](/docs/api-v2/discount) — 10 endpoints
-   [Entitlement](/docs/api-v2/entitlement) — 10 endpoints
-   [IAM](/docs/api-v2/iam) — 1 endpoint
-   [Integration](/docs/api-v2/integration) — 5 endpoints
-   [Invoice](/docs/api-v2/invoice) — 2 endpoints
-   [Offering](/docs/api-v2/offering) — 7 endpoints
-   [Package](/docs/api-v2/package) — 8 endpoints
-   [Paywall](/docs/api-v2/paywall) — 5 endpoints
-   [Paywall Fonts & Media](/docs/api-v2/paywall/assets) — 4 endpoints
-   [Paywall Publishing](/docs/api-v2/paywall/publishing) — 7 endpoints
-   [Product](/docs/api-v2/product) — 8 endpoints
-   [Project](/docs/api-v2/project) — 2 endpoints
-   [Purchase](/docs/api-v2/purchase) — 4 endpoints
-   [Subscription](/docs/api-v2/subscription) — 7 endpoints
-   [Subscription Data Model](/docs/api-v2/subscription-data-model) — full schema reference
-   [Subscription Transactions](/docs/api-v2/subscription-transactions) — 2 endpoints
-   [Virtual Currency](/docs/api-v2/virtual-currency) — 10 endpoints

## Response schema reference

Response examples above mirror the rendered API reference. These field definitions come from the same OpenAPI specification.

### ListSubscriptions

- Used by `GET /projects/{project_id}/subscriptions (200) — Search subscriptions by store subscription identifier`

- `object` (required): string — one of `list`; String representing the object's type. Objects of the same type share the same value. Always has the value `list`.
- `items` (required): array of Subscription — Details about each object.
  - `object` (required): string — one of `subscription`; String representing the object's type. Objects of the same type share the same value.
  - `id` (required): string — length 1–255; The ID of the subscription (generated by RevenueCat)
  - `customer_id` (required): string — length 1–1500; The ID of the customer
  - `original_customer_id` (required): string — length 1–1500; The ID of the original customer. Relevant for subscriptions that were transferred from one customer to another
  - `product_id` (required): string or null — length 1–255; The RevenueCat ID of the product that the customer is subscribed to. Exists for all store types except for promotional.
  - `starts_at` (required): integer (format: `int64`) — The date when the subscription originally started in ms since epoch
  - `current_period_starts_at` (required): integer (format: `int64`) — The date when the subscription billing period started in ms since epoch
  - `current_period_ends_at` (required): integer or null (format: `int64`) — The date when the subscription billing period is expected to end in ms since epoch. Can be null if the subscription is paused until an indefinite date.
  - `ends_at` (required): integer or null (format: `int64`) — The date when the latest subscription billing period is expected to end in ms since epoch. It will only be different from `current_period_ends_at` if `auto_renewal_status` is `has_already_renewed`, in which case it indicates the end of the next billing period. Can be null if the subscription is paused until an indefinite date.
  - `gives_access` (required): boolean — Determines whether the customer should currently be provided access to the entitlements associated with the subscription
  - `pending_payment` (required): boolean — Determines whether there is a pending payment associated with the subscription
  - `auto_renewal_status` (required): string — one of `will_renew`, `will_not_renew`, `will_change_product`, `will_pause`, `requires_price_increase_consent`, `has_already_renewed`; The auto renewal status of a subscription. Possible values: • `will_renew`: the subscription is currently set to automatically renew • `will_not_renew`: the subscription is currently set to expire at the end of the period • `will_change_product`: the subscription is currently set to change product at the end of the period (which might start a new subscription) • `will_pause`: the subscription is currently set to pause at the end of the current period • `requires_price_increase_consent`: the subscription will expire at the end of the current period unless the customer consents to the price increase • `has_already_renewed`: the customer has already been charged for the upcoming renewal (so the renewal will take place even if the customer opts out of auto-renewal before the end of the period)
  - `status` (required): string — one of `trialing`, `active`, `expired`, `in_grace_period`, `in_billing_retry`, `paused`, `unknown`, `incomplete`; The status of a subscription. Please note that additional states might be added in the future. To determine whether or not a subscription currently provides access to any associated entitlements, use the _gives_access_ field. Possible values: • `trialing`: the subscription is in a free trial period • `active`: the subscription is active, in a paid period • `expired`: the subscription is expired and no longer active • `in_grace_period`: the subscription is past its regular expiry date and experienced a billing issue, but is currently still in an access-granting grace period • `in_billing_retry`: the subscription has experienced a billing issue. Billing is being retried, access is suspended.-paused: the subscription is currently paused and should not provide access. • `unknown`: the subscription is in an unknown state. Refer to the _gives_access_ field to determine whether or not to grant access. • `incomplete`: the subscription is in an incomplete state, maybe due to incorrect billing details or because it's scheduled to start in the future.
  - `total_revenue_in_usd` (required): MonetaryAmount — Total revenue generated by a subscription in USD
    - `currency` (required): Currency — one of `AED`, `AFN`, `ALL`, `AMD`, `ANG`, `AOA`, `ARS`, `AUD`, `AWG`, `AZN`, `BAM`, `BBD`, `BDT`, `BGN`, `BHD`, `BIF`, `BMD`, `BND`, `BOB`, `BRL`, `BSD`, `BTC`, `BTN`, `BWP`, `BYN`, `BZD`, `CAD`, `CDF`, `CHF`, `CLF`, `CLP`, `CNH`, `CNY`, `COP`, `CRC`, `CUC`, `CUP`, `CVE`, `CZK`, `DJF`, `DKK`, `DOP`, `DZD`, `EGP`, `ERN`, `ETB`, `EUR`, `FJD`, `FKP`, `GBP`, `GEL`, `GGP`, `GHS`, `GIP`, `GMD`, `GNF`, `GTQ`, `GYD`, `HKD`, `HNL`, `HRK`, `HTG`, `HUF`, `IDR`, `ILS`, `IMP`, `INR`, `IQD`, `IRR`, `ISK`, `JEP`, `JMD`, `JOD`, `JPY`, `KES`, `KGS`, `KHR`, `KMF`, `KPW`, `KRW`, `KWD`, `KYD`, `KZT`, `LAK`, `LBP`, `LKR`, `LRD`, `LSL`, `LYD`, `MAD`, `MDL`, `MGA`, `MKD`, `MMK`, `MNT`, `MOP`, `MRU`, `MUR`, `MVR`, `MWK`, `MXN`, `MYR`, `MZN`, `NAD`, `NGN`, `NIO`, `NOK`, `NPR`, `NZD`, `OMR`, `PAB`, `PEN`, `PGK`, `PHP`, `PKR`, `PLN`, `PYG`, `QAR`, `RON`, `RSD`, `RUB`, `RWF`, `SAR`, `SBD`, `SCR`, `SDG`, `SEK`, `SGD`, `SHP`, `SLL`, `SOS`, `SRD`, `SSP`, `STD`, `STN`, `SVC`, `SYP`, `SZL`, `THB`, `TJS`, `TMT`, `TND`, `TOP`, `TRY`, `TTD`, `TWD`, `TZS`, `UAH`, `UGX`, `USD`, `UYU`, `UZS`, `VEF`, `VES`, `VND`, `VUV`, `WST`, `XAF`, `XAG`, `XAU`, `XCD`, `XDR`, `XOF`, `XPD`, `XPF`, `XPT`, `YER`, `ZAR`, `ZMW`, `ZWL`; ISO 4217 currency code
    - `gross` (required): number — Total revenue generated (excluding taxes and commission)
    - `commission`: number — Store commission or payment processor fees deducted from gross revenue (if any)
    - `tax` (required): number — Estimated taxes deducted from gross revenue
    - `proceeds` (required): number — Net revenue after store commission / fees and taxes
  - `presented_offering_id` (required): string or null — length 1–200; The ID of the offering the customer saw when purchasing the subscription
  - `entitlements` (required): object
    - `object` (required): string — one of `list`; String representing the object's type. Objects of the same type share the same value. Always has the value `list`.
    - `items` (required): array of Entitlement — Details about each object.
    - `next_page` (required): string or null — URL to access the next page of the customer's entitlements. If not present / null, there is no next page
    - `url` (required): string — length 0–5000; The URL where this list can be accessed.
  - `environment` (required): Environment — The store environment
  - `store` (required): string — one of `amazon`, `app_store`, `mac_app_store`, `play_store`, `promotional`, `stripe`, `rc_billing`, `external`, `roku`, `paddle`, `paypal`, `galaxy`, `test_store`; Store the subscription belongs to
  - `store_subscription_identifier` (required): string — length 1–255; The subscription identifier as per the store (e.g, for Apple App Store, the `transaction_id` of the latest transaction of the subscription, or for Google Play Store, the Order ID of the last renewal of the subscription)
  - `ownership` (required): Ownership — Ownership of the subscription
  - `pending_changes`: object or null — Expected changes to the subscription that will occur at the end of the current period. Present when the subscription has a pending product change, has already renewed for the next period, or has a failed upcoming renewal. Only fields that differ from the current subscription state are included.
    - `product`: Product or null — The product that will be active as of the next renewal
    - `current_period_starts_at`: integer or null (format: `int64`) — Expected start of the next billing period in ms since epoch. Omitted when unchanged from the current subscription.
    - `current_period_ends_at`: integer or null (format: `int64`) — Expected end of the next billing period in ms since epoch. Omitted when unchanged from the current subscription.
    - `store_subscription_identifier`: string or null — length 1–255; Expected store subscription identifier for the next period. Omitted when unchanged from the current subscription.
    - `auto_renewal_status`: string or null — one of `will_renew`, `will_not_renew`, `will_change_product`, `will_pause`, `requires_price_increase_consent`, `has_already_renewed`; Expected auto renewal status for the next period. Omitted when unchanged from the current subscription.
    - `status`: string or null — one of `trialing`, `active`, `expired`, `in_grace_period`, `in_billing_retry`, `paused`, `unknown`, `incomplete`; Expected subscription status for the next period. Omitted when unchanged from the current subscription.
    - `pending_payment`: boolean or null — Expected pending payment flag for the next period. Omitted when unchanged from the current subscription.
    - `gives_access`: boolean or null — Expected access flag for the next period. Omitted when unchanged from the current subscription.
  - `country`: Country or null — one of ``, `AF`, `AL`, `DZ`, `AS`, `AD`, `AO`, `AI`, `AQ`, `AG`, `AR`, `AM`, `AW`, `AU`, `AT`, `AZ`, `BS`, `BH`, `BD`, `BB`, `BY`, `BE`, `BZ`, `BJ`, `BM`, `BT`, `BO`, `BQ`, `BA`, `BW`, `BV`, `BR`, `IO`, `BN`, `BG`, `BF`, `BI`, `CV`, `KH`, `CM`, `CA`, `KY`, `CF`, `TD`, `CL`, `CN`, `CX`, `CC`, `CO`, `KM`, `CD`, `CG`, `CK`, `CR`, `HR`, `CU`, `CW`, `CY`, `CZ`, `CI`, `DK`, `DJ`, `DM`, `DO`, `EC`, `EG`, `SV`, `GQ`, `ER`, `EE`, `SZ`, `ET`, `FK`, `FO`, `FJ`, `FI`, `FR`, `GF`, `PF`, `TF`, `GA`, `GM`, `GE`, `DE`, `GH`, `GI`, `GR`, `GL`, `GD`, `GP`, `GU`, `GT`, `GG`, `GN`, `GW`, `GY`, `HT`, `HM`, `VA`, `HN`, `HK`, `HU`, `IS`, `IN`, `ID`, `IR`, `IQ`, `IE`, `IM`, `IL`, `IT`, `JM`, `JP`, `JE`, `JO`, `KZ`, `KE`, `KI`, `KP`, `KR`, `KW`, `KG`, `LA`, `LV`, `LB`, `LS`, `LR`, `LY`, `LI`, `LT`, `LU`, `MO`, `MG`, `MW`, `MY`, `MV`, `ML`, `MT`, `MH`, `MQ`, `MR`, `MU`, `YT`, `MX`, `FM`, `MD`, `MC`, `MN`, `ME`, `MS`, `MA`, `MZ`, `MM`, `NA`, `NR`, `NP`, `NL`, `NC`, `NZ`, `NI`, `NE`, `NG`, `NU`, `NF`, `MP`, `NO`, `OM`, `PK`, `PW`, `PS`, `PA`, `PG`, `PY`, `PE`, `PH`, `PN`, `PL`, `PT`, `PR`, `QA`, `MK`, `RO`, `RU`, `RW`, `RE`, `BL`, `SH`, `KN`, `LC`, `MF`, `PM`, `VC`, `WS`, `SM`, `ST`, `SA`, `SN`, `RS`, `SC`, `SL`, `SG`, `SX`, `SK`, `SI`, `SB`, `SO`, `ZA`, `GS`, `SS`, `ES`, `LK`, `SD`, `SR`, `SJ`, `SE`, `CH`, `SY`, `TW`, `TJ`, `TZ`, `TH`, `TL`, `TG`, `TK`, `TO`, `TT`, `TN`, `TR`, `TM`, `TC`, `TV`, `UG`, `UA`, `AE`, `GB`, `UM`, `US`, `UY`, `UZ`, `VU`, `VE`, `VN`, `VG`, `VI`, `WF`, `EH`, `YE`, `ZM`, `ZW`, `AX`; The country that the object is associated with, in ISO alpha 2 code
  - `management_url` (required): string or null — The URL to manage the subscription
  - `redemption`: Redemption or null — Information about the most recent successful redemption of the purchase's redemption link. Only applicable to Web Billing web-to-web purchases; null if the purchase has never been successfully redeemed (or has no redemption link, e.g. purchases from other stores).
    - `object` (required): string — one of `redemption`; String representing the object's type. Objects of the same type share the same value.
    - `redeemed_at` (required): integer (format: `int64`) — The date of the most recent successful redemption of the purchase's redemption link in ms since epoch.
  - `product_change`: object — The outcome of a product change request. Only present in the response to the change product endpoint. `applied` means this subscription reflects the new product; for Stripe that is a new subscription, so its `id` differs from the one the change was requested for and that one is now expired. `pending` means the change was accepted but this subscription does not reflect it yet.
    - `status` (required): string — one of `applied`, `pending`; Whether the change has been applied yet.
    - `product_id` (required): string — The RevenueCat ID of the product the subscription is changing to
- `next_page` (required): string or null — URL to access the next page of the customer's subscriptions. If not present / null, there is no next page
- `url` (required): string — length 0–5000; The URL where this list can be accessed.

### Subscription

- Used by `GET /projects/{project_id}/subscriptions/{subscription_id} (200) — Get a subscription`
- Used by `POST /projects/{project_id}/subscriptions/{subscription_id}/actions/cancel (200) — Cancel an active Web Billing subscription`
- Used by `POST /projects/{project_id}/subscriptions/{subscription_id}/actions/extend (200) — Extend the current billing period of a subscription`
- Used by `POST /projects/{project_id}/subscriptions/{subscription_id}/actions/refund (200) — Refund an active Web Billing subscription`

- `object` (required): string — one of `subscription`; String representing the object's type. Objects of the same type share the same value.
- `id` (required): string — length 1–255; The ID of the subscription (generated by RevenueCat)
- `customer_id` (required): string — length 1–1500; The ID of the customer
- `original_customer_id` (required): string — length 1–1500; The ID of the original customer. Relevant for subscriptions that were transferred from one customer to another
- `product_id` (required): string or null — length 1–255; The RevenueCat ID of the product that the customer is subscribed to. Exists for all store types except for promotional.
- `starts_at` (required): integer (format: `int64`) — The date when the subscription originally started in ms since epoch
- `current_period_starts_at` (required): integer (format: `int64`) — The date when the subscription billing period started in ms since epoch
- `current_period_ends_at` (required): integer or null (format: `int64`) — The date when the subscription billing period is expected to end in ms since epoch. Can be null if the subscription is paused until an indefinite date.
- `ends_at` (required): integer or null (format: `int64`) — The date when the latest subscription billing period is expected to end in ms since epoch. It will only be different from `current_period_ends_at` if `auto_renewal_status` is `has_already_renewed`, in which case it indicates the end of the next billing period. Can be null if the subscription is paused until an indefinite date.
- `gives_access` (required): boolean — Determines whether the customer should currently be provided access to the entitlements associated with the subscription
- `pending_payment` (required): boolean — Determines whether there is a pending payment associated with the subscription
- `auto_renewal_status` (required): string — one of `will_renew`, `will_not_renew`, `will_change_product`, `will_pause`, `requires_price_increase_consent`, `has_already_renewed`; The auto renewal status of a subscription. Possible values: • `will_renew`: the subscription is currently set to automatically renew • `will_not_renew`: the subscription is currently set to expire at the end of the period • `will_change_product`: the subscription is currently set to change product at the end of the period (which might start a new subscription) • `will_pause`: the subscription is currently set to pause at the end of the current period • `requires_price_increase_consent`: the subscription will expire at the end of the current period unless the customer consents to the price increase • `has_already_renewed`: the customer has already been charged for the upcoming renewal (so the renewal will take place even if the customer opts out of auto-renewal before the end of the period)
- `status` (required): string — one of `trialing`, `active`, `expired`, `in_grace_period`, `in_billing_retry`, `paused`, `unknown`, `incomplete`; The status of a subscription. Please note that additional states might be added in the future. To determine whether or not a subscription currently provides access to any associated entitlements, use the _gives_access_ field. Possible values: • `trialing`: the subscription is in a free trial period • `active`: the subscription is active, in a paid period • `expired`: the subscription is expired and no longer active • `in_grace_period`: the subscription is past its regular expiry date and experienced a billing issue, but is currently still in an access-granting grace period • `in_billing_retry`: the subscription has experienced a billing issue. Billing is being retried, access is suspended.-paused: the subscription is currently paused and should not provide access. • `unknown`: the subscription is in an unknown state. Refer to the _gives_access_ field to determine whether or not to grant access. • `incomplete`: the subscription is in an incomplete state, maybe due to incorrect billing details or because it's scheduled to start in the future.
- `total_revenue_in_usd` (required): MonetaryAmount — Total revenue generated by a subscription in USD
  - `currency` (required): Currency — one of `AED`, `AFN`, `ALL`, `AMD`, `ANG`, `AOA`, `ARS`, `AUD`, `AWG`, `AZN`, `BAM`, `BBD`, `BDT`, `BGN`, `BHD`, `BIF`, `BMD`, `BND`, `BOB`, `BRL`, `BSD`, `BTC`, `BTN`, `BWP`, `BYN`, `BZD`, `CAD`, `CDF`, `CHF`, `CLF`, `CLP`, `CNH`, `CNY`, `COP`, `CRC`, `CUC`, `CUP`, `CVE`, `CZK`, `DJF`, `DKK`, `DOP`, `DZD`, `EGP`, `ERN`, `ETB`, `EUR`, `FJD`, `FKP`, `GBP`, `GEL`, `GGP`, `GHS`, `GIP`, `GMD`, `GNF`, `GTQ`, `GYD`, `HKD`, `HNL`, `HRK`, `HTG`, `HUF`, `IDR`, `ILS`, `IMP`, `INR`, `IQD`, `IRR`, `ISK`, `JEP`, `JMD`, `JOD`, `JPY`, `KES`, `KGS`, `KHR`, `KMF`, `KPW`, `KRW`, `KWD`, `KYD`, `KZT`, `LAK`, `LBP`, `LKR`, `LRD`, `LSL`, `LYD`, `MAD`, `MDL`, `MGA`, `MKD`, `MMK`, `MNT`, `MOP`, `MRU`, `MUR`, `MVR`, `MWK`, `MXN`, `MYR`, `MZN`, `NAD`, `NGN`, `NIO`, `NOK`, `NPR`, `NZD`, `OMR`, `PAB`, `PEN`, `PGK`, `PHP`, `PKR`, `PLN`, `PYG`, `QAR`, `RON`, `RSD`, `RUB`, `RWF`, `SAR`, `SBD`, `SCR`, `SDG`, `SEK`, `SGD`, `SHP`, `SLL`, `SOS`, `SRD`, `SSP`, `STD`, `STN`, `SVC`, `SYP`, `SZL`, `THB`, `TJS`, `TMT`, `TND`, `TOP`, `TRY`, `TTD`, `TWD`, `TZS`, `UAH`, `UGX`, `USD`, `UYU`, `UZS`, `VEF`, `VES`, `VND`, `VUV`, `WST`, `XAF`, `XAG`, `XAU`, `XCD`, `XDR`, `XOF`, `XPD`, `XPF`, `XPT`, `YER`, `ZAR`, `ZMW`, `ZWL`; ISO 4217 currency code
  - `gross` (required): number — Total revenue generated (excluding taxes and commission)
  - `commission`: number — Store commission or payment processor fees deducted from gross revenue (if any)
  - `tax` (required): number — Estimated taxes deducted from gross revenue
  - `proceeds` (required): number — Net revenue after store commission / fees and taxes
- `presented_offering_id` (required): string or null — length 1–200; The ID of the offering the customer saw when purchasing the subscription
- `entitlements` (required): object
  - `object` (required): string — one of `list`; String representing the object's type. Objects of the same type share the same value. Always has the value `list`.
  - `items` (required): array of Entitlement — Details about each object.
    - `state` (required): string — one of `active`, `inactive`; Whether the entitlement is active or inactive (archived).
    - `object` (required): string — one of `entitlement`; String representing the object's type. Objects of the same type share the same value.
    - `project_id` (required): string — length 1–20; ID of the project to which the entitlement belongs
    - `id` (required): string — length 1–255; The id of the entitlement
    - `lookup_key` (required): string — length 1–200; A custom identifier of the entitlement
    - `display_name` (required): string — length 1–1500; The display name of the entitlement
    - `created_at` (required): integer (format: `int64`) — The date when the entitlement was created in ms since epoch
    - `products`: object or null — List of products attached to the entitlement
  - `next_page` (required): string or null — URL to access the next page of the customer's entitlements. If not present / null, there is no next page
  - `url` (required): string — length 0–5000; The URL where this list can be accessed.
- `environment` (required): Environment — The store environment
- `store` (required): string — one of `amazon`, `app_store`, `mac_app_store`, `play_store`, `promotional`, `stripe`, `rc_billing`, `external`, `roku`, `paddle`, `paypal`, `galaxy`, `test_store`; Store the subscription belongs to
- `store_subscription_identifier` (required): string — length 1–255; The subscription identifier as per the store (e.g, for Apple App Store, the `transaction_id` of the latest transaction of the subscription, or for Google Play Store, the Order ID of the last renewal of the subscription)
- `ownership` (required): Ownership — Ownership of the subscription
- `pending_changes`: object or null — Expected changes to the subscription that will occur at the end of the current period. Present when the subscription has a pending product change, has already renewed for the next period, or has a failed upcoming renewal. Only fields that differ from the current subscription state are included.
  - `product`: Product or null — The product that will be active as of the next renewal
    - `state` (required): string — one of `active`, `inactive`; Whether the product is active or inactive (archived).
    - `object` (required): string — one of `product`; String representing the object's type. Objects of the same type share the same value. Always has the value `list`.
    - `id` (required): string — length 1–255; The id of the product
    - `store_identifier` (required): string — length 1–255; The store product identifier
    - `type` (required): ProductType — one of `subscription`, `one_time`, `consumable`, `non_consumable`, `non_renewing_subscription`
    - `subscription`: SubscriptionProduct or null
    - `one_time`: OneTimeProduct or null
    - `created_at` (required): integer (format: `int64`) — The date when the product was created in ms since epoch
    - `app_id` (required): string — length 1–255; The id of the app
    - `app`: App or null
    - `indicative_price`: IndicativePrice or null — An indicative price for a product, in the default currency/country (USD / US). Uses the same price source as the get-offering-prices endpoint.
    - `display_name` (required): string or null — length 1–1500; The display name of the product
  - `current_period_starts_at`: integer or null (format: `int64`) — Expected start of the next billing period in ms since epoch. Omitted when unchanged from the current subscription.
  - `current_period_ends_at`: integer or null (format: `int64`) — Expected end of the next billing period in ms since epoch. Omitted when unchanged from the current subscription.
  - `store_subscription_identifier`: string or null — length 1–255; Expected store subscription identifier for the next period. Omitted when unchanged from the current subscription.
  - `auto_renewal_status`: string or null — one of `will_renew`, `will_not_renew`, `will_change_product`, `will_pause`, `requires_price_increase_consent`, `has_already_renewed`; Expected auto renewal status for the next period. Omitted when unchanged from the current subscription.
  - `status`: string or null — one of `trialing`, `active`, `expired`, `in_grace_period`, `in_billing_retry`, `paused`, `unknown`, `incomplete`; Expected subscription status for the next period. Omitted when unchanged from the current subscription.
  - `pending_payment`: boolean or null — Expected pending payment flag for the next period. Omitted when unchanged from the current subscription.
  - `gives_access`: boolean or null — Expected access flag for the next period. Omitted when unchanged from the current subscription.
- `country`: Country or null — one of ``, `AF`, `AL`, `DZ`, `AS`, `AD`, `AO`, `AI`, `AQ`, `AG`, `AR`, `AM`, `AW`, `AU`, `AT`, `AZ`, `BS`, `BH`, `BD`, `BB`, `BY`, `BE`, `BZ`, `BJ`, `BM`, `BT`, `BO`, `BQ`, `BA`, `BW`, `BV`, `BR`, `IO`, `BN`, `BG`, `BF`, `BI`, `CV`, `KH`, `CM`, `CA`, `KY`, `CF`, `TD`, `CL`, `CN`, `CX`, `CC`, `CO`, `KM`, `CD`, `CG`, `CK`, `CR`, `HR`, `CU`, `CW`, `CY`, `CZ`, `CI`, `DK`, `DJ`, `DM`, `DO`, `EC`, `EG`, `SV`, `GQ`, `ER`, `EE`, `SZ`, `ET`, `FK`, `FO`, `FJ`, `FI`, `FR`, `GF`, `PF`, `TF`, `GA`, `GM`, `GE`, `DE`, `GH`, `GI`, `GR`, `GL`, `GD`, `GP`, `GU`, `GT`, `GG`, `GN`, `GW`, `GY`, `HT`, `HM`, `VA`, `HN`, `HK`, `HU`, `IS`, `IN`, `ID`, `IR`, `IQ`, `IE`, `IM`, `IL`, `IT`, `JM`, `JP`, `JE`, `JO`, `KZ`, `KE`, `KI`, `KP`, `KR`, `KW`, `KG`, `LA`, `LV`, `LB`, `LS`, `LR`, `LY`, `LI`, `LT`, `LU`, `MO`, `MG`, `MW`, `MY`, `MV`, `ML`, `MT`, `MH`, `MQ`, `MR`, `MU`, `YT`, `MX`, `FM`, `MD`, `MC`, `MN`, `ME`, `MS`, `MA`, `MZ`, `MM`, `NA`, `NR`, `NP`, `NL`, `NC`, `NZ`, `NI`, `NE`, `NG`, `NU`, `NF`, `MP`, `NO`, `OM`, `PK`, `PW`, `PS`, `PA`, `PG`, `PY`, `PE`, `PH`, `PN`, `PL`, `PT`, `PR`, `QA`, `MK`, `RO`, `RU`, `RW`, `RE`, `BL`, `SH`, `KN`, `LC`, `MF`, `PM`, `VC`, `WS`, `SM`, `ST`, `SA`, `SN`, `RS`, `SC`, `SL`, `SG`, `SX`, `SK`, `SI`, `SB`, `SO`, `ZA`, `GS`, `SS`, `ES`, `LK`, `SD`, `SR`, `SJ`, `SE`, `CH`, `SY`, `TW`, `TJ`, `TZ`, `TH`, `TL`, `TG`, `TK`, `TO`, `TT`, `TN`, `TR`, `TM`, `TC`, `TV`, `UG`, `UA`, `AE`, `GB`, `UM`, `US`, `UY`, `UZ`, `VU`, `VE`, `VN`, `VG`, `VI`, `WF`, `EH`, `YE`, `ZM`, `ZW`, `AX`; The country that the object is associated with, in ISO alpha 2 code
- `management_url` (required): string or null — The URL to manage the subscription
- `redemption`: Redemption or null — Information about the most recent successful redemption of the purchase's redemption link. Only applicable to Web Billing web-to-web purchases; null if the purchase has never been successfully redeemed (or has no redemption link, e.g. purchases from other stores).
  - `object` (required): string — one of `redemption`; String representing the object's type. Objects of the same type share the same value.
  - `redeemed_at` (required): integer (format: `int64`) — The date of the most recent successful redemption of the purchase's redemption link in ms since epoch.
- `product_change`: object — The outcome of a product change request. Only present in the response to the change product endpoint. `applied` means this subscription reflects the new product; for Stripe that is a new subscription, so its `id` differs from the one the change was requested for and that one is now expired. `pending` means the change was accepted but this subscription does not reflect it yet.
  - `status` (required): string — one of `applied`, `pending`; Whether the change has been applied yet.
  - `product_id` (required): string — The RevenueCat ID of the product the subscription is changing to

### AuthenticatedManagementUrl

- Used by `GET /projects/{project_id}/subscriptions/{subscription_id}/authenticated_management_url (200) — Get an authenticated subscription management URL`

- `object` (required): string — one of `authenticated_management_url`; String representing the object's type. Objects of the same type share the same value.
- `management_url` (required): string or null — A secure URL that provides temporary access to the subscription management portal. For RC Billing subscriptions, this is a single-use magic link to the RevenueCat customer portal. For Paddle subscriptions, this is a short-lived authenticated Paddle Customer Portal URL when the API key has the Customer portal session (Write) permission and Paddle returns the required management URLs; otherwise a non-authenticated URL (customer signs in via email) or `null` if no URL can be generated.

### ListEntitlements

- Used by `GET /projects/{project_id}/subscriptions/{subscription_id}/entitlements (200) — Get a list of entitlements associated with a subscription`

- `object` (required): string — one of `list`; String representing the object's type. Objects of the same type share the same value. Always has the value `list`.
- `items` (required): array of Entitlement — Details about each object.
  - `state` (required): string — one of `active`, `inactive`; Whether the entitlement is active or inactive (archived).
  - `object` (required): string — one of `entitlement`; String representing the object's type. Objects of the same type share the same value.
  - `project_id` (required): string — length 1–20; ID of the project to which the entitlement belongs
  - `id` (required): string — length 1–255; The id of the entitlement
  - `lookup_key` (required): string — length 1–200; A custom identifier of the entitlement
  - `display_name` (required): string — length 1–1500; The display name of the entitlement
  - `created_at` (required): integer (format: `int64`) — The date when the entitlement was created in ms since epoch
  - `products`: object or null — List of products attached to the entitlement
    - `object` (required): string — one of `list`; String representing the object's type. Objects of the same type share the same value. Always has the value `list`.
    - `items` (required): array of Product — Details about each object.
    - `next_page` (required): string or null — URL to access the next page of the Entitlement's products. If not present / null, there is no next page
    - `url` (required): string — length 0–5000; The URL where this list can be accessed.
- `next_page` (required): string or null — URL to access the next page of the project's entitlements. If not present / null, there is no next page
- `url` (required): string — length 0–5000; The URL where this list can be accessed.