---
title: "Subscription"
permalink: "/docs/api-v2/subscription"
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).

# Subscription

## Subscription

Operations about subscriptions.

### Get a subscription

`GET /projects/{project_id}/subscriptions/{subscription_id}`

Operation ID: `get-subscription`

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

**Parameters**

| Name | In | Required | Description |
| --- | --- | --- | --- |
| `project_id` | path | yes | ID of the project |
| `subscription_id` | path | yes | ID of the subscription |
| `expand` | query | no | 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 `200` body**

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `object` | string | yes | String representing the object's type. Objects of the same type share the same value. One of: `subscription` |
| `id` | string | yes | The ID of the subscription (generated by RevenueCat) |
| `customer_id` | string | yes | The ID of the customer |
| `original_customer_id` | string | yes | The ID of the original customer. Relevant for subscriptions that were transferred from one customer to another |
| `product_id` | string | yes | The RevenueCat ID of the product that the customer is subscribed to. Exists for all store types except for promotional. |
| `starts_at` | integer | yes | The date when the subscription originally started in ms since epoch |
| `current_period_starts_at` | integer | yes | The date when the subscription billing period started in ms since epoch |
| `current_period_ends_at` | integer | yes | 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` | integer | yes | 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` | boolean | yes | Determines whether the customer should currently be provided access to the entitlements associated with the subscription |
| `pending_payment` | boolean | yes | Determines whether there is a pending payment associated with the subscription |
| `auto_renewal_status` | string | yes | The auto renewal status of a subscription.<br><br>Possible values:<br>• `will_renew`: the subscription is currently set to automatically renew<br>• `will_not_renew`: the subscription is currently set to expire at the end of the period<br>• `will_change_product`: the subscription is currently set to change product at the end of the period (which might start a new subscription)<br>• `will_pause`: the subscription is currently set to pause at the end of the current period<br>• `requires_price_increase_consent`: the subscription will expire at the end of the current period unless the customer consents to the price increase<br>• `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) One of: `will_renew`, `will_not_renew`, `will_change_product`, `will_pause`, `requires_price_increase_consent`, `has_already_renewed` |
| `status` | string | yes | 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.<br><br>Possible values:<br>• `trialing`: the subscription is in a free trial period<br>• `active`: the subscription is active, in a paid period<br>• `expired`: the subscription is expired and no longer active<br>• `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<br>• `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.<br>• `unknown`: the subscription is in an unknown state. Refer to the _gives_access_ field to determine whether or not to grant access.<br>• `incomplete`: the subscription is in an incomplete state, maybe due to incorrect billing details or because it's scheduled to start in the future. One of: `trialing`, `active`, `expired`, `in_grace_period`, `in_billing_retry`, `paused`, `unknown`, `incomplete` |
| `total_revenue_in_usd` | oneOf | yes | Total revenue generated by a subscription in USD |
| `presented_offering_id` | string | yes | The ID of the offering the customer saw when purchasing the subscription |
| `entitlements` | object | yes |  |
| `environment` | oneOf | yes | The store environment |
| `store` | string | yes | Store the subscription belongs to One of: `amazon`, `app_store`, `mac_app_store`, `play_store`, `promotional`, `stripe`, `rc_billing`, `external`, `roku`, `paddle`, `paypal`, `galaxy`, `test_store` |
| `store_subscription_identifier` | string | yes | 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` | oneOf | yes | Ownership of the subscription |
| `pending_changes` | object | no | 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. |
| `country` | Country | no | The country that the object is associated with, in ISO alpha 2 code One of: `null`, `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` |
| `management_url` | string | yes | The URL to manage the subscription |
| `redemption` | Redemption | no | 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). |

