Skip to main content
API docs by Redocly

RevenueCat API v1 (1.0)

Download OpenAPI specification:Download

New to RevenueCat?
Welcome! If you're adding subscriptions or other in-app purchases to your app, the RevenueCat SDK will handle most of the heavy-lifting without the need to interact with this API directly. See our Quickstart for more information on getting started with RevenueCat.

About RevenueCat’s REST API

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.

Should I use this REST API or the RevenueCat SDK?

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 Customers' 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 Customers' 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.

Base URL

The base URL for the RevenueCat REST API is https://api.revenuecat.com/v1.

Authentication

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

Making requests

Request Payload

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="
}

URL parameters

For URL params, such as the app_user_id, make sure you URL encode them before using them.

Transactions

Operations about transactions.

Create a Purchase

Records a purchase for a Customer from iOS, Android, Stripe, Roku and Paddle will create a Customer if they don't already exist.

Authorizations:
BearerAuth
header Parameters
X-Platform
required
string
Example: ios

The platform this purchase is for. Either ios, android, amazon, macos, uikitformac, stripe, roku, or paddle

Request Body schema: application/json
app_user_id
required
string

App User ID of the Customer the receipt is associated with.

fetch_token
required
string

For iOS, the base64 encoded receipt file (or JWSTransaction for StoreKit2), for Android the receipt token, for Amazon the receipt, for Stripe the subscription ID or the Stripe Checkout Session ID, for Roku the transaction ID, and for Paddle the subscription ID or transaction ID.

product_id
string

The Apple, Google, Amazon, Roku, or Paddle product identifier or SKU. Required for Google.

price
number <float>

The price of the product. Required if you provide a currency.

currency
string
Default: "USD"

The currency of the product. The currency must be in ISO 4217 format. Required if you provide a price.

payment_mode
string

Optionally used by the iOS SDK to communicate intro pricing periods. Either pay_as_you_go = 0, pay_up_front = 1, or free_trial = 2. Defaults to 2 (free trial) if an introductory period is detected in the receipt but this value is not provided.

introductory_price
number <float>

Introductory price paid

is_restore
boolean
Deprecated
Default: false

If true, the fetch token will trigger your configured restore behavior for any other users sharing the same fetch token.

presented_offering_identifier
string

Optional. The offering that was presented to the Customer at the time of purchase. This will be attached to any new transactions in this fetch token and will be available in ETL exports and webhooks. This is mostly useful if you're sending fetch tokens from your backend.

object

Any Attributes to set on the Customer as a dictionary keyed by the Attribute name.

additional property
object

A single Attribute to be set.

value
required
string

The value of the attribute. If the value is null or an empty string, the attribute will be deleted.

updated_at_ms
integer <int64>

UNIX epoch in milliseconds of when the attribute was updated. This value is used to resolve conflicts, an attribute will only be updated if the new updated_at_ms value is newer than the value for the stored attribute.

Responses

Request samples

Content type
application/json
{
  • "app_user_id": "string",
  • "fetch_token": "string",
  • "product_id": "com.my.product.iap",
  • "price": 1.99,
  • "currency": "USD",
  • "payment_mode": "string",
  • "introductory_price": 0.1,
  • "is_restore": false,
  • "presented_offering_identifier": "string",
  • "attributes": {
    }
}

Response samples

Content type
application/json
{
  • "value": {
    }
}

Google Play: Refund and Revoke Subscription

Immediately revokes access to a Google Subscription and issues a refund for the last purchase. If you want to refund a one-time Google purchase, see refund a Google purchase.

Authorizations:
BearerAuth
path Parameters
app_user_id
required
string

The App User ID of the Customer.

product_identifier
required
string

The identifier of the product belonging to the subscription that is being revoked.

Responses

Response samples

Content type
application/json
{
  • "value": {
    }
}

Google Play: Defer a Subscription

Defers the purchase of a Google Subscription to a later date.

Authorizations:
BearerAuth
path Parameters
app_user_id
required
string

The App User ID of the Customer.

product_identifier
required
string

The identifier of the product belonging to the subscription that is being deferred. This can be found in RevenueCat's Product catalog -> {Product} -> Subscription Id.

Request Body schema: application/json
expiry_time_ms
integer <int64>

The desired next expiry time to assign to the subscription, in milliseconds since the Epoch. The given time must be later/greater than the current expiry time for the subscription. Either expiry_time_ms or extend_by_days must be provided.

extend_by_days
integer [ 1 .. 365 ]

The number of days to extend the subscription renewal date. Must be between 1 and 365. Either expiry_time_ms or extend_by_days must be provided.

Responses

Request samples

Content type
application/json
{
  • "expiry_time_ms": 1708417962662,
  • "extend_by_days": 30
}

Response samples

Content type
application/json
{
  • "value": {
    }
}

Google Play: Refund and Revoke Purchase

Issues a refund for the most recent purchase of a Google product and revokes access. Works for subscription and non-subscription purchases that occurred in the last 365 days.

Authorizations:
BearerAuth
path Parameters
app_user_id
required
string

