---
title: "Virtual Currency"
permalink: "/docs/api-v2/virtual-currency"
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).

# Virtual Currency

## Virtual Currency

Operations about virtual currencies.

### Get a list of virtual currencies

`GET /projects/{project_id}/virtual_currencies`

Operation ID: `list-virtual-currencies`

This endpoint requires the following permission(s): <code>project_configuration:virtual_currencies:read</code>. This endpoint belongs to the <strong>Project Configuration</strong> domain, which has a default rate limit of <strong>60 requests per minute</strong>.

**Parameters**

| Name | In | Required | Description |
| --- | --- | --- | --- |
| `project_id` | path | yes | ID of the project |
| `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 VirtualCurrency | yes | Details about each object. |
| `next_page` | string | yes | URL to access the next page of the project's virtual currencies. 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 virtual currency 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: `virtual_currency` |
| `project_id` | string | yes | ID of the project to which the virtual currency belongs |
| `code` | string | yes | The unique code for this virtual currency |
| `name` | string | yes | The display name of the virtual currency |
| `created_at` | integer | yes | The date the virtual currency was created at in ms since epoch |
| `description` | string | no | Description of the virtual currency |
| `product_grants` | array of VirtualCurrencyProductGrant | no | The grants that define how products grant this virtual currency |

<details><summary><code>product_grants</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.product_grant` |
| `product_ids` | array of string | yes | The list of product IDs that grant this virtual currency |
| `amount` | integer | yes | The amount of virtual currency granted |
| `trial_amount` | integer | yes | The amount of virtual currency granted during trial period |
| `expire_at_cycle_end` | boolean | yes | Whether the grant expires at the end of the subscription cycle |

</details>
</details>
### Create a virtual currency

`POST /projects/{project_id}/virtual_currencies`

Operation ID: `create-virtual-currency`

This endpoint requires the following permission(s): <code>project_configuration:virtual_currencies:read_write</code>. This endpoint belongs to the <strong>Project Configuration</strong> domain, which has a default rate limit of <strong>60 requests per minute</strong>.

**Parameters**

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

**Request body**

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `code` | string | yes | The unique code for this virtual currency |
| `name` | string | yes | The display name of the virtual currency |
| `description` | string | no | Description of the virtual currency |
| `product_grants` | array of VirtualCurrencyProductGrantInput | no | Product grants that define how products grant this virtual currency |

<details><summary><code>product_grants</code></summary>

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `product_ids` | array of string | yes | The list of product IDs that grant this virtual currency |
| `amount` | integer | yes | The amount of virtual currency granted |
| `trial_amount` | integer | no | The amount of virtual currency granted during trial period |
| `expire_at_cycle_end` | boolean | no | Whether the grant expires at the end of the subscription cycle |

</details>
**Responses**

- `201` — Success. The virtual currency was created
- `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 `201` body**

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `state` | string | yes | Whether the virtual currency 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: `virtual_currency` |
| `project_id` | string | yes | ID of the project to which the virtual currency belongs |
| `code` | string | yes | The unique code for this virtual currency |
| `name` | string | yes | The display name of the virtual currency |
| `created_at` | integer | yes | The date the virtual currency was created at in ms since epoch |
| `description` | string | no | Description of the virtual currency |
| `product_grants` | array of VirtualCurrencyProductGrant | no | The grants that define how products grant this virtual currency |

<details><summary><code>product_grants</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.product_grant` |
| `product_ids` | array of string | yes | The list of product IDs that grant this virtual currency |
| `amount` | integer | yes | The amount of virtual currency granted |
| `trial_amount` | integer | yes | The amount of virtual currency granted during trial period |
| `expire_at_cycle_end` | boolean | yes | Whether the grant expires at the end of the subscription cycle |

</details>
### Get a virtual currency

`GET /projects/{project_id}/virtual_currencies/{virtual_currency_code}`

Operation ID: `get-virtual-currency`