<details><summary><code>total_revenue_in_usd</code></summary>

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `currency` | Currency | yes | ISO 4217 currency code 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` |
| `gross` | number | yes | Total revenue generated (excluding taxes and commission) |
| `commission` | number | no | Store commission or payment processor fees deducted from gross revenue (if any) |
| `tax` | number | yes | Estimated taxes deducted from gross revenue |
| `proceeds` | number | yes | Net revenue after store commission / fees and taxes |

</details>

<details><summary><code>entitlements</code></summary>

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `object` | string | yes | String representing the object's type. Objects of the same type share the same value. Always has the value `list`. One of: `list` |
| `items` | array of Entitlement | yes | Details about each object. |
| `next_page` | string | yes | URL to access the next page of the customer's entitlements. If not present / null, there is no next page |
| `url` | string | yes | The URL where this list can be accessed. |

<details><summary><code>items</code></summary>

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `state` | string | yes | Whether the entitlement is active or inactive (archived). One of: `active`, `inactive` |
| `object` | string | yes | String representing the object's type. Objects of the same type share the same value. One of: `entitlement` |
| `project_id` | string | yes | ID of the project to which the entitlement belongs |
| `id` | string | yes | The id of the entitlement |
| `lookup_key` | string | yes | A custom identifier of the entitlement |
| `display_name` | string | yes | The display name of the entitlement |
| `created_at` | integer | yes | The date when the entitlement was created in ms since epoch |
| `products` | object | no | List of products attached to the entitlement |

</details>
</details>

<details><summary><code>pending_changes</code></summary>

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `product` | object | no | The product that will be active as of the next renewal |
| `current_period_starts_at` | integer | no | Expected start of the next billing period in ms since epoch. Omitted when unchanged from the current subscription. |
| `current_period_ends_at` | integer | no | Expected end of the next billing period in ms since epoch. Omitted when unchanged from the current subscription. |
| `store_subscription_identifier` | string | no | Expected store subscription identifier for the next period. Omitted when unchanged from the current subscription. |
| `auto_renewal_status` | string | no | Expected auto renewal status for the next period. Omitted when unchanged from the current subscription. One of: `will_renew`, `will_not_renew`, `will_change_product`, `will_pause`, `requires_price_increase_consent`, `has_already_renewed` |
| `status` | string | no | Expected subscription status for the next period. Omitted when unchanged from the current subscription. One of: `trialing`, `active`, `expired`, `in_grace_period`, `in_billing_retry`, `paused`, `unknown`, `incomplete` |
| `pending_payment` | boolean | no | Expected pending payment flag for the next period. Omitted when unchanged from the current subscription. |
| `gives_access` | boolean | no | Expected access flag for the next period. Omitted when unchanged from the current subscription. |

</details>

<details><summary><code>redemption</code></summary>

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `object` | string | yes | String representing the object's type. Objects of the same type share the same value. One of: `redemption` |
| `redeemed_at` | integer | yes | The date of the most recent successful redemption of the purchase's redemption link in ms since epoch. |

</details>
### Get a Play Store or App Store subscription's transactions

`GET /projects/{project_id}/subscriptions/{subscription_id}/transactions`

Operation ID: `get-play-store-or-app-store-subscription-transactions`

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

**Parameters**

| Name | In | Required | Description |
| --- | --- | --- | --- |
| `project_id` | path | yes | ID of the project |
| `subscription_id` | path | yes | ID of the subscription |
| `starting_after` | query | no | Pagination cursor. Pass the id of the last item from the previous page to fetch the next page; omit for the first page. |
| `limit` | query | no | Maximum number of items to return per page. Values below 1 or above 100 are clamped to that range rather than rejected. |
| `sort` | query | no | Column to sort the result list by. |
| `direction` | query | no | Sort direction for the result list. |

**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 `200` body**

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `object` | string | yes | String representing the object's type. Objects of the same type share the same value. Always has the value `list`. One of: `list` |
| `items` | array of SubscriptionTransaction | yes | Details about each object. |
| `next_page` | string | yes | URL to access the next page of the projects. If not present / null, there is no next page |
| `url` | string | yes | The URL where this list can be accessed. |

<details><summary><code>items</code></summary>

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `object` | string | yes | String representing the object's type. Objects of the same type share the same value. One of: `subscription_transaction` |
| `id` | string | yes | The ID of the subscription transaction in the store |
| `purchased_at` | integer | yes | The date of the transaction in ms since epoch |
| `product_store_identifier` | string | yes | The store identifier of the purchased product |
| `revenue_in_local_currency` | oneOf | no | The revenue generated by the transaction in the customer's purchased currency |
| `revenue_in_usd` | oneOf | no | The revenue generated by the transaction in USD |
| `expiration_date` | integer | no | The expiration date of the transaction in ms since epoch |
| `effective_expiration_date` | integer | no | The effective expiration date of the transaction in ms since epoch, including potential grace period |

</details>
### Refund a Play Store or Galaxy subscription's transaction

`POST /projects/{project_id}/subscriptions/{subscription_id}/transactions/{transaction_id}/actions/refund`

Operation ID: `refund-play-store-or-galaxy-subscription-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): <code>customer_information:subscriptions:read_write</code>. This endpoint belongs to the <strong>Subscription Transactions Refunds</strong> domain, which has a default rate limit of <strong>480 requests per minute</strong>.

**Parameters**

| Name | In | Required | Description |
| --- | --- | --- | --- |
| `project_id` | path | yes | ID of the project |
| `subscription_id` | path | yes | ID of the subscription |
| `transaction_id` | path | yes | Identifier of the transaction in the store |

**Responses**

- `200` — Success
- `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 `200` body**

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `object` | string | yes | String representing the object's type. Objects of the same type share the same value. One of: `subscription_transaction` |
| `id` | string | yes | The ID of the subscription transaction in the store |
| `purchased_at` | integer | yes | The date of the transaction in ms since epoch |
| `product_store_identifier` | string | yes | The store identifier of the purchased product |
| `revenue_in_local_currency` | oneOf | no | The revenue generated by the transaction in the customer's purchased currency |
| `revenue_in_usd` | oneOf | no | The revenue generated by the transaction in USD |
| `expiration_date` | integer | no | The expiration date of the transaction in ms since epoch |
| `effective_expiration_date` | integer | no | The effective expiration date of the transaction in ms since epoch, including potential grace period |

<details><summary><code>revenue_in_local_currency</code></summary>

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `currency` | Currency | yes | ISO 4217 currency code 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` |
| `gross` | number | yes | Total revenue generated (excluding taxes and commission) |
| `commission` | number | no | Store commission or payment processor fees deducted from gross revenue (if any) |
| `tax` | number | yes | Estimated taxes deducted from gross revenue |
| `proceeds` | number | yes | Net revenue after store commission / fees and taxes |