The App User ID of the Customer.

store_transaction_identifier
required
string

The identifier of the transaction to refund. Example: GPA.3309-9122-6177-45730

Responses

Response samples

Content type
application/json
{
  • "value": {
    }
}

Google Play: Cancel a Subscription

Cancels a Google subscription.

Authorizations:
BearerAuth
path Parameters
app_user_id
required
string

The App User ID of the Customer.

store_transaction_identifier
required
string

The identifier of the transaction to cancel. Example: GPA.3309-9122-6177-45730

Responses

Response samples

Content type
application/json
{
  • "value": {
    }
}

App Store: Extend a Subscription

Extends the renewal date of an auto-renewable subscription for up to 90 days for a specific customer.

This uses Apple's Extend a Subscription Renewal Date API.

Requires a v1 Secret API key.

Note: Apple limits subscription extensions to two per year per customer. Apple immediately sends the customer an email notification of the extension.

Authorizations:
BearerAuth
path Parameters
app_user_id
required
string

The App User ID of the Customer.

store_transaction_identifier
required
string

The store transaction identifier of the subscription to extend. Can be original transaction identifier or renewal transaction identifier. Example: 1000000819074923

Request Body schema: application/json
extend_by_days
required
integer [ 1 .. 90 ]

The number of days to extend the subscription renewal date. Must be between 1 and 90.

extend_reason_code
required
integer [ 0 .. 3 ]

The reason code for the subscription extension. See Apple's extendReasonCode documentation.

  • 0: Undeclared - The renewal-date extension reason is undeclared.
  • 1: Customer Satisfaction - The renewal-date extension is for customer satisfaction.
  • 2: Other - The renewal-date extension is for a reason other than the ones listed.
  • 3: Service Issue or Outage - The renewal-date extension is due to a service issue or outage.

Responses

Request samples

Content type
application/json
{
  • "extend_by_days": 30,
  • "extend_reason_code": 1
}

Response samples

Content type
application/json
{
  • "value": {
    }
}

Customers

Operations about customers.

Get or Create Customer

Gets the latest Customer Info for the customer with the given App User ID, or creates a new customer if it doesn't exist.

Authorizations:
BearerAuth
path Parameters
app_user_id
required
string

The App User ID used with the mobile SDK.

header Parameters
X-Platform
string
Example: ios

Optionally set the X-Platform header to update the Customer's last_seen field. Set to either ios, android, amazon, macos, uikitformac. Don't set this if you are calling the getter for informational purposes or using a secret API key to fetch the customer's attributes.

Responses

Response samples

Content type
application/json
{
  • "request_date": "2019-07-26T17:40:10Z",
  • "request_date_ms": 1564162810884,
  • "subscriber": {
    }
}

Delete Customer

Permanently deletes a customer.

Authorizations:
BearerAuth
path Parameters
app_user_id
required
string

The App User ID of the customer to be deleted (might be an aliased App User ID).

Responses

Response samples

Content type
application/json
{
  • "app_user_id": "XXX-XXXXX-XXXXX-XX",
  • "deleted": true
}

Add Customer Attribution Data Deprecated

Attaches attribution data to a subscriber from specific supported networks.

Authorizations:
BearerAuth
path Parameters
app_user_id
required
string

The App User ID of the Customer.

Request Body schema: application/json
required
object

The data returned by the attribution network callbacks.

rc_idfa
string

The idfa from AdSupport on iOS. (iOS Only)

rc_gps_adid
string

The Google Play Services Advertising identifier. (Android Only)

network
required
string
Enum: "0" "1" "2" "3" "4" "5"

The attribution network the data is coming from:

  • 0: Apple Search AdSupport
  • 1: Adjust
  • 2: AppsFlyer
  • 3: Branch
  • 4: Tenjin
  • 5: Facebook

Responses

Request samples

Content type
application/json
{
  • "data": {
    },
  • "network": "0"
}

Response samples

Content type
application/json
"{}"

Update Customer Attributes

Updates attributes for a customer.

Authorizations:
BearerAuth
path Parameters
app_user_id
required
string

The App User ID used with the mobile SDK.

Request Body schema: application/json
object
required
object

Mapping of keys to attribute values.

value
required
string

The value of the attribute. If the value is null or an empty string, the attribute will be deleted.

updated_at_ms
integer <int64>

UNIX epoch in milliseconds of when the attribute was updated. This value is used to resolve conflicts, an attribute will only be updated if the new updated_at_ms value is newer than the value for the stored attribute.

Responses

Request samples

Content type
application/json
{
  • "attributes": {
    }
}

Response samples

Content type
application/json
{
  • "value": {
    }
}

Offerings

Operations about offerings.

Override a Customer's Current Offering

Overrides the current Offering for a specific Customer

Authorizations:
BearerAuth
path Parameters
app_user_id
required
string

The App User ID of the Customer.

offering_uuid
required
string

The UUID for the offering you want to set as the override for the Customer. The UUID can be found in the URL of the offering. For example, the offering UUID in https://app.revenuecat.com/apps/abcd1234/offerings/ofrng1234567abc is ofrng1234567abc.

