RevenueCat provides a REST API for developers to perform customer and transaction related actions from their own server.

Most of this API is geared toward client usage via RevenueCat’s SDK, but there are various endpoints that can be used for refunding purchases, granting promotional entitlements, and other sensitive actions that can only be done via a Secret API key from your server.

If you’re adding subscriptions or other in-app purchases to your app for the first time or if you don’t have a backend that stores your user’s receipts, you’re probably looking to implement the RevenueCat SDK.

If you want to start migrating your existing users to RevenueCat and you have your user’s receipts stored on your own server, or you want to check subscription status of your users from your own server, the REST API is a great solution.

Authentication for the RevenueCat REST API is achieved by setting the Authorization header with a valid API key. You'll find two types of API keys in your RevenueCat dashboard: public and secret.

Certain endpoints require secret keys, which should be kept out of any publicly accessible areas such as GitHub, client-side code, and so forth. See our Authentication guide for more information.

Authorization: Bearer YOUR_REVENUECAT_API_KEY

You can create a new secret API key in your project settings page > API keys. Select + New.

Give it a name, select V2 as the version, and set your permissions. Be sure to select Generate at the top right corner.

Each endpoint in this documentation will contain a description informing you which permissions are required.

The body of the POST requests should be encoded in JSON and have the 'Content-Type' header set to 'application/json'.

Content-Type: application/json

{
  "app_user_id": "user-1456",
  "fetch_token": "MQABC...EFH1234="
}

Top-level API resources have support for bulk fetches via "list" API methods. For instance, you can list products, list entitlements, and list offerings. These list API methods share a common structure, taking at least these two parameters: limit and starting_after.

When a response or a field contains multiple entities of the same type, it returns a list object of the following structure:

{
  "object": "list",
  "items": [{}],
  "next_page": "LIST_BASE_URL?starting_after=LAST_ID",
  "url": "LIST_BASE_URL"
}

Where…

• url is the full path base URL of the list endpoint (i.e., if you make a request to this endpoint, you will get the first page), e.g. /v2/projects/{project_id}/products
• next_page is the URL for the next page, if there is one. If there is no next page, the next_page field will not be present. Example: /v2/projects/{project_id}/products?starting_after={last_id}
• items is an array of the entries of the list.

The starting_after query parameter of list endpoints accepts the ID of the first list item that will not be part of the list (in other words, the ID of the last item of the previous page).

At the moment we only support forward pagination.

limit optional, default is 20

A limit on the number of objects to be returned.

starting_after optional

A cursor for use in pagination. starting_after is an object ID that defines your place in the list. For instance, if you make a list request and receive 20 objects, ending with foo, your subsequent call can include starting_after=foo in order to fetch the next page of the list.

We will return the following headers on all successful requests:

• RevenueCat-Rate-Limit-Current-Usage: the number of executed requests for the current rate limiting period, including the current request. The rate limiting period is one minute.
• RevenueCat-Rate-Limit-Current-Limit: the limit in requests per minute for this endpoint

If you reach the rate limit, as indicated by a 429 error code, we will also include the following header:

• Retry-After: the number of seconds to wait until you can retry this request.

Below is an example of the response body that will be sent when the rate limit is reached. The value of the backoff_ms field corresponds to the `Retry-After`` header but specified in milliseconds.

{
  "type": "rate_limit_error",
  "message": "Rate limit exceeded",
  "retryable": true,
  "doc_url": "https://errors.rev.cat/rate-limit-error",
  "backoff_ms": 1000
}

Expandables allow you to retrieve related data along with the request without making additional requests. Fields in the REST API will allow you to request additional information as an expanded response by using the expand query parameter.

For example, a product object will have an associated app_id field. This app_id field can be expanded in the same request with the expand query parameter and will include an app object in the response.

Without expand query param

{
  "object": "product",
  "id": "prod1a2b3c4d5e",
  "store_identifier": "rc_1w_199",
  "type": "subscription",
  "subscription": {
    "duration": "P1M",
    "grace_period_duration": "P3D",
    "trial_duration": "P1W"
  },
  "created_at": 1658399423658,
  "app_id": "app1a2b3c4"
}

With expand query param:

{
  "object": "product",
  "id": "prod1a2b3c4d5e",
  "store_identifier": "rc_1w_199",
  "type": "subscription",
  "subscription": {
    "duration": "P1M",
    "grace_period_duration": "P3D",
    "trial_duration": "P1W"
  },
  "created_at": 1658399423658,
  "app_id": "app1a2b3c4",
  "app": {
    "id": "app1a2b3c4",
    "name": "string",
    "created_at": 1658399423658,
    "type": "amazon",
    "project_id": "proj1a2b3c4"
  }
}

As you can see from above, the app_id field remains the same, but the response contains an additional app object.

Fields that can be expanded into objects are indicated in the endpoint documentation under Query Params and will list accepted values. Also, the required permissions to be defined in the API key are listed there.

RevenueCat uses standard HTTP status codes to indicate the success or failure of an API request. Codes in the 2XX range indicate the request was successful. 4XX codes indicate an error caused by the client. 5XX codes indicate an error in RevenueCat servers.

Successful modifications return the modified entity. Errors return the following fields:

{
  "type": "parameter_error",
  "param": "customer_id",
  "message": "id is too long",
  "retryable": false,
  "doc_url": "https://errors.rev.cat/parameter-error"
}

For more information on the type field and how to resolve these errors, please visit our Error Types documentation.

authentication_error

Authentication is not valid for the given API key. Double check your API key.

authorization_error

The API key does not belong the project you specified. Double check that your API key is associated with the IDs you are passing.

invalid_request

This error can be due to several reasons:

• Content-Type: application/json is missing in the request header for POST/PUT/PATCH requests
• Using the incorrect HTTP method on a path (i.e: GET …/entitlements/<entitlements_id>/actions/attach_products)

parameter_error

The parameter provided is invalid. Please refer to the message field for more information.

• IDs (e.g: entitlement_id, project_id, etc): 1 to 255 characters
• display_name(applies to Entitlements): 1 to 1000 characters
• lookup_key(applies to Entitlements): 1 to 200 characters

rate_limit_error

The request has hit the rate limit for this endpoint. Refer to the backoff_ms field to determine how many milliseconds to wait before making another request to the same endpoint.

resource_missing

The resource with the specific ID does not exist. Double check the IDs (e.g: product ID, entitlement ID, etc) you are passing into the endpoints.

resource_already_exists

The resource with the specific ID already exists. Use a different, unique value for ID and try again.

resource_locked_error

The resource is currently being modified by a concurrent request. Refer to the backoff_ms field to determine when to try again.

server_error

Request is not able to be processed due to an internal server error. Refer to the backoff_ms field to determine when to try again. Please report this to the RevenueCat team if you are encountering this issue.

store_error

There was a problem with the stores (e.g: Apple App Store, Google Play Store, etc). This typically occurs when the stores are unable to process the request. Refer to the backoff_ms field to determine when to try again.

unprocessable_entity_error

Request is not able to be processed. Please refer to the message field for more information.

Operations about apps.

Operations about chart metrics.

Operations about customers.

Operations about entitlements.