</details>

<details><summary><code>revenue_in_usd</code></summary>

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `currency` | Currency | yes | ISO 4217 currency code 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` |
| `gross` | number | yes | Total revenue generated (excluding taxes and commission) |
| `commission` | number | no | Store commission or payment processor fees deducted from gross revenue (if any) |
| `tax` | number | yes | Estimated taxes deducted from gross revenue |
| `proceeds` | number | yes | Net revenue after store commission / fees and taxes |

</details>
### Get a list of entitlements associated with a subscription

`GET /projects/{project_id}/subscriptions/{subscription_id}/entitlements`

Operation ID: `list-subscription-entitlements`

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

**Parameters**

| Name | In | Required | Description |
| --- | --- | --- | --- |
| `project_id` | path | yes | ID of the project |
| `subscription_id` | path | yes | ID of the subscription |
| `starting_after` | query | no | Pagination cursor. Pass the id of the last item from the previous page to fetch the next page; omit for the first page. |
| `limit` | query | no | 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 `200` body**

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `object` | string | yes | String representing the object's type. Objects of the same type share the same value. Always has the value `list`. One of: `list` |
| `items` | array of Entitlement | yes | Details about each object. |
| `next_page` | string | yes | URL to access the next page of the project's entitlements. If not present / null, there is no next page |
| `url` | string | yes | The URL where this list can be accessed. |

<details><summary><code>items</code></summary>

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `state` | string | yes | Whether the entitlement is active or inactive (archived). One of: `active`, `inactive` |
| `object` | string | yes | String representing the object's type. Objects of the same type share the same value. One of: `entitlement` |
| `project_id` | string | yes | ID of the project to which the entitlement belongs |
| `id` | string | yes | The id of the entitlement |
| `lookup_key` | string | yes | A custom identifier of the entitlement |
| `display_name` | string | yes | The display name of the entitlement |
| `created_at` | integer | yes | The date when the entitlement was created in ms since epoch |
| `products` | object | no | List of products attached to the entitlement |

<details><summary><code>products</code></summary>

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `object` | string | yes | String representing the object's type. Objects of the same type share the same value. Always has the value `list`. One of: `list` |
| `items` | array of Product | yes | Details about each object. |
| `next_page` | string | yes | URL to access the next page of the Entitlement's products. If not present / null, there is no next page |
| `url` | string | yes | The URL where this list can be accessed. |

</details>
</details>
### Cancel an active Web Billing subscription

`POST /projects/{project_id}/subscriptions/{subscription_id}/actions/cancel`

Operation ID: `cancel-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): <code>customer_information:subscriptions:read_write</code>. This endpoint belongs to the <strong>Customer Information</strong> domain, which has a default rate limit of <strong>480 requests per minute</strong>.

**Parameters**

| Name | In | Required | Description |
| --- | --- | --- | --- |
| `project_id` | path | yes | ID of the project |
| `subscription_id` | path | yes | 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 `200` body**

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `object` | string | yes | String representing the object's type. Objects of the same type share the same value. One of: `subscription` |
| `id` | string | yes | The ID of the subscription (generated by RevenueCat) |
| `customer_id` | string | yes | The ID of the customer |
| `original_customer_id` | string | yes | The ID of the original customer. Relevant for subscriptions that were transferred from one customer to another |
| `product_id` | string | yes | The RevenueCat ID of the product that the customer is subscribed to. Exists for all store types except for promotional. |
| `starts_at` | integer | yes | The date when the subscription originally started in ms since epoch |
| `current_period_starts_at` | integer | yes | The date when the subscription billing period started in ms since epoch |
| `current_period_ends_at` | integer | yes | 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` | integer | yes | 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` | boolean | yes | Determines whether the customer should currently be provided access to the entitlements associated with the subscription |
| `pending_payment` | boolean | yes | Determines whether there is a pending payment associated with the subscription |
| `auto_renewal_status` | string | yes | The auto renewal status of a subscription.<br><br>Possible values:<br>• `will_renew`: the subscription is currently set to automatically renew<br>• `will_not_renew`: the subscription is currently set to expire at the end of the period<br>• `will_change_product`: the subscription is currently set to change product at the end of the period (which might start a new subscription)<br>• `will_pause`: the subscription is currently set to pause at the end of the current period<br>• `requires_price_increase_consent`: the subscription will expire at the end of the current period unless the customer consents to the price increase<br>• `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) One of: `will_renew`, `will_not_renew`, `will_change_product`, `will_pause`, `requires_price_increase_consent`, `has_already_renewed` |
| `status` | string | yes | 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.<br><br>Possible values:<br>• `trialing`: the subscription is in a free trial period<br>• `active`: the subscription is active, in a paid period<br>• `expired`: the subscription is expired and no longer active<br>• `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<br>• `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.<br>• `unknown`: the subscription is in an unknown state. Refer to the _gives_access_ field to determine whether or not to grant access.<br>• `incomplete`: the subscription is in an incomplete state, maybe due to incorrect billing details or because it's scheduled to start in the future. One of: `trialing`, `active`, `expired`, `in_grace_period`, `in_billing_retry`, `paused`, `unknown`, `incomplete` |
| `total_revenue_in_usd` | oneOf | yes | Total revenue generated by a subscription in USD |
| `presented_offering_id` | string | yes | The ID of the offering the customer saw when purchasing the subscription |
| `entitlements` | object | yes |  |
| `environment` | oneOf | yes | The store environment |
| `store` | string | yes | Store the subscription belongs to One of: `amazon`, `app_store`, `mac_app_store`, `play_store`, `promotional`, `stripe`, `rc_billing`, `external`, `roku`, `paddle`, `paypal`, `galaxy`, `test_store` |
| `store_subscription_identifier` | string | yes | 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` | oneOf | yes | Ownership of the subscription |
| `pending_changes` | object | no | 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. |
| `country` | Country | no | The country that the object is associated with, in ISO alpha 2 code One of: `null`, `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` |
| `management_url` | string | yes | The URL to manage the subscription |
| `redemption` | Redemption | no | 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). |

