---
title: "Customer Resources"
permalink: "/docs/api-v2/customer/resources"
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).

# Customer Resources

## Customer

Operations about customers.

### Get customer center configuration

`GET /projects/{project_id}/customers/{customer_id}/customer_center`

Operation ID: `get-customer-center-config`

This endpoint requires the following permission(s): <code>customer_information:customers: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 |
| `customer_id` | path | yes | ID of the customer |
| `platform` | query | no | The platform to process the Customer Center configuration for. When provided, returns the locale-selected, platform-filtered configuration the customer would see. When omitted, returns the full unprocessed configuration for all platforms. Must match a store configured on this project. |
| `locale` | query | no | BCP 47 locale string (e.g. en_US) used to select the appropriate localization when platform is provided. When omitted, the configuration's default locale is used. Has no effect if platform is not provided. |

**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: `customer_center_config` |
| `customer_center` | object | yes | The Customer Center configuration. When no platform is specified, contains the full configuration for all platforms and locales. When a platform is specified, contains the processed configuration for that platform and locale. |

### Get a list of subscriptions associated with a customer

`GET /projects/{project_id}/customers/{customer_id}/subscriptions`

Operation ID: `list-subscriptions`

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 |
| `customer_id` | path | yes | ID of the customer |
| `environment` | query | no | Filter by environment, omit to include both. |
| `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. |
| `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>
### Get a list of purchases associated with a customer

`GET /projects/{project_id}/customers/{customer_id}/purchases`

Operation ID: `list-purchases`

This endpoint requires the following permission(s): <code>customer_information:purchases: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 |
| `customer_id` | path | yes | ID of the customer |
| `environment` | query | no | Filter by environment, omit to include both. |
| `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. |
| `expand` | query | no | Specifies which fields in the response should be expanded. Accepted values are: `items.redemption` (requires `customer_information:purchases: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 Purchase | yes | Details about each object. |
| `next_page` | string | yes | URL to access the next page of the customer's purchases. 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: `purchase` |
| `id` | string | yes | The id of the purchase |
| `customer_id` | string | yes | The id of the customer |
| `original_customer_id` | string | yes | The ID of the original customer |
| `product_id` | string | yes | The ID of the product that was purchased |
| `purchased_at` | integer | yes | The date when the purchase was made in ms since epoch |
| `revenue_in_usd` | oneOf | yes | The revenue generated by the purchase in USD |
| `quantity` | integer | yes | The quantity of the product purchased in one transaction |
| `status` | string | yes | The status of a purchase One of: `owned`, `refunded` |
| `presented_offering_id` | string | yes | The ID of the offering the customer saw when they did the purchase |
| `entitlements` | object | yes |  |
| `environment` | Environment | yes | The store environment One of: `production`, `sandbox` |
| `store` | string | yes | Store the purchase belongs to One of: `amazon`, `app_store`, `mac_app_store`, `play_store`, `promotional`, `stripe`, `rc_billing`, `external`, `roku`, `paddle`, `paypal`, `galaxy`, `test_store` |
| `store_purchase_identifier` | string | yes | The store purchase identifier |
| `ownership` | oneOf | yes | Ownership of the purchase |
| `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` |
| `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>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>
### Get a list of customer's active entitlements

`GET /projects/{project_id}/customers/{customer_id}/active_entitlements`

Operation ID: `list-customer-active-entitlements`

This endpoint requires the following permission(s): <code>customer_information:customers: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 |
| `customer_id` | path | yes | ID of the customer |
| `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 CustomerEntitlement | yes | Details about each object. |
| `next_page` | string | yes | URL to access the next page of the customer's active 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 |
| --- | --- | --- | --- |
| `object` | string | yes | String representing the object's type. Objects of the same type share the same value. One of: `customer.active_entitlement` |
| `entitlement_id` | string | yes | ID of the entitlement granted to the customer |
| `expires_at` | integer | yes | The date after which the access to the entitlement expires in ms since epoch |

</details>
### Get a list of the customer's events

`GET /projects/{project_id}/customers/{customer_id}/events`

Operation ID: `list-customer-events`

