---
title: "Offering"
permalink: "/docs/api-v2/offering"
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).
# Offering
## Offering
Operations about offerings.
### Get an offering
`GET /projects/{project_id}/offerings/{offering_id}`
Operation ID: `get-offering`
This endpoint requires the following permission(s): project_configuration:offerings:read. This endpoint belongs to the Project Configuration domain, which has a default rate limit of 60 requests per minute.
**Parameters**
| Name | In | Required | Description |
| --- | --- | --- | --- |
| `project_id` | path | yes | ID of the project |
| `offering_id` | path | yes | ID of the offering |
| `expand` | query | no | Specifies which fields in the response should be expanded. Accepted values are: `package` (requires `project_configuration:packages:read` permission), `package.product` (requires `project_configuration:products: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 |
| --- | --- | --- | --- |
| `state` | string | yes | Whether the offering is active or inactive (archived). Inactive offerings are not returned by the SDK. One of: `active`, `inactive` |
| `object` | string | yes | String representing the object's type. Objects of the same type share the same value. One of: `offering` |
| `id` | string | yes | The id of the offering |
| `lookup_key` | string | yes | A custom identifier of the entitlement |
| `display_name` | string | yes | The display name of the offering |
| `is_current` | boolean | yes | Indicates if the offering is the current offering |
| `created_at` | integer | yes | The date the offering was created at in ms since epoch |
| `project_id` | string | yes | ID of the project to which the offering belongs |
| `paywall_id` | string | yes | ID of the v2-visible paywall attached to this offering, or null if none. |
| `metadata` | OfferingMetadata | no | Custom metadata of the offering |
| `packages` | object | no | |
packages
| 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 Package | yes | Details about each object. |
| `next_page` | string | yes | URL to access the next page of the Offering's packages. If not present / null, there is no next page |
| `url` | string | yes | The URL where this list can be accessed. |
items
| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `object` | string | yes | String representing the object's type. Objects of the same type share the same value. One of: `package` |
| `id` | string | yes | The id of the package |
| `lookup_key` | string | yes | The lookup_key of the package |
| `display_name` | string | yes | The display name of the package |
| `position` | integer | yes | The position of the package within the offering |
| `created_at` | integer | yes | The date the package was created at in ms since epoch |
| `products` | object | no | |
project_configuration:offerings:read_write. This endpoint belongs to the Project Configuration domain, which has a default rate limit of 60 requests per minute.
**Parameters**
| Name | In | Required | Description |
| --- | --- | --- | --- |
| `project_id` | path | yes | ID of the project |
| `offering_id` | path | yes | ID of the offering |
**Request body**
| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `display_name` | string | no | The display name of the offering |
| `is_current` | boolean | no | Indicates if the offering is the current offering |
| `metadata` | OfferingMetadata | no | Custom metadata of the offering |
**Responses**
- `200` — Success. The offering 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 offering is active or inactive (archived). Inactive offerings are not returned by the SDK. One of: `active`, `inactive` |
| `object` | string | yes | String representing the object's type. Objects of the same type share the same value. One of: `offering` |
| `id` | string | yes | The id of the offering |
| `lookup_key` | string | yes | A custom identifier of the entitlement |
| `display_name` | string | yes | The display name of the offering |
| `is_current` | boolean | yes | Indicates if the offering is the current offering |
| `created_at` | integer | yes | The date the offering was created at in ms since epoch |
| `project_id` | string | yes | ID of the project to which the offering belongs |
| `paywall_id` | string | yes | ID of the v2-visible paywall attached to this offering, or null if none. |
| `metadata` | OfferingMetadata | no | Custom metadata of the offering |
| `packages` | object | no | |
packages
| 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 Package | yes | Details about each object. |
| `next_page` | string | yes | URL to access the next page of the Offering's packages. If not present / null, there is no next page |
| `url` | string | yes | The URL where this list can be accessed. |
items
| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `object` | string | yes | String representing the object's type. Objects of the same type share the same value. One of: `package` |
| `id` | string | yes | The id of the package |
| `lookup_key` | string | yes | The lookup_key of the package |
| `display_name` | string | yes | The display name of the package |
| `position` | integer | yes | The position of the package within the offering |
| `created_at` | integer | yes | The date the package was created at in ms since epoch |
| `products` | object | no | |
project_configuration:offerings:read_write. This endpoint belongs to the Project Configuration domain, which has a default rate limit of 60 requests per minute.
**Parameters**
| Name | In | Required | Description |
| --- | --- | --- | --- |
| `project_id` | path | yes | ID of the project |
| `offering_id` | path | yes | ID of the offering |
**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 | 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 an offering
`POST /projects/{project_id}/offerings/{offering_id}/actions/archive`
Operation ID: `archive-offering`
Archives an offering (makes it inactive).
This endpoint requires the following permission(s): project_configuration:offerings:read_write. This endpoint belongs to the Project Configuration domain, which has a default rate limit of 60 requests per minute.
**Parameters**
| Name | In | Required | Description |
| --- | --- | --- | --- |
| `project_id` | path | yes | ID of the project |
| `offering_id` | path | yes | ID of the offering |
**Responses**
- `200` — Success. The offering 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 offering is active or inactive (archived). Inactive offerings are not returned by the SDK. One of: `active`, `inactive` |
| `object` | string | yes | String representing the object's type. Objects of the same type share the same value. One of: `offering` |
| `id` | string | yes | The id of the offering |
| `lookup_key` | string | yes | A custom identifier of the entitlement |
| `display_name` | string | yes | The display name of the offering |
| `is_current` | boolean | yes | Indicates if the offering is the current offering |
| `created_at` | integer | yes | The date the offering was created at in ms since epoch |
| `project_id` | string | yes | ID of the project to which the offering belongs |
| `paywall_id` | string | yes | ID of the v2-visible paywall attached to this offering, or null if none. |
| `metadata` | OfferingMetadata | no | Custom metadata of the offering |
| `packages` | object | no | |
packages
| 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 Package | yes | Details about each object. |
| `next_page` | string | yes | URL to access the next page of the Offering's packages. If not present / null, there is no next page |
| `url` | string | yes | The URL where this list can be accessed. |
items
| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `object` | string | yes | String representing the object's type. Objects of the same type share the same value. One of: `package` |
| `id` | string | yes | The id of the package |
| `lookup_key` | string | yes | The lookup_key of the package |
| `display_name` | string | yes | The display name of the package |
| `position` | integer | yes | The position of the package within the offering |
| `created_at` | integer | yes | The date the package was created at in ms since epoch |
| `products` | object | no | |
project_configuration:offerings:read_write. This endpoint belongs to the Project Configuration domain, which has a default rate limit of 60 requests per minute.
**Parameters**
| Name | In | Required | Description |
| --- | --- | --- | --- |
| `project_id` | path | yes | ID of the project |
| `offering_id` | path | yes | ID of the offering |
**Request body**
| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `unarchive_referenced_entities` | boolean | no | If true, also unarchive any archived products referenced by this offering's packages. |
**Responses**
- `200` — Success. The offering 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 offering is active or inactive (archived). Inactive offerings are not returned by the SDK. One of: `active`, `inactive` |
| `object` | string | yes | String representing the object's type. Objects of the same type share the same value. One of: `offering` |
| `id` | string | yes | The id of the offering |
| `lookup_key` | string | yes | A custom identifier of the entitlement |
| `display_name` | string | yes | The display name of the offering |
| `is_current` | boolean | yes | Indicates if the offering is the current offering |
| `created_at` | integer | yes | The date the offering was created at in ms since epoch |
| `project_id` | string | yes | ID of the project to which the offering belongs |
| `paywall_id` | string | yes | ID of the v2-visible paywall attached to this offering, or null if none. |
| `metadata` | OfferingMetadata | no | Custom metadata of the offering |
| `packages` | object | no | |
packages
| 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 Package | yes | Details about each object. |
| `next_page` | string | yes | URL to access the next page of the Offering's packages. If not present / null, there is no next page |
| `url` | string | yes | The URL where this list can be accessed. |
items
| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `object` | string | yes | String representing the object's type. Objects of the same type share the same value. One of: `package` |
| `id` | string | yes | The id of the package |
| `lookup_key` | string | yes | The lookup_key of the package |
| `display_name` | string | yes | The display name of the package |
| `position` | integer | yes | The position of the package within the offering |
| `created_at` | integer | yes | The date the package was created at in ms since epoch |
| `products` | object | no | |
project_configuration:offerings:read. This endpoint belongs to the Project Configuration domain, which has a default rate limit of 60 requests per minute.
**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. |
| `expand` | query | no | Specifies which fields in the response should be expanded. Accepted values are: `items.package` (requires `project_configuration:packages:read` permission), `items.package.product` (requires `project_configuration:products: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 Offering | yes | Details about each object. |
| `next_page` | string | yes | URL to access the next page of the project's offerings. If not present / null, there is no next page |
| `url` | string | yes | The URL where this list can be accessed. |
items
| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `state` | string | yes | Whether the offering is active or inactive (archived). Inactive offerings are not returned by the SDK. One of: `active`, `inactive` |
| `object` | string | yes | String representing the object's type. Objects of the same type share the same value. One of: `offering` |
| `id` | string | yes | The id of the offering |
| `lookup_key` | string | yes | A custom identifier of the entitlement |
| `display_name` | string | yes | The display name of the offering |
| `is_current` | boolean | yes | Indicates if the offering is the current offering |
| `created_at` | integer | yes | The date the offering was created at in ms since epoch |
| `project_id` | string | yes | ID of the project to which the offering belongs |
| `paywall_id` | string | yes | ID of the v2-visible paywall attached to this offering, or null if none. |
| `metadata` | OfferingMetadata | no | Custom metadata of the offering |
| `packages` | object | no | |
packages
| 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 Package | yes | Details about each object. |
| `next_page` | string | yes | URL to access the next page of the Offering's packages. If not present / null, there is no next page |
| `url` | string | yes | The URL where this list can be accessed. |
project_configuration:offerings:read_write. This endpoint belongs to the Project Configuration domain, which has a default rate limit of 60 requests per minute.
**Parameters**
| Name | In | Required | Description |
| --- | --- | --- | --- |
| `project_id` | path | yes | ID of the project |
**Request body**
| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `lookup_key` | string | yes | The custom identifier of the offering |
| `display_name` | string | yes | The display_name of the offering |
| `metadata` | OfferingMetadata | no | Custom metadata of the offering |
**Responses**
- `201` — Success. The offering 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 offering is active or inactive (archived). Inactive offerings are not returned by the SDK. One of: `active`, `inactive` |
| `object` | string | yes | String representing the object's type. Objects of the same type share the same value. One of: `offering` |
| `id` | string | yes | The id of the offering |
| `lookup_key` | string | yes | A custom identifier of the entitlement |
| `display_name` | string | yes | The display name of the offering |
| `is_current` | boolean | yes | Indicates if the offering is the current offering |
| `created_at` | integer | yes | The date the offering was created at in ms since epoch |
| `project_id` | string | yes | ID of the project to which the offering belongs |
| `paywall_id` | string | yes | ID of the v2-visible paywall attached to this offering, or null if none. |
| `metadata` | OfferingMetadata | no | Custom metadata of the offering |
| `packages` | object | no | |
packages
| 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 Package | yes | Details about each object. |
| `next_page` | string | yes | URL to access the next page of the Offering's packages. If not present / null, there is no next page |
| `url` | string | yes | The URL where this list can be accessed. |
items
| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `object` | string | yes | String representing the object's type. Objects of the same type share the same value. One of: `package` |
| `id` | string | yes | The id of the package |
| `lookup_key` | string | yes | The lookup_key of the package |
| `display_name` | string | yes | The display name of the package |
| `position` | integer | yes | The position of the package within the offering |
| `created_at` | integer | yes | The date the package was created at in ms since epoch |
| `products` | object | no | |