This endpoint requires the following permission(s): <code>project_configuration:virtual_currencies:read</code>. This endpoint belongs to the <strong>Project Configuration</strong> domain, which has a default rate limit of <strong>60 requests per minute</strong>.

**Parameters**

| Name | In | Required | Description |
| --- | --- | --- | --- |
| `project_id` | path | yes | ID of the project |
| `virtual_currency_code` | path | yes | The virtual currency code |

**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 |
| --- | --- | --- | --- |
| `state` | string | yes | Whether the virtual currency 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: `virtual_currency` |
| `project_id` | string | yes | ID of the project to which the virtual currency belongs |
| `code` | string | yes | The unique code for this virtual currency |
| `name` | string | yes | The display name of the virtual currency |
| `created_at` | integer | yes | The date the virtual currency was created at in ms since epoch |
| `description` | string | no | Description of the virtual currency |
| `product_grants` | array of VirtualCurrencyProductGrant | no | The grants that define how products grant this virtual currency |

<details><summary><code>product_grants</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.product_grant` |
| `product_ids` | array of string | yes | The list of product IDs that grant this virtual currency |
| `amount` | integer | yes | The amount of virtual currency granted |
| `trial_amount` | integer | yes | The amount of virtual currency granted during trial period |
| `expire_at_cycle_end` | boolean | yes | Whether the grant expires at the end of the subscription cycle |

</details>
### Update a virtual currency

`POST /projects/{project_id}/virtual_currencies/{virtual_currency_code}`

Operation ID: `update-virtual-currency`

This endpoint requires the following permission(s): <code>project_configuration:virtual_currencies:read_write</code>. This endpoint belongs to the <strong>Project Configuration</strong> domain, which has a default rate limit of <strong>60 requests per minute</strong>.

**Parameters**

| Name | In | Required | Description |
| --- | --- | --- | --- |
| `project_id` | path | yes | ID of the project |
| `virtual_currency_code` | path | yes | The virtual currency code |

**Request body**

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string | no | The display name of the virtual currency |
| `description` | string | no | Description of the virtual currency |
| `product_grants` | array of VirtualCurrencyProductGrantInput | no | Product grants that define how products grant this virtual currency |

<details><summary><code>product_grants</code></summary>

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `product_ids` | array of string | yes | The list of product IDs that grant this virtual currency |
| `amount` | integer | yes | The amount of virtual currency granted |
| `trial_amount` | integer | no | The amount of virtual currency granted during trial period |
| `expire_at_cycle_end` | boolean | no | Whether the grant expires at the end of the subscription cycle |

</details>
**Responses**

- `200` — Success. The virtual currency was updated
- `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 |
| --- | --- | --- | --- |
| `state` | string | yes | Whether the virtual currency 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: `virtual_currency` |
| `project_id` | string | yes | ID of the project to which the virtual currency belongs |
| `code` | string | yes | The unique code for this virtual currency |
| `name` | string | yes | The display name of the virtual currency |
| `created_at` | integer | yes | The date the virtual currency was created at in ms since epoch |
| `description` | string | no | Description of the virtual currency |
| `product_grants` | array of VirtualCurrencyProductGrant | no | The grants that define how products grant this virtual currency |

<details><summary><code>product_grants</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.product_grant` |
| `product_ids` | array of string | yes | The list of product IDs that grant this virtual currency |
| `amount` | integer | yes | The amount of virtual currency granted |
| `trial_amount` | integer | yes | The amount of virtual currency granted during trial period |
| `expire_at_cycle_end` | boolean | yes | Whether the grant expires at the end of the subscription cycle |

</details>
### Delete a virtual currency

`DELETE /projects/{project_id}/virtual_currencies/{virtual_currency_code}`

Operation ID: `delete-virtual-currency`

This endpoint requires the following permission(s): <code>project_configuration:virtual_currencies:read_write</code>. This endpoint belongs to the <strong>Project Configuration</strong> domain, which has a default rate limit of <strong>60 requests per minute</strong>.

**Parameters**

| Name | In | Required | Description |
| --- | --- | --- | --- |
| `project_id` | path | yes | ID of the project |
| `virtual_currency_code` | path | yes | The virtual currency code |

**Responses**

- `200` — Success. The virtual currency was deleted
- `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 | The type of the deleted object One of: `app`, `chart_annotation`, `customer`, `discount`, `entitlement`, `experiment`, `offering`, `package`, `paywall`, `product`, `virtual_currency`, `webhook_integration` |
| `id` | string | yes | The ID of the deleted object |
| `deleted_at` | integer | yes | The date when the object was deleted in ms since epoch |