<details><summary><code>total_revenue_in_usd</code></summary>

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `currency` | Currency | yes | ISO 4217 currency code 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` |
| `gross` | number | yes | Total revenue generated (excluding taxes and commission) |
| `commission` | number | no | Store commission or payment processor fees deducted from gross revenue (if any) |
| `tax` | number | yes | Estimated taxes deducted from gross revenue |
| `proceeds` | number | yes | Net revenue after store commission / fees and taxes |

</details>

<details><summary><code>entitlements</code></summary>

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `object` | string | yes | String representing the object's type. Objects of the same type share the same value. Always has the value `list`. One of: `list` |
| `items` | array of Entitlement | yes | Details about each object. |
| `next_page` | string | yes | URL to access the next page of the customer's entitlements. If not present / null, there is no next page |
| `url` | string | yes | The URL where this list can be accessed. |

<details><summary><code>items</code></summary>

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `state` | string | yes | Whether the entitlement is active or inactive (archived). One of: `active`, `inactive` |
| `object` | string | yes | String representing the object's type. Objects of the same type share the same value. One of: `entitlement` |
| `project_id` | string | yes | ID of the project to which the entitlement belongs |
| `id` | string | yes | The id of the entitlement |
| `lookup_key` | string | yes | A custom identifier of the entitlement |
| `display_name` | string | yes | The display name of the entitlement |
| `created_at` | integer | yes | The date when the entitlement was created in ms since epoch |
| `products` | object | no | List of products attached to the entitlement |

</details>
</details>

<details><summary><code>pending_changes</code></summary>

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `product` | object | no | The product that will be active as of the next renewal |
| `current_period_starts_at` | integer | no | Expected start of the next billing period in ms since epoch. Omitted when unchanged from the current subscription. |
| `current_period_ends_at` | integer | no | Expected end of the next billing period in ms since epoch. Omitted when unchanged from the current subscription. |
| `store_subscription_identifier` | string | no | Expected store subscription identifier for the next period. Omitted when unchanged from the current subscription. |
| `auto_renewal_status` | string | no | Expected auto renewal status for the next period. Omitted when unchanged from the current subscription. One of: `will_renew`, `will_not_renew`, `will_change_product`, `will_pause`, `requires_price_increase_consent`, `has_already_renewed` |
| `status` | string | no | Expected subscription status for the next period. Omitted when unchanged from the current subscription. One of: `trialing`, `active`, `expired`, `in_grace_period`, `in_billing_retry`, `paused`, `unknown`, `incomplete` |
| `pending_payment` | boolean | no | Expected pending payment flag for the next period. Omitted when unchanged from the current subscription. |
| `gives_access` | boolean | no | Expected access flag for the next period. Omitted when unchanged from the current subscription. |

</details>

<details><summary><code>redemption</code></summary>

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `object` | string | yes | String representing the object's type. Objects of the same type share the same value. One of: `redemption` |
| `redeemed_at` | integer | yes | The date of the most recent successful redemption of the purchase's redemption link in ms since epoch. |

</details>
### Extend the current billing period of a subscription

`POST /projects/{project_id}/subscriptions/{subscription_id}/actions/extend`

Operation ID: `extend-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): <code>customer_information:subscriptions:read_write</code>. This endpoint belongs to the <strong>Customer Information</strong> domain, which has a default rate limit of <strong>480 requests per minute</strong>.

**Parameters**

| Name | In | Required | Description |
| --- | --- | --- | --- |
| `project_id` | path | yes | ID of the project |
| `subscription_id` | path | yes | ID of the subscription |

