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

# Paywall

## Paywall

Operations about paywalls.

### Get a list of paywalls

`GET /projects/{project_id}/paywalls`

Operation ID: `list-paywalls`

This endpoint requires the following permission(s): <code>project_configuration:offerings: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. |
| `expand` | query | no | Specifies which fields in the response should be expanded. Accepted values are: `items.offering` (requires `project_configuration:offerings: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 Paywall | yes | Details about each object. |
| `next_page` | string | yes | URL to access the next page of the project's paywalls. 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: `paywall` |
| `id` | string | yes | The id of the paywall |
| `name` | string | yes | The name of the paywall |
| `offering_id` | string | yes | The ID of the offering the paywall is for. |
| `created_at` | integer | yes | The date the paywall was created at in ms since epoch |
| `published_at` | integer | yes | The date the paywall was published at in ms since epoch |
| `automatically_scale_font_size` | boolean | yes | Whether font sizes should automatically scale for this paywall. |
| `offering` | Offering | no |  |
| `components` | PaywallComponents | no |  |

<details><summary><code>offering</code></summary>

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

</details>

<details><summary><code>components</code></summary>

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `published` | PaywallComponentsVersion | yes | A specific version (published or draft) of a paywall's components configuration. |
| `draft` | PaywallComponentsVersion | yes | A specific version (published or draft) of a paywall's components configuration. |

</details>
</details>
### Create a paywall

`POST /projects/{project_id}/paywalls`

Operation ID: `create-paywall`

Create a paywall draft for a project. You can either use the offering template shortcut or provide full draft components directly.
 This endpoint requires the following permission(s): <code>project_configuration:offerings: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 |
| --- | --- | --- | --- |
| `offering_id` | string | yes | The ID of the offering the paywall will be created for. |
| `automatically_scale_font_size` | boolean | no | Whether font sizes should automatically scale for this paywall. Defaults to true. |

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `offering_id` | string | no | The optional ID of the offering the paywall draft will be attached to. |
| `name` | string | no | Optional paywall name. |
| `components_config` | object | yes | The raw paywall components configuration to save as the draft. |
| `components_localizations` | object | yes | Localized component values keyed by locale. |
| `default_locale` | string | no | The default locale for this paywall. Defaults to en_US. |
| `automatically_scale_font_size` | boolean | no | Whether font sizes should automatically scale for this paywall. Defaults to true. |

**Responses**

- `201` — Success. The paywall 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 |
| --- | --- | --- | --- |
| `object` | string | yes | String representing the object's type. Objects of the same type share the same value. One of: `paywall` |
| `id` | string | yes | The id of the paywall |
| `name` | string | yes | The name of the paywall |
| `offering_id` | string | yes | The ID of the offering the paywall is for. |
| `created_at` | integer | yes | The date the paywall was created at in ms since epoch |
| `published_at` | integer | yes | The date the paywall was published at in ms since epoch |
| `automatically_scale_font_size` | boolean | yes | Whether font sizes should automatically scale for this paywall. |
| `offering` | Offering | no |  |
| `components` | PaywallComponents | no |  |

<details><summary><code>offering</code></summary>

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

<details><summary><code>packages</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 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. |

</details>
</details>

<details><summary><code>components</code></summary>

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `published` | PaywallComponentsVersion | yes | A specific version (published or draft) of a paywall's components configuration. |
| `draft` | PaywallComponentsVersion | yes | A specific version (published or draft) of a paywall's components configuration. |

<details><summary><code>published</code></summary>

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `revision` | integer | yes | The revision number of this version. |
| `components_config` | object | yes | The raw, schemaless JSON payload for paywall components configuration. |
| `default_locale` | string | yes | The default locale for the paywall. |
| `components_localizations` | object | yes | Localized values keyed by locale code. |
| `automatically_scale_font_size` | boolean | yes | Whether font sizes should automatically scale for this paywall. |
| `fonts` | object | no | Font objects used by the published paywall components. Only present on published versions. |

</details>

<details><summary><code>draft</code></summary>

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `revision` | integer | yes | The revision number of this version. |
| `components_config` | object | yes | The raw, schemaless JSON payload for paywall components configuration. |
| `default_locale` | string | yes | The default locale for the paywall. |
| `components_localizations` | object | yes | Localized values keyed by locale code. |
| `automatically_scale_font_size` | boolean | yes | Whether font sizes should automatically scale for this paywall. |
| `fonts` | object | no | Font objects used by the published paywall components. Only present on published versions. |

</details>
</details>
### Get a paywall

`GET /projects/{project_id}/paywalls/{paywall_id}`

Operation ID: `get-paywall`

This endpoint requires the following permission(s): <code>project_configuration:offerings: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 |
| `paywall_id` | path | yes | ID of the paywall |
| `expand` | query | no | Specifies which fields in the response should be expanded. Accepted values are: `offering` (requires `project_configuration:offerings:read` permission), `components` (requires `project_configuration:offerings: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: `paywall` |
| `id` | string | yes | The id of the paywall |
| `name` | string | yes | The name of the paywall |
| `offering_id` | string | yes | The ID of the offering the paywall is for. |
| `created_at` | integer | yes | The date the paywall was created at in ms since epoch |
| `published_at` | integer | yes | The date the paywall was published at in ms since epoch |
| `automatically_scale_font_size` | boolean | yes | Whether font sizes should automatically scale for this paywall. |
| `offering` | Offering | no |  |
| `components` | PaywallComponents | no |  |

<details><summary><code>offering</code></summary>

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

<details><summary><code>packages</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 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. |

</details>
</details>

<details><summary><code>components</code></summary>

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `published` | PaywallComponentsVersion | yes | A specific version (published or draft) of a paywall's components configuration. |
| `draft` | PaywallComponentsVersion | yes | A specific version (published or draft) of a paywall's components configuration. |

<details><summary><code>published</code></summary>

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `revision` | integer | yes | The revision number of this version. |
| `components_config` | object | yes | The raw, schemaless JSON payload for paywall components configuration. |
| `default_locale` | string | yes | The default locale for the paywall. |
| `components_localizations` | object | yes | Localized values keyed by locale code. |
| `automatically_scale_font_size` | boolean | yes | Whether font sizes should automatically scale for this paywall. |
| `fonts` | object | no | Font objects used by the published paywall components. Only present on published versions. |

</details>

<details><summary><code>draft</code></summary>

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `revision` | integer | yes | The revision number of this version. |
| `components_config` | object | yes | The raw, schemaless JSON payload for paywall components configuration. |
| `default_locale` | string | yes | The default locale for the paywall. |
| `components_localizations` | object | yes | Localized values keyed by locale code. |
| `automatically_scale_font_size` | boolean | yes | Whether font sizes should automatically scale for this paywall. |
| `fonts` | object | no | Font objects used by the published paywall components. Only present on published versions. |

</details>
</details>
### Update a paywall

`PATCH /projects/{project_id}/paywalls/{paywall_id}`

Operation ID: `update-paywall`

Update a paywall draft. If the paywall is already published, this updates its draft version without changing the published version.
 This endpoint requires the following permission(s): <code>project_configuration:offerings: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 |
| `paywall_id` | path | yes | ID of the paywall |

**Request body**

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `revision` | integer | yes | The current draft revision. Used to reject stale writes. |
| `components_config` | object | no | The raw paywall components configuration to save as the draft. Omit to leave unchanged. |
| `components_localizations` | object | no | Localized component values keyed by locale. Omit to leave unchanged. |
| `default_locale` | string | no | The default locale for this paywall. Omit to leave unchanged. |
| `offering_id` | string | no | The ID of the offering to attach this paywall to. Pass null to detach the paywall from its offering (not supported while the paywall is published). Omit the field to leave it unchanged. |
| `name` | string | no | Optional paywall name. |
| `automatically_scale_font_size` | boolean | no | Whether font sizes should automatically scale for this paywall draft. |
| `exit_offers` | object | no | Exit offer configuration to save on the draft. |
| `state_declarations` | object | no | State declarations to save on the draft. |
| `play_store_product_change_mode` | object | no | Play Store product change mode configuration to save on the draft. |

**Responses**

- `200` — Success. The paywall draft 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 |
| --- | --- | --- | --- |
| `object` | string | yes | String representing the object's type. Objects of the same type share the same value. One of: `paywall` |
| `id` | string | yes | The id of the paywall |
| `name` | string | yes | The name of the paywall |
| `offering_id` | string | yes | The ID of the offering the paywall is for. |
| `created_at` | integer | yes | The date the paywall was created at in ms since epoch |
| `published_at` | integer | yes | The date the paywall was published at in ms since epoch |
| `automatically_scale_font_size` | boolean | yes | Whether font sizes should automatically scale for this paywall. |
| `offering` | Offering | no |  |
| `components` | PaywallComponents | no |  |

<details><summary><code>offering</code></summary>

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

<details><summary><code>packages</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 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. |

</details>
</details>

<details><summary><code>components</code></summary>

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `published` | PaywallComponentsVersion | yes | A specific version (published or draft) of a paywall's components configuration. |
| `draft` | PaywallComponentsVersion | yes | A specific version (published or draft) of a paywall's components configuration. |

<details><summary><code>published</code></summary>

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `revision` | integer | yes | The revision number of this version. |
| `components_config` | object | yes | The raw, schemaless JSON payload for paywall components configuration. |
| `default_locale` | string | yes | The default locale for the paywall. |
| `components_localizations` | object | yes | Localized values keyed by locale code. |
| `automatically_scale_font_size` | boolean | yes | Whether font sizes should automatically scale for this paywall. |
| `fonts` | object | no | Font objects used by the published paywall components. Only present on published versions. |

</details>

<details><summary><code>draft</code></summary>

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `revision` | integer | yes | The revision number of this version. |
| `components_config` | object | yes | The raw, schemaless JSON payload for paywall components configuration. |
| `default_locale` | string | yes | The default locale for the paywall. |
| `components_localizations` | object | yes | Localized values keyed by locale code. |
| `automatically_scale_font_size` | boolean | yes | Whether font sizes should automatically scale for this paywall. |
| `fonts` | object | no | Font objects used by the published paywall components. Only present on published versions. |

</details>
</details>
### Delete a paywall

`DELETE /projects/{project_id}/paywalls/{paywall_id}`

Operation ID: `delete-paywall`

This endpoint requires the following permission(s): <code>project_configuration:offerings: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 |
| `paywall_id` | path | yes | ID of the paywall |

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