### Archive a virtual currency

`POST /projects/{project_id}/virtual_currencies/{virtual_currency_code}/actions/archive`

Operation ID: `archive-virtual-currency`

Archives a virtual currency (makes it inactive).
 This endpoint requires the following permission(s): <code>project_configuration:virtual_currencies:read_write</code>. This endpoint belongs to the <strong>Project Configuration</strong> domain, which has a default rate limit of <strong>60 requests per minute</strong>.

**Parameters**

| Name | In | Required | Description |
| --- | --- | --- | --- |
| `project_id` | path | yes | ID of the project |
| `virtual_currency_code` | path | yes | The virtual currency code |

**Responses**

- `200` — Success. The virtual currency was archived
- `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 |
| --- | --- | --- | --- |
| `state` | string | yes | Whether the virtual currency 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: `virtual_currency` |
| `project_id` | string | yes | ID of the project to which the virtual currency belongs |
| `code` | string | yes | The unique code for this virtual currency |
| `name` | string | yes | The display name of the virtual currency |
| `created_at` | integer | yes | The date the virtual currency was created at in ms since epoch |
| `description` | string | no | Description of the virtual currency |
| `product_grants` | array of VirtualCurrencyProductGrant | no | The grants that define how products grant this virtual currency |

<details><summary><code>product_grants</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.product_grant` |
| `product_ids` | array of string | yes | The list of product IDs that grant this virtual currency |
| `amount` | integer | yes | The amount of virtual currency granted |
| `trial_amount` | integer | yes | The amount of virtual currency granted during trial period |
| `expire_at_cycle_end` | boolean | yes | Whether the grant expires at the end of the subscription cycle |

</details>
### Unarchive a virtual currency

`POST /projects/{project_id}/virtual_currencies/{virtual_currency_code}/actions/unarchive`

Operation ID: `unarchive-virtual-currency`

Unarchives a virtual currency (makes it active).
 This endpoint requires the following permission(s): <code>project_configuration:virtual_currencies:read_write</code>. This endpoint belongs to the <strong>Project Configuration</strong> domain, which has a default rate limit of <strong>60 requests per minute</strong>.

**Parameters**

| Name | In | Required | Description |
| --- | --- | --- | --- |
| `project_id` | path | yes | ID of the project |
| `virtual_currency_code` | path | yes | The virtual currency code |

**Responses**

- `200` — Success. The virtual currency was unarchived
- `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 |
| --- | --- | --- | --- |
| `state` | string | yes | Whether the virtual currency 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: `virtual_currency` |
| `project_id` | string | yes | ID of the project to which the virtual currency belongs |
| `code` | string | yes | The unique code for this virtual currency |
| `name` | string | yes | The display name of the virtual currency |
| `created_at` | integer | yes | The date the virtual currency was created at in ms since epoch |
| `description` | string | no | Description of the virtual currency |
| `product_grants` | array of VirtualCurrencyProductGrant | no | The grants that define how products grant this virtual currency |

<details><summary><code>product_grants</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.product_grant` |
| `product_ids` | array of string | yes | The list of product IDs that grant this virtual currency |
| `amount` | integer | yes | The amount of virtual currency granted |
| `trial_amount` | integer | yes | The amount of virtual currency granted during trial period |
| `expire_at_cycle_end` | boolean | yes | Whether the grant expires at the end of the subscription cycle |

</details>