**Request body**

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `extend_by_days` | integer | yes | Number of days to extend the current billing period by. For Apple Store subscriptions, the maximum allowed value is 90. |
| `extend_reason_code` | string | no | Reason for the extension. Required for Apple Store subscriptions; ignored for Google Play and Web Billing subscriptions. One of: `undeclared`, `customer_satisfaction`, `other`, `service_issue_or_outage` |

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `extend_until_ms` | integer | yes | Absolute epoch timestamp (in milliseconds) to which the current billing period should be extended. Must be after the subscription's current `current_period_ends_at`. For Apple Store subscriptions, the resulting extension cannot exceed 90 days. |
| `extend_reason_code` | string | no | Reason for the extension. Required for Apple Store subscriptions; ignored for Google Play and Web Billing subscriptions. One of: `undeclared`, `customer_satisfaction`, `other`, `service_issue_or_outage` |

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

**Response `200` body**

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `object` | string | yes | String representing the object's type. Objects of the same type share the same value. One of: `subscription` |
| `id` | string | yes | The ID of the subscription (generated by RevenueCat) |
| `customer_id` | string | yes | The ID of the customer |
| `original_customer_id` | string | yes | The ID of the original customer. Relevant for subscriptions that were transferred from one customer to another |
| `product_id` | string | yes | The RevenueCat ID of the product that the customer is subscribed to. Exists for all store types except for promotional. |
| `starts_at` | integer | yes | The date when the subscription originally started in ms since epoch |
| `current_period_starts_at` | integer | yes | The date when the subscription billing period started in ms since epoch |
| `current_period_ends_at` | integer | yes | 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` | integer | yes | 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` | boolean | yes | Determines whether the customer should currently be provided access to the entitlements associated with the subscription |
| `pending_payment` | boolean | yes | Determines whether there is a pending payment associated with the subscription |
| `auto_renewal_status` | string | yes | The auto renewal status of a subscription.<br><br>Possible values:<br>• `will_renew`: the subscription is currently set to automatically renew<br>• `will_not_renew`: the subscription is currently set to expire at the end of the period<br>• `will_change_product`: the subscription is currently set to change product at the end of the period (which might start a new subscription)<br>• `will_pause`: the subscription is currently set to pause at the end of the current period<br>• `requires_price_increase_consent`: the subscription will expire at the end of the current period unless the customer consents to the price increase<br>• `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) One of: `will_renew`, `will_not_renew`, `will_change_product`, `will_pause`, `requires_price_increase_consent`, `has_already_renewed` |
| `status` | string | yes | 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.<br><br>Possible values:<br>• `trialing`: the subscription is in a free trial period<br>• `active`: the subscription is active, in a paid period<br>• `expired`: the subscription is expired and no longer active<br>• `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<br>• `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.<br>• `unknown`: the subscription is in an unknown state. Refer to the _gives_access_ field to determine whether or not to grant access.<br>• `incomplete`: the subscription is in an incomplete state, maybe due to incorrect billing details or because it's scheduled to start in the future. One of: `trialing`, `active`, `expired`, `in_grace_period`, `in_billing_retry`, `paused`, `unknown`, `incomplete` |
| `total_revenue_in_usd` | oneOf | yes | Total revenue generated by a subscription in USD |
| `presented_offering_id` | string | yes | The ID of the offering the customer saw when purchasing the subscription |
| `entitlements` | object | yes |  |
| `environment` | oneOf | yes | The store environment |
| `store` | string | yes | Store the subscription belongs to One of: `amazon`, `app_store`, `mac_app_store`, `play_store`, `promotional`, `stripe`, `rc_billing`, `external`, `roku`, `paddle`, `paypal`, `galaxy`, `test_store` |
| `store_subscription_identifier` | string | yes | 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` | oneOf | yes | Ownership of the subscription |
| `pending_changes` | object | no | 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. |
| `country` | Country | no | The country that the object is associated with, in ISO alpha 2 code One of: `null`, `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` |
| `management_url` | string | yes | The URL to manage the subscription |
| `redemption` | Redemption | no | 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). |