This endpoint requires the following permission(s): <code>customer_information:customers: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 |
| `customer_id` | path | yes | ID of the customer |
| `environment` | query | no | Filter by environment, omit to include both. |
| `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 CustomerEvent | yes | Details about each event. |
| `next_page` | string | yes | URL to access the next page of customer events. 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: `customer.event` |
| `id` | string | yes | The identifier of the event. |
| `app_id` | string | no | The ID of the app associated with the event. |
| `type` | string | yes | The type of event. |
| `body` | object | yes | Event payload. Fields vary by event type. |
| `created_at` | integer | yes | The creation date of the event in RevenueCat. |
| `occurred_at` | integer | no | The date when the event occurred, sourced from event_timestamp_ms when available. |

</details>
### Get a list of customer's virtual currencies balances

`GET /projects/{project_id}/customers/{customer_id}/virtual_currencies`

Operation ID: `list-virtual-currencies-balances`

This endpoint requires the following permission(s): <code>customer_information:purchases:read</code>. This endpoint belongs to the <strong>Virtual Currencies</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 |
| `customer_id` | path | yes | ID of the customer |
| `include_empty_balances` | query | no | Whether to include virtual currencies with a zero balance (default false). |
| `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. One of: `list` |
| `items` | array of VirtualCurrencyBalance | yes | Details about each object. |
| `next_page` | string | yes | URL to access the next page of the customer's balances. 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: `virtual_currency_balance` |
| `currency_code` | string | yes | The code of the virtual currency. |
| `balance` | integer | yes | The balance of the virtual currency. |
| `description` | string | no | The description of the virtual currency. |
| `name` | string | no | The name of the virtual currency. |

</details>
### Create a virtual currencies transaction

`POST /projects/{project_id}/customers/{customer_id}/virtual_currencies/transactions`

Operation ID: `create-virtual-currencies-transaction`

This endpoint requires the following permission(s): <code>customer_information:purchases:read_write</code>. This endpoint belongs to the <strong>Virtual Currencies</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 |
| `customer_id` | path | yes | ID of the customer |
| `Idempotency-Key` | header | no | This is an optional idempotency key to ensure exactly once execution of the request. Maximum length is 255 characters. |
| `include_empty_balances` | query | no | Whether to include virtual currencies with a zero balance (default false). |

**Request body**

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `adjustments` | object | yes | The adjustments to the virtual currencies |
| `reference` | string | no | The reference of the transaction |

**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: `list` |
| `items` | array of VirtualCurrencyBalance | yes | Details about each object. |
| `next_page` | string | yes | URL to access the next page of the customer's balances. 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: `virtual_currency_balance` |
| `currency_code` | string | yes | The code of the virtual currency. |
| `balance` | integer | yes | The balance of the virtual currency. |
| `description` | string | no | The description of the virtual currency. |
| `name` | string | no | The name of the virtual currency. |

</details>
### Update a virtual currencies balance without creating a transaction

`POST /projects/{project_id}/customers/{customer_id}/virtual_currencies/update_balance`

Operation ID: `update-virtual-currencies-balance`

This endpoint requires the following permission(s): <code>customer_information:purchases:read_write</code>. This endpoint belongs to the <strong>Virtual Currencies</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 |
| `customer_id` | path | yes | ID of the customer |
| `Idempotency-Key` | header | no | This is an optional idempotency key to ensure exactly once execution of the request. Maximum length is 255 characters. |
| `include_empty_balances` | query | no | Whether to include virtual currencies with a zero balance (default false). |

**Request body**

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `adjustments` | object | yes | The adjustments to the virtual currencies |
| `reference` | string | no | The reference of the transaction |

**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: `list` |
| `items` | array of VirtualCurrencyBalance | yes | Details about each object. |
| `next_page` | string | yes | URL to access the next page of the customer's balances. 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: `virtual_currency_balance` |
| `currency_code` | string | yes | The code of the virtual currency. |
| `balance` | integer | yes | The balance of the virtual currency. |
| `description` | string | no | The description of the virtual currency. |
| `name` | string | no | The name of the virtual currency. |

</details>