Responses

Response samples

Content type
application/json
{
  • "value": {
    }
}

Remove a Customer's Current Offering Override

Reset the offering overrides back to the current offering for a specific Customer

Authorizations:
BearerAuth
path Parameters
app_user_id
required
string

The App User ID of the Customer.

Responses

Response samples

Content type
application/json
{
  • "value": {
    }
}

Get Offerings

Gets the offerings for your app.

Authorizations:
BearerAuth
path Parameters
app_user_id
required
string

The App User ID used with the mobile SDK. The App User ID doesn't have to exist for the endpoint to work but it can affect the current offering depending on whether you have any Experiments running or have overridden the current offering for this specific App User ID.

header Parameters
X-Platform
string
Example: ios

Set the X-Platform header to fetch that platform's packages. Can be ios, android, amazon, stripe, roku, or paddle. This header is required if you use a legacy public API key to determine which store the products should be returned for. It is not required if you use a new, app-specific API key, in which case the products for the app associated with the API key will be returned.

Responses

Response samples

Content type
application/json
{
  • "value": {
    }
}

Entitlements

Operations about entitlements.

Grant an Entitlement

Grants a Customer an entitlement. Does not override or defer a store transaction, applied simultaneously.

Authorizations:
BearerAuth
path Parameters
app_user_id
required
string

The App User ID of the Customer.

entitlement_identifier
required
string

The identifier for the entitlement you want to grant to the Customer.

Request Body schema: application/json
end_time_ms
integer <int64>

A Unix epoch in milliseconds for when the entitlement should expire. The entitlement will always be granted immediately. If not provided then duration must be provided.

duration
string
Deprecated
Enum: "daily" "three_day" "weekly" "two_week" "monthly" "two_month" "three_month" "six_month" "yearly" "lifetime"

How long of a duration to grant the entitlement for. If not provided then end_time_ms must be provided.

start_time_ms
integer <int64>
Deprecated

A Unix epoch in milliseconds used to determine the expiration date, by adding duration to start_time_ms. Regardless of what start_time_ms is set to, the entitlement will always be granted immediately. If start_time_ms is not provided, the duration will be added to the current time to determine the expiration date.

Responses

Request samples

Content type
application/json
{
  • "start_time_ms": 1709195668093,
  • "end_time_ms": 1709196532093
}

Response samples

Content type
application/json
{
  • "value": {
    }
}

Revoke Granted Entitlements

Revokes all granted entitlements for a given entitlement identifier and App User ID.

Authorizations:
BearerAuth
path Parameters
app_user_id
required
string

The App User ID of the Customer.

entitlement_identifier
required
string

The identifier for the entitlement you want to revoke from the Customer.

Responses

Response samples

Content type
application/json
{
  • "value": {
    }
}

Customer Info

request_date
string

Date of the request in ISO 8601 format.

request_date_ms
integer <int64>

Date of the request in milliseconds since Epoch.

object

Information about the Customer.

object

Dictionary of the entitlements of this Customer (including any expired entitlements).

first_seen
string

The ISO 8601 datetime string corresponding to when the Customer was first seen by RevenueCat.

last_seen
string

The ISO 8601 datetime string corresponding to when the Customer was last seen by RevenueCat.

management_url
string

URL to manage the active subscription of the Customer. If the Customer has an active iOS subscription, this will point to the App Store, if the Customer has an active Play Store subscription it will point there.

If there are no active subscriptions it will be null.

If the Customer has multiple active subscriptions for different platforms, this will take the value of the OS in the X-Platform header into consideration:

  • If the request was made on an OS for which there are active subscriptions, this will return the URL for the store that matches the header.
  • If the request was made on a different OS or the OS was not included in the X-Platform header, this will return the URL for the store of the subscription with the farthest future expiration date.
object

Non-subscription purchases of the Customer, keyed by the product identifier.

original_app_user_id
string

The App User ID under which this Customer was first known to RevenueCat.

original_application_version
string

Only available on iOS. This will be null until an iOS receipt is sent for the Customer. After a receipt has been sent, it will indicate the first App Store version of your app that the Customer installed.

original_purchase_date
string

Only available on iOS. The date that the app was first purchased/downloaded by the Customer. Will be null if no receipt is recorded for the Customer. Useful for Migrating Subscriptions.

other_purchases
object
Deprecated
object

A dictionary of any Attributes set on this Customer. Only included in responses to requests made with a secret API key.

object

Subscription purchases of the Customer, keyed by the product identifier.

{
  • "request_date": "2019-07-26T17:40:10Z",
  • "request_date_ms": 1564162810884,
  • "subscriber": {
    }
}

Offerings

current_offering_id
string

The identifier of the current Offering for this Customer. Targeting, Offering overrides, and Experiments affect this identifier depending on the App User ID.

Array of objects

A list of available Offerings.

Array
description
string

The Offering's description.

identifier
string

The Offering's identifier.

Array of objects

The Packages of this Offering.

{
  • "current_offering_id": "default",
  • "offerings": [
    ]
}