<details><summary><code>total_revenue_in_usd</code></summary>

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `currency` | Currency | yes | ISO 4217 currency code 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` |
| `gross` | number | yes | Total revenue generated (excluding taxes and commission) |
| `commission` | number | no | Store commission or payment processor fees deducted from gross revenue (if any) |
| `tax` | number | yes | Estimated taxes deducted from gross revenue |
| `proceeds` | number | yes | Net revenue after store commission / fees and taxes |

</details>

<details><summary><code>entitlements</code></summary>

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `object` | string | yes | String representing the object's type. Objects of the same type share the same value. Always has the value `list`. One of: `list` |
| `items` | array of Entitlement | yes | Details about each object. |
| `next_page` | string | yes | URL to access the next page of the customer's entitlements. If not present / null, there is no next page |
| `url` | string | yes | The URL where this list can be accessed. |

<details><summary><code>items</code></summary>

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `state` | string | yes | Whether the entitlement is active or inactive (archived). One of: `active`, `inactive` |
| `object` | string | yes | String representing the object's type. Objects of the same type share the same value. One of: `entitlement` |
| `project_id` | string | yes | ID of the project to which the entitlement belongs |
| `id` | string | yes | The id of the entitlement |
| `lookup_key` | string | yes | A custom identifier of the entitlement |
| `display_name` | string | yes | The display name of the entitlement |
| `created_at` | integer | yes | The date when the entitlement was created in ms since epoch |
| `products` | object | no | List of products attached to the entitlement |

</details>
</details>

<details><summary><code>pending_changes</code></summary>

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `product` | object | no | The product that will be active as of the next renewal |
| `current_period_starts_at` | integer | no | Expected start of the next billing period in ms since epoch. Omitted when unchanged from the current subscription. |
| `current_period_ends_at` | integer | no | Expected end of the next billing period in ms since epoch. Omitted when unchanged from the current subscription. |
| `store_subscription_identifier` | string | no | Expected store subscription identifier for the next period. Omitted when unchanged from the current subscription. |
| `auto_renewal_status` | string | no | Expected auto renewal status for the next period. Omitted when unchanged from the current subscription. One of: `will_renew`, `will_not_renew`, `will_change_product`, `will_pause`, `requires_price_increase_consent`, `has_already_renewed` |
| `status` | string | no | Expected subscription status for the next period. Omitted when unchanged from the current subscription. One of: `trialing`, `active`, `expired`, `in_grace_period`, `in_billing_retry`, `paused`, `unknown`, `incomplete` |
| `pending_payment` | boolean | no | Expected pending payment flag for the next period. Omitted when unchanged from the current subscription. |
| `gives_access` | boolean | no | Expected access flag for the next period. Omitted when unchanged from the current subscription. |

</details>

<details><summary><code>redemption</code></summary>

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `object` | string | yes | String representing the object's type. Objects of the same type share the same value. One of: `redemption` |
| `redeemed_at` | integer | yes | The date of the most recent successful redemption of the purchase's redemption link in ms since epoch. |

</details>
### Refund an active Web Billing subscription

`POST /projects/{project_id}/subscriptions/{subscription_id}/actions/refund`

Operation ID: `refund-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): <code>customer_information:subscriptions:read_write</code>. This endpoint belongs to the <strong>Customer Information</strong> domain, which has a default rate limit of <strong>480 requests per minute</strong>.

**Parameters**

| Name | In | Required | Description |
| --- | --- | --- | --- |
| `project_id` | path | yes | ID of the project |
| `subscription_id` | path | yes | 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 `200` body**

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `object` | string | yes | String representing the object's type. Objects of the same type share the same value. One of: `subscription` |
| `id` | string | yes | The ID of the subscription (generated by RevenueCat) |
| `customer_id` | string | yes | The ID of the customer |
| `original_customer_id` | string | yes | The ID of the original customer. Relevant for subscriptions that were transferred from one customer to another |
| `product_id` | string | yes | The RevenueCat ID of the product that the customer is subscribed to. Exists for all store types except for promotional. |
| `starts_at` | integer | yes | The date when the subscription originally started in ms since epoch |
| `current_period_starts_at` | integer | yes | The date when the subscription billing period started in ms since epoch |
| `current_period_ends_at` | integer | yes | 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` | integer | yes | 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` | boolean | yes | Determines whether the customer should currently be provided access to the entitlements associated with the subscription |
| `pending_payment` | boolean | yes | Determines whether there is a pending payment associated with the subscription |
| `auto_renewal_status` | string | yes | The auto renewal status of a subscription.<br><br>Possible values:<br>• `will_renew`: the subscription is currently set to automatically renew<br>• `will_not_renew`: the subscription is currently set to expire at the end of the period<br>• `will_change_product`: the subscription is currently set to change product at the end of the period (which might start a new subscription)<br>• `will_pause`: the subscription is currently set to pause at the end of the current period<br>• `requires_price_increase_consent`: the subscription will expire at the end of the current period unless the customer consents to the price increase<br>• `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) One of: `will_renew`, `will_not_renew`, `will_change_product`, `will_pause`, `requires_price_increase_consent`, `has_already_renewed` |
| `status` | string | yes | 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.<br><br>Possible values:<br>• `trialing`: the subscription is in a free trial period<br>• `active`: the subscription is active, in a paid period<br>• `expired`: the subscription is expired and no longer active<br>• `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<br>• `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.<br>• `unknown`: the subscription is in an unknown state. Refer to the _gives_access_ field to determine whether or not to grant access.<br>• `incomplete`: the subscription is in an incomplete state, maybe due to incorrect billing details or because it's scheduled to start in the future. One of: `trialing`, `active`, `expired`, `in_grace_period`, `in_billing_retry`, `paused`, `unknown`, `incomplete` |
| `total_revenue_in_usd` | oneOf | yes | Total revenue generated by a subscription in USD |
| `presented_offering_id` | string | yes | The ID of the offering the customer saw when purchasing the subscription |
| `entitlements` | object | yes |  |
| `environment` | oneOf | yes | The store environment |
| `store` | string | yes | Store the subscription belongs to One of: `amazon`, `app_store`, `mac_app_store`, `play_store`, `promotional`, `stripe`, `rc_billing`, `external`, `roku`, `paddle`, `paypal`, `galaxy`, `test_store` |
| `store_subscription_identifier` | string | yes | 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` | oneOf | yes | Ownership of the subscription |
| `pending_changes` | object | no | 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. |
| `country` | Country | no | The country that the object is associated with, in ISO alpha 2 code One of: `null`, `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` |
| `management_url` | string | yes | The URL to manage the subscription |
| `redemption` | Redemption | no | 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). |

<details><summary><code>total_revenue_in_usd</code></summary>

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `currency` | Currency | yes | ISO 4217 currency code 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` |
| `gross` | number | yes | Total revenue generated (excluding taxes and commission) |
| `commission` | number | no | Store commission or payment processor fees deducted from gross revenue (if any) |
| `tax` | number | yes | Estimated taxes deducted from gross revenue |
| `proceeds` | number | yes | Net revenue after store commission / fees and taxes |

</details>

<details><summary><code>entitlements</code></summary>

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `object` | string | yes | String representing the object's type. Objects of the same type share the same value. Always has the value `list`. One of: `list` |
| `items` | array of Entitlement | yes | Details about each object. |
| `next_page` | string | yes | URL to access the next page of the customer's entitlements. If not present / null, there is no next page |
| `url` | string | yes | The URL where this list can be accessed. |

<details><summary><code>items</code></summary>

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `state` | string | yes | Whether the entitlement is active or inactive (archived). One of: `active`, `inactive` |
| `object` | string | yes | String representing the object's type. Objects of the same type share the same value. One of: `entitlement` |
| `project_id` | string | yes | ID of the project to which the entitlement belongs |
| `id` | string | yes | The id of the entitlement |
| `lookup_key` | string | yes | A custom identifier of the entitlement |
| `display_name` | string | yes | The display name of the entitlement |
| `created_at` | integer | yes | The date when the entitlement was created in ms since epoch |
| `products` | object | no | List of products attached to the entitlement |

</details>
</details>

<details><summary><code>pending_changes</code></summary>

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `product` | object | no | The product that will be active as of the next renewal |
| `current_period_starts_at` | integer | no | Expected start of the next billing period in ms since epoch. Omitted when unchanged from the current subscription. |
| `current_period_ends_at` | integer | no | Expected end of the next billing period in ms since epoch. Omitted when unchanged from the current subscription. |
| `store_subscription_identifier` | string | no | Expected store subscription identifier for the next period. Omitted when unchanged from the current subscription. |
| `auto_renewal_status` | string | no | Expected auto renewal status for the next period. Omitted when unchanged from the current subscription. One of: `will_renew`, `will_not_renew`, `will_change_product`, `will_pause`, `requires_price_increase_consent`, `has_already_renewed` |
| `status` | string | no | Expected subscription status for the next period. Omitted when unchanged from the current subscription. One of: `trialing`, `active`, `expired`, `in_grace_period`, `in_billing_retry`, `paused`, `unknown`, `incomplete` |
| `pending_payment` | boolean | no | Expected pending payment flag for the next period. Omitted when unchanged from the current subscription. |
| `gives_access` | boolean | no | Expected access flag for the next period. Omitted when unchanged from the current subscription. |

</details>

<details><summary><code>redemption</code></summary>

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `object` | string | yes | String representing the object's type. Objects of the same type share the same value. One of: `redemption` |
| `redeemed_at` | integer | yes | The date of the most recent successful redemption of the purchase's redemption link in ms since epoch. |

</details>
### Get an authenticated subscription management URL

`GET /projects/{project_id}/subscriptions/{subscription_id}/authenticated_management_url`

Operation ID: `get-authorized-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): <code>customer_information:subscriptions:read</code>. This endpoint belongs to the <strong>Customer Information</strong> domain, which has a default rate limit of <strong>480 requests per minute</strong>.

**Parameters**

| Name | In | Required | Description |
| --- | --- | --- | --- |
| `project_id` | path | yes | ID of the project |
| `subscription_id` | path | yes | 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 `200` body**

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `object` | string | yes | String representing the object's type. Objects of the same type share the same value. One of: `authenticated_management_url` |
| `management_url` | string | yes | 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. |

### Search subscriptions by store subscription identifier

`GET /projects/{project_id}/subscriptions`

Operation ID: `search-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): <code>customer_information:subscriptions:read</code>. This endpoint belongs to the <strong>Customer Information</strong> domain, which has a default rate limit of <strong>480 requests per minute</strong>.

**Parameters**

| Name | In | Required | Description |
| --- | --- | --- | --- |
| `project_id` | path | yes | ID of the project |
| `store_subscription_identifier` | query | yes | Store ID associated with the subscription for the current or next period. |
| `include_scheduled` | query | no | When true, includes subscriptions scheduled to start in the future in the response. |
| `expand` | query | no | 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 `200` body**

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `object` | string | yes | String representing the object's type. Objects of the same type share the same value. Always has the value `list`. One of: `list` |
| `items` | array of Subscription | yes | Details about each object. |
| `next_page` | string | yes | URL to access the next page of the customer's subscriptions. If not present / null, there is no next page |
| `url` | string | yes | The URL where this list can be accessed. |

<details><summary><code>items</code></summary>

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `object` | string | yes | String representing the object's type. Objects of the same type share the same value. One of: `subscription` |
| `id` | string | yes | The ID of the subscription (generated by RevenueCat) |
| `customer_id` | string | yes | The ID of the customer |
| `original_customer_id` | string | yes | The ID of the original customer. Relevant for subscriptions that were transferred from one customer to another |
| `product_id` | string | yes | The RevenueCat ID of the product that the customer is subscribed to. Exists for all store types except for promotional. |
| `starts_at` | integer | yes | The date when the subscription originally started in ms since epoch |
| `current_period_starts_at` | integer | yes | The date when the subscription billing period started in ms since epoch |
| `current_period_ends_at` | integer | yes | 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` | integer | yes | 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` | boolean | yes | Determines whether the customer should currently be provided access to the entitlements associated with the subscription |
| `pending_payment` | boolean | yes | Determines whether there is a pending payment associated with the subscription |
| `auto_renewal_status` | string | yes | The auto renewal status of a subscription.<br><br>Possible values:<br>• `will_renew`: the subscription is currently set to automatically renew<br>• `will_not_renew`: the subscription is currently set to expire at the end of the period<br>• `will_change_product`: the subscription is currently set to change product at the end of the period (which might start a new subscription)<br>• `will_pause`: the subscription is currently set to pause at the end of the current period<br>• `requires_price_increase_consent`: the subscription will expire at the end of the current period unless the customer consents to the price increase<br>• `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) One of: `will_renew`, `will_not_renew`, `will_change_product`, `will_pause`, `requires_price_increase_consent`, `has_already_renewed` |
| `status` | string | yes | 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.<br><br>Possible values:<br>• `trialing`: the subscription is in a free trial period<br>• `active`: the subscription is active, in a paid period<br>• `expired`: the subscription is expired and no longer active<br>• `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<br>• `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.<br>• `unknown`: the subscription is in an unknown state. Refer to the _gives_access_ field to determine whether or not to grant access.<br>• `incomplete`: the subscription is in an incomplete state, maybe due to incorrect billing details or because it's scheduled to start in the future. One of: `trialing`, `active`, `expired`, `in_grace_period`, `in_billing_retry`, `paused`, `unknown`, `incomplete` |
| `total_revenue_in_usd` | oneOf | yes | Total revenue generated by a subscription in USD |
| `presented_offering_id` | string | yes | The ID of the offering the customer saw when purchasing the subscription |
| `entitlements` | object | yes |  |
| `environment` | oneOf | yes | The store environment |
| `store` | string | yes | Store the subscription belongs to One of: `amazon`, `app_store`, `mac_app_store`, `play_store`, `promotional`, `stripe`, `rc_billing`, `external`, `roku`, `paddle`, `paypal`, `galaxy`, `test_store` |
| `store_subscription_identifier` | string | yes | 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` | oneOf | yes | Ownership of the subscription |
| `pending_changes` | object | no | 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. |
| `country` | Country | no | The country that the object is associated with, in ISO alpha 2 code One of: `null`, `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` |
| `management_url` | string | yes | The URL to manage the subscription |
| `redemption` | Redemption | no | 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). |

<details><summary><code>entitlements</code></summary>

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `object` | string | yes | String representing the object's type. Objects of the same type share the same value. Always has the value `list`. One of: `list` |
| `items` | array of Entitlement | yes | Details about each object. |
| `next_page` | string | yes | URL to access the next page of the customer's entitlements. If not present / null, there is no next page |
| `url` | string | yes | The URL where this list can be accessed. |

</details>

<details><summary><code>pending_changes</code></summary>

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `product` | object | no | The product that will be active as of the next renewal |
| `current_period_starts_at` | integer | no | Expected start of the next billing period in ms since epoch. Omitted when unchanged from the current subscription. |
| `current_period_ends_at` | integer | no | Expected end of the next billing period in ms since epoch. Omitted when unchanged from the current subscription. |
| `store_subscription_identifier` | string | no | Expected store subscription identifier for the next period. Omitted when unchanged from the current subscription. |
| `auto_renewal_status` | string | no | Expected auto renewal status for the next period. Omitted when unchanged from the current subscription. One of: `will_renew`, `will_not_renew`, `will_change_product`, `will_pause`, `requires_price_increase_consent`, `has_already_renewed` |
| `status` | string | no | Expected subscription status for the next period. Omitted when unchanged from the current subscription. One of: `trialing`, `active`, `expired`, `in_grace_period`, `in_billing_retry`, `paused`, `unknown`, `incomplete` |
| `pending_payment` | boolean | no | Expected pending payment flag for the next period. Omitted when unchanged from the current subscription. |
| `gives_access` | boolean | no | Expected access flag for the next period. Omitted when unchanged from the current subscription. |

</details>

<details><summary><code>redemption</code></summary>

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `object` | string | yes | String representing the object's type. Objects of the same type share the same value. One of: `redemption` |
| `redeemed_at` | integer | yes | The date of the most recent successful redemption of the purchase's redemption link in ms since epoch. |

</details>
</details>