Skip to main content

Developer API (2.0.0)

Download OpenAPI specification:Download

Overview (v2)

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.
API v2 under development
REST API v2 is currently under development and does not yet cover all use cases from API v1. For those missing use cases, please use v1 in the meantime.

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

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
Authorization type `Bearer` required in header
he RevenueCat REST API v2 requires stating the authorization type `Bearer` in the `Authorization` header before the API key in accordance with [RFC 7235](https://datatracker.ietf.org/doc/html/rfc7235). This is different to the v1 API which allowed passing just the API key as the `Authorization` header.
API v1 keys will not work with REST API v2
In order to utilize the RevenueCat API v2, please create new v2 secret keys and define your permissions.

API v2 Permissions

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.

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

Params

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

Pagination

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.

Parameters

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.

Rate Limit

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

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.

Error Handling

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.

Error Codes

Code Name Description
200 OK Processed as expected
201 Created Entity was created
202 Accepted Request acknowledged, but cannot be processed in real time (for instance, async job)
204 No content The request was successful and there was no content that could be returned
400 Bad Request Client error
401 Unauthorized Not authenticated
403 Forbidden Authorization failed
404 Not Found No resource was found
409 Conflict Uniqueness constraint violation
418 I'm a teapot RevenueCat refuses to brew coffee
422 Unprocessable entity The request was valid and the syntax correct, but we were unable to process the contained instructions.
423 Locked The request conflicted with another ongoing request
429 Too Many Requests Being rate limited
500 Internal Server Error The RevenueCat server ran into an unexpected problem – please check the RevenueCat status page for any known outages and/or report the issue to RevenueCat support
502 Bad Gateway Invalid response from an upstream server
503 Service Unavailable There wasn’t a server to handle the request
504 Gateway Timeout We could not get the response in time from the upstream server

Error Types

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.

Representation of Subscriptions

In comparison to our v1 REST API, we have made changes to improve the organization and accessibility of your customers’ subscriptions. The data model used in the RevenueCat REST API v2 has several advantages. Firstly, it better abstracts differences between different app stores, making it easier for you to access your data without needing to understand the specificities and idiosyncrasies of each individual store.

Additionally, the REST API v2 subscription data model provides richer information regarding your subscription data and includes new fields such as:

  • gives_access: Rather than having to create your own logic to determine if a customer should have access, we will provide you with that information directly.
  • auto_renewal_status: Previously you would have to use unsubscribe_detected_at, billing_issues_detected_at, and other fields to determine the auto renewal status of the customer, now we include this information to take away the estimation work.
  • status: Gives you a quick and easy way to gather the status of the customer’s subscription to determine what state they are currently in.
  • store_subscription_identifier: Whereas the old data model was missing the store’s subscription identifier (aka the transaction ID directly from the stores), we have included this new field to help identify your customer’s subscription.
  • total_revenue_in_usd: You can easily determine how much a customer has spent for this subscription in USD and utilize it for your own bookkeeping purposes. This object also contains information such as gross, commission, tax, and proceeds to help you break down the customer’s revenue.

To view more details of fields we have included for the subscription object, check out the model reference.

Eventually we will also expose this sort of information in webhooks and customer event details to incorporate the new data model throughout RevenueCat.

What constitutes a new subscription

Different stores supported by RevenueCat have different logic to define what is a new subscription vs. a change to an existing subscription. To make it easier to handle subscriptions across different stores, the data model for the RevenueCat REST API v2 is now following a consistent definition of what continues the same subscription vs. a new one:

  • After a subscription has lapsed (e.g: after a billing retry or letting subscription expire after an unsubscribe), if a customer subscribes to the same product it will be considered a new subscription (this was previously treated differently on Apple App Store vs. Google Play Store)
  • If the product of a paid subscription is changed, the subscription to the new product will be considered a new subscription. An exception is product changes during a trial period, the post-trial subscription period to a different product will not be considered a new subscription, but a regular trial conversion
  • For family shared subscriptions:
    • Family shared subscriptions will be considered as a new subscription (albeit with no revenue)
    • If family sharing access is revoked and later re-enabled, this will be considered as a new subscription

Diagrams for different cases

Billing issue: unrecovered

Billing issue: recovered

Lapsed subscription

Product changes: upgrade (no trial)

Product changes: downgrade (no trial)

Product changes (with trial)

Subscription paused: Recovery

Subscription paused: Billing issue, recovered

Subscription paused: Billing issue, unrecovered

Family shared subscriptions

Family shared subscriptions: regranted

Subscription Data Model

object
required
string
Value: "subscription"

String representing the object's type. Objects of the same type share the same value.

id
required
string [ 1 .. 255 ] characters

The ID of the subscription (generated by RevenueCat)

customer_id
required
string [ 1 .. 1500 ] characters

The ID of the customer

original_customer_id
required
string [ 1 .. 1500 ] characters

The ID of the original customer. Relevant for subscriptions that were transferred from one customer to another

product_id
required
string or null [ 1 .. 255 ] characters

The RevenueCat ID of the product that the customer is subscribed to. Exists for all store types except for promotional.

starts_at
required
integer

The date when the subscription originally started in ms since epoch

current_period_starts_at
required
integer

The date when the subscription billing period started in ms since epoch

current_period_ends_at
required
integer or null

The date when the subscription billing period is expected to end in ms since epoch. Can be null if the subscription is paused until an indefinite date.

gives_access
required
boolean

Determines whether the customer should currently be provided access to the entitlements associated with the subscription

pending_payment
required
boolean

Determines whether there is a pending payment associated with the subscription

auto_renewal_status
required
string
Enum: "will_renew" "will_not_renew" "will_change_product" "will_pause" "requires_price_increase_consent" "has_already_renewed"

The auto renewal status of a subscription.

Possible values:
will_renew: the subscription is currently set to automatically renew
will_not_renew: the subscription is currently set to expire at the end of the period
will_change_product: the subscription is currently set to change product at the end of the period (which might start a new subscription)
will_pause: the subscription is currently set to pause at the end of the current period
requires_price_increase_consent: the subscription will expire at the end of the current period unless the customer consents to the price increase
has_already_renewed: the customer has already been charged for the upcoming renewal (so the renewal will take place even if the customer opts out of auto-renewal before the end of the period)

status
required
string
Enum: "trialing" "active" "expired" "in_grace_period" "in_billing_retry" "paused" "unknown" "incomplete"

The status of a subscription. Please note that additional states might be added in the future. To determine whether or not a subscription currently provides access to any associated entitlements, use the gives_access field.

Possible values:
trialing: the subscription is in a free trial period
active: the subscription is active, in a paid period
expired: the subscription is expired and no longer active
in_grace_period: the subscription is past its regular expiry date and experienced a billing issue, but is currently still in an access-granting grace period
in_billing_retry: the subscription has experienced a billing issue. Billing is being retried, access is suspended.-paused: the subscription is currently paused and should not provide access.
unknown: the subscription is in an unknown state. Refer to the gives_access field to determine whether or not to grant access.
incomplete: the subscription is in an incomplete state, maybe due to incorrect billing details or because it's scheduled to start in the future.

required
MonetaryAmount (object)

Total revenue generated by a subscription in USD

One of
currency
required
string (Currency)
Enum: "AED" "AFN" "ALL" "AMD" "ANG" "AOA" "ARS" "AUD" "AWG" "AZN" … 160 more

ISO 4217 currency code

gross
required
number

Total revenue generated (excluding taxes and commission)

commission
number

Store commission or payment processor fees deducted from gross revenue (if any)

tax
required
number

Estimated taxes deducted from gross revenue

proceeds
required
number

Net revenue after store commission / fees and taxes

presented_offering_id
required
string or null [ 1 .. 200 ] characters

The ID of the offering the customer saw when purchasing the subscription

required
object (EntitlementList)
object
required
string
Value: "list"

String representing the object's type. Objects of the same type share the same value. Always has the value list.

required
Array of objects (Entitlement)

Details about each object.

next_page
required
string or null

URL to access the next page of the customer's entitlements. If not present / null, there is no next page

url
required
string <= 5000 characters

The URL where this list can be accessed.

required
Environment (string)

The store environment

One of
string (Environment)
Enum: "production" "sandbox"

The store environment

store
required
string
Enum: "amazon" "app_store" "mac_app_store" "play_store" "promotional" "stripe" "rc_billing"

Store the subscription belongs to

store_subscription_identifier
required
string [ 1 .. 255 ] characters

The subscription identifier as per the store (e.g, for Apple App Store, the transaction_id of the latest transaction of the subscription, or for Google Play Store, the Order ID of the last renewal of the subscription)

required
Ownership (string)

Ownership of the subscription

One of
string (Ownership)
Enum: "purchased" "family_shared"

Ownership of the subscription

object or null

Indicates pending product changes. Present if the auto_renewal_status is will_change_product.

object (Product)
object
required
string
Value: "product"

String representing the object's type. Objects of the same type share the same value. Always has the value list.

id
required
string [ 1 .. 255 ] characters

The id of the product

store_identifier
required
string [ 1 .. 255 ] characters

The store product identifier

type
required
string (ProductType)
Enum: "subscription" "one_time"
object or null (SubscriptionProduct)
object or null (OneTimeProduct)
created_at
required
integer

The date when the product was created in ms since epoch

app_id
required
string [ 1 .. 255 ] characters

The id of the app

object (App)
display_name
required
string or null [ 1 .. 1500 ] characters

The display name of the product

country
string or null (Country)
Enum: null "AF" "AL" "DZ" "AS" "AD" "AO" "AI" "AQ" "AG" … 240 more

The country that the object is associated with, in ISO alpha 2 code

management_url
required
string or null

The URL to manage the subscription

{
  • "object": "subscription",
  • "id": "sub1ab2c3d4e5",
  • "customer_id": "19b8de26-77c1-49f1-aa18-019a391603e2",
  • "original_customer_id": "19b8de26-77c1-49f1-aa18-019a391603e2",
  • "product_id": "prod1a2b3c4d5e",
  • "starts_at": 1658399423658,
  • "current_period_starts_at": 1658399423658,
  • "current_period_ends_at": 1658399423658,
  • "gives_access": true,
  • "pending_payment": true,
  • "auto_renewal_status": "will_renew",
  • "status": "trialing",
  • "total_revenue_in_usd": {
    },
  • "presented_offering_id": "ofrnge1a2b3c4d5",
  • "entitlements": {
    },
  • "environment": "production",
  • "store": "amazon",
  • "store_subscription_identifier": 12345678,
  • "ownership": "purchased",
  • "pending_changes": {
    },
  • "country": "US",
}

App

Operations about apps.

Get a list of apps

This endpoint requires the following permission(s): project_configuration:apps:read.

Authorizations:
BearerAuth
path Parameters
project_id
required
string <= 255 characters
Example: proj1ab2c3d4

ID of the project

query Parameters
starting_after
string
Example: starting_after=ent12354
limit
integer
Default: 20
Example: limit=10

Responses

Response samples

Content type
application/json
{
  • "object": "list",
  • "items": [
    ],
  • "next_page": "/v2/projects/projec1a2b3c4d/apps?starting_after=app1a2b3c4d",
  • "url": "/v2/projects/projec1a2b3c4d/apps"
}

Create an App

This endpoint requires the following permission(s): project_configuration:apps:read_write.

Authorizations:
BearerAuth
path Parameters
project_id
required
string <= 255 characters
Example: proj1ab2c3d4

ID of the project

Request Body schema: application/json
required
name
required
string [ 1 .. 255 ] characters

The name of the app

type
required
string
Enum: "amazon" "app_store" "mac_app_store" "play_store" "stripe" "rc_billing" "roku"

The platform of the app. Mac App Store is disabled by default. See Legacy Mac Apps for more details.

object

Amazon type details. Should only be used when type is amazon.

package_name
required
string [ 1 .. 256 ] characters

The package name of the app

shared_secret
string

Your Amazon Developer Identity Shared Key

object

App Store type details. Should only be used when type is app_store.

bundle_id
required
string [ 1 .. 256 ] characters

The bundle ID of the app

shared_secret
string = 32 characters

The shared secret of the app

subscription_private_key
required
string [ 1 .. 4500 ] characters

PKCS /#8 In App Key downloaded from App Store Connect in PEM format. Copy the contents of the file in this field. See instructions on how to get it in: https://www.revenuecat.com/docs/in-app-purchase-key-configuration

subscription_key_id
required
string [ 1 .. 32 ] characters

In App Key id. The ID of the downloaded in app key. You can get it from App Store Connect

subscription_key_issuer
required
string [ 1 .. 36 ] characters
object

Mac App Store type details. Should only be used when type is mac_app_store.

bundle_id
required
string [ 1 .. 256 ] characters

The bundle ID of the app

shared_secret
string = 32 characters

The shared secret of the app

object

Play Store type details. Should only be used when type is play_store.

package_name
required
string [ 1 .. 256 ] characters

The package name of the app

object

Stripe type details. Should only be used when type is stripe.

stripe_account_id
string or null [ 1 .. 256 ] characters

It needs to be connected to your RevenueCat account. It can be omitted if you only have a single Stripe account connected to your RevenueCat account.

object or null

Revenue Cat Billing Store type details

stripe_account_id
string or null [ 1 .. 256 ] characters

It needs to be connected to your RevenueCat account. It can be omitted if you only have a single Stripe account connected to your RevenueCat account.

seller_company_name
required
string [ 1 .. 256 ] characters

The company name.

seller_company_support_email
string or null [ 1 .. 320 ] characters

The company support email.

default_currency
string (RCBillingCurrency)
Enum: "AUD" "CAD" "EUR" "GBP" "JPY" "USD"

ISO 4217 currency code

object or null

Roku Channel Store details. Should only be used when type is roku.

roku_api_key
string or null = 33 characters

Roku Pay API key provided on the Roku Pay Web Services page.

roku_channel_id
string or null = 6 characters

Channel ID provided on the Roku Channel page.

roku_channel_name
string or null [ 1 .. 30 ] characters

Channel name that is displayed on the Roku Channel page.

Responses

Request samples

Content type
application/json
Example
{
  • "name": "My App Store App",
  • "type": "app_store",
  • "app_store": {
    }
}

Response samples

Content type
application/json
{
  • "object": "app",
  • "id": "app1a2b3c4",
  • "name": "string",
  • "created_at": 1658399423658,
  • "type": "app_store",
  • "project_id": "proj1a2b3c4",
  • "amazon": {
    },
  • "app_store": {
    },
  • "mac_app_store": {
    },
  • "play_store": {
    },
  • "stripe": {
    },
  • "rc_billing": {
    },
  • "roku": {
    }
}

Get an app

This endpoint requires the following permission(s): project_configuration:apps:read.

Authorizations:
BearerAuth
path Parameters
project_id
required
string <= 255 characters
Example: proj1ab2c3d4

ID of the project

app_id
required
string <= 255 characters
Example: app1ab2c3d4

ID of the app

Responses

Response samples

Content type
application/json
{
  • "object": "app",
  • "id": "app1a2b3c4",
  • "name": "string",
  • "created_at": 1658399423658,
  • "type": "app_store",
  • "project_id": "proj1a2b3c4",
  • "amazon": {
    },
  • "app_store": {
    },
  • "mac_app_store": {
    },
  • "play_store": {
    },
  • "stripe": {
    },
  • "rc_billing": {
    },
  • "roku": {
    }
}

Update an app

This endpoint requires the following permission(s): project_configuration:apps:read_write.

Authorizations:
BearerAuth
path Parameters
project_id
required
string <= 255 characters
Example: proj1ab2c3d4

ID of the project

app_id
required
string <= 255 characters
Example: app1ab2c3d4

ID of the app

Request Body schema: application/json
required
name
string [ 1 .. 255 ] characters

The name of the app

object

Amazon type details. Should only be used when type is amazon.

package_name
string [ 1 .. 256 ] characters

The package name of the app

shared_secret
string or null

Your Amazon Developer Identity Shared Key

object

App Store type details. Should only be used when type is app_store.

bundle_id
string [ 1 .. 256 ] characters

The bundle ID of the app

shared_secret
string or null = 32 characters

The shared secret of the app

object

Legacy Mac App Store type details. Should only be used when type is mac_app_store.

bundle_id
string [ 1 .. 256 ] characters

The bundle ID of the app

shared_secret
string or null = 32 characters

The shared secret of the app

object

Play Store type details. Should only be used when type is play_store.

package_name
required
string [ 1 .. 256 ] characters

The package name of the app

object

Stripe type details. Should only be used when type is stripe.

stripe_account_id
string [ 1 .. 256 ] characters

It needs to be connected to your RevenueCat account. It can be omitted if you only have a single Stripe account connected to your RevenueCat account.

object

RevenueCat Billing type details. Should only be used when type is rc_billing.

stripe_account_id
string or null [ 1 .. 256 ] characters

It needs to be connected to your RevenueCat account. It can be omitted if you only have a single Stripe account connected to your RevenueCat account.

seller_company_name
string or null [ 1 .. 256 ] characters

The company name.

seller_company_support_email
string or null [ 1 .. 320 ] characters

The company support email.

default_currency
string (RCBillingCurrency)
Enum: "AUD" "CAD" "EUR" "GBP" "JPY" "USD"

ISO 4217 currency code

object

Roku Channel Store type details. Should only be used when type is roku.

roku_api_key
string or null = 33 characters

Roku Pay API key provided on the Roku Pay Web Services page.

roku_channel_id
string or null = 6 characters

Channel ID provided on the Roku Channel page.

roku_channel_name
string or null [ 1 .. 30 ] characters

Channel name that is displayed on the Roku Channel page.

Responses

Request samples

Content type
application/json
Example
{
  • "name": "New App name",
  • "app_store": {
    }
}

Response samples

Content type
application/json
{
  • "object": "app",
  • "id": "app1a2b3c4",
  • "name": "string",
  • "created_at": 1658399423658,
  • "type": "app_store",
  • "project_id": "proj1a2b3c4",
  • "amazon": {
    },
  • "app_store": {
    },
  • "mac_app_store": {
    },
  • "play_store": {
    },
  • "stripe": {
    },
  • "rc_billing": {
    },
  • "roku": {
    }
}

Delete an app

This endpoint requires the following permission(s): project_configuration:apps:read_write.

Authorizations:
BearerAuth
path Parameters
project_id
required
string <= 255 characters
Example: proj1ab2c3d4

ID of the project

app_id
required
string <= 255 characters
Example: app1ab2c3d4

ID of the app

Responses

Response samples

Content type
application/json
{
  • "object": "app",
  • "id": "string",
  • "deleted_at": 1658399423658
}

Charts & Metrics

Operations about chart metrics.

Get overview metrics for a project

This endpoint requires the following permission(s): charts_metrics:overview:read.

Authorizations:
BearerAuth
path Parameters
project_id
required
string <= 255 characters
Example: proj1ab2c3d4

ID of the project

Responses

Response samples

Content type
application/json
{
  • "object": "overview_metrics",
  • "metrics": [
    ]
}

Customer

Operations about customers.

Get a list of customers

This endpoint requires the following permission(s): customer_information:customers:read.

Authorizations:
BearerAuth
path Parameters
project_id
required
string <= 255 characters
Example: proj1ab2c3d4

ID of the project

query Parameters
starting_after
string
Example: starting_after=ent12354
limit
integer
Default: 20
Example: limit=10

Responses

Response samples

Content type
application/json
{
  • "object": "list",
  • "items": [
    ],
  • "next_page": "/v2/projects/projec1a2b3c4d/customers?starting_after=223xx1100",
  • "url": "/v2/projects/projec1a2b3c4d/customers"
}

Create a customer

This endpoint requires the following permission(s): customer_information:customers:read_write.

Authorizations:
BearerAuth
path Parameters
project_id
required
string <= 255 characters
Example: proj1ab2c3d4

ID of the project

Request Body schema: application/json
required
id
required
string [ 1 .. 1500 ] characters ^[0-9a-zA-Z_-]*$

The ID of the customer

Array of objects <= 50 characters
Array
required
CustomerAttributeReservedName (string) or CustomerAttributeCustomName (string) [ 1 .. 40 ] characters

The name of the attribute

value
required
string <= 500 characters

The value of the attribute

Responses

Request samples

Content type
application/json
{
  • "id": "19b8de26-77c1-49f1-aa18-019a391603e2",
  • "attributes": [
    ]
}

Response samples

Content type
application/json
{
  • "object": "customer",
  • "id": "19b8de26-77c1-49f1-aa18-019a391603e2",
  • "project_id": "proj1ab2c3d4",
  • "first_seen_at": 1658399423658,
  • "last_seen_at": 1658399423658,
  • "active_entitlements": {
    },
  • "experiment": {
    }
}

Get a customer

This endpoint requires the following permission(s): customer_information:customers:read.

Authorizations:
BearerAuth
path Parameters
project_id
required
string <= 255 characters
Example: proj1ab2c3d4

ID of the project

customer_id
required
string [ 1 .. 1500 ] characters
Example: 19b8de26-77c1-49f1-aa18-019a391603e2

ID of the customer

Responses

Response samples

Content type
application/json
{
  • "object": "customer",
  • "id": "19b8de26-77c1-49f1-aa18-019a391603e2",
  • "project_id": "proj1ab2c3d4",
  • "first_seen_at": 1658399423658,
  • "last_seen_at": 1658399423658,
  • "active_entitlements": {
    },
  • "experiment": {
    }
}

Delete a customer

This endpoint requires the following permission(s): customer_information:customers:read_write.

Authorizations:
BearerAuth
path Parameters
project_id
required
string <= 255 characters
Example: proj1ab2c3d4

ID of the project

customer_id
required
string [ 1 .. 1500 ] characters
Example: 19b8de26-77c1-49f1-aa18-019a391603e2

ID of the customer

Responses

Response samples

Content type
application/json
{
  • "object": "customer",
  • "id": "b5b7bfd2-66fb-4091-af50-7c3cdccfdf24",
  • "deleted_at": 1658399423658
}

Get a list of subscriptions associated with a customer

This endpoint requires the following permission(s): customer_information:subscriptions:read.

Authorizations:
BearerAuth
path Parameters
project_id
required
string <= 255 characters
Example: proj1ab2c3d4

ID of the project

customer_id
required
string [ 1 .. 1500 ] characters
Example: 19b8de26-77c1-49f1-aa18-019a391603e2

ID of the customer

query Parameters
environment
string
Enum: "sandbox" "production"
Example: environment=production
starting_after
string
Example: starting_after=ent12354
limit
integer
Default: 20
Example: limit=10

Responses

Response samples

Content type
application/json
{
  • "object": "list",
  • "items": [
    ],
  • "next_page": "/v2/projects/proj1ab2c3d4/customers/19b8de26-77c1-49f1-aa18-019a391603e2/subscriptions?starting_after=sub1a2b3c4d",
  • "url": "/v2/projects/proj1ab2c3d4/customers/19b8de26-77c1-49f1-aa18-019a391603e2/subscriptions"
}

Get a list of purchases associated with a customer

This endpoint requires the following permission(s): customer_information:purchases:read.

Authorizations:
BearerAuth
path Parameters
project_id
required
string <= 255 characters
Example: proj1ab2c3d4

ID of the project

customer_id
required
string [ 1 .. 1500 ] characters
Example: 19b8de26-77c1-49f1-aa18-019a391603e2

ID of the customer

query Parameters
environment
string
Enum: "sandbox" "production"
Example: environment=production
starting_after
string
Example: starting_after=ent12354
limit
integer
Default: 20
Example: limit=10

Responses

Response samples

Content type
application/json
{
  • "object": "list",
  • "items": [
    ],
  • "next_page": "/v2/projects/proj1ab2c3d4/customers/19b8de26-77c1-49f1-aa18-019a391603e2/purchases?starting_after=purc1a2b3c4d5e",
  • "url": "/v2/projects/proj1ab2c3d4/customers/19b8de26-77c1-49f1-aa18-019a391603e2/purchases"
}

Get a list of customer's active entitlements

This endpoint requires the following permission(s): customer_information:customers:read.

Authorizations:
BearerAuth
path Parameters
project_id
required
string <= 255 characters
Example: proj1ab2c3d4

ID of the project

customer_id
required
string [ 1 .. 1500 ] characters
Example: 19b8de26-77c1-49f1-aa18-019a391603e2

ID of the customer

query Parameters
starting_after
string
Example: starting_after=ent12354
limit
integer
Default: 20
Example: limit=10

Responses

Response samples

Content type
application/json
{
  • "object": "list",
  • "items": [
    ],
  • "next_page": "/v2/projects/proj1ab2c3d4/customers/19b8de26-77c1-49f1-aa18-019a391603e2/active_entitlements?starting_after=entlab21dac",
  • "url": "/v2/projects/proj1ab2c3d4/customers/19b8de26-77c1-49f1-aa18-019a391603e2/active_entitlements"
}

Get a list of the customer's aliases

This endpoint requires the following permission(s): customer_information:customers:read.

Authorizations:
BearerAuth
path Parameters
project_id
required
string <= 255 characters
Example: proj1ab2c3d4

ID of the project

customer_id
required
string [ 1 .. 1500 ] characters
Example: 19b8de26-77c1-49f1-aa18-019a391603e2

ID of the customer

query Parameters
starting_after
string
Example: starting_after=ent12354
limit
integer
Default: 20
Example: limit=10

Responses

Response samples

Content type
application/json
{
  • "object": "list",
  • "items": [
    ],
  • "next_page": "/v2/projects/proj1ab2c3d4/customers/19b8de26-77c1-49f1-aa18-019a391603e2/aliases?starting_after=9fjeja8fjed",
  • "url": "/v2/projects/proj1ab2c3d4/customers/19b8de26-77c1-49f1-aa18-019a391603e2/aliases"
}

Entitlement

Operations about entitlements.

Get an entitlement

This endpoint requires the following permission(s): project_configuration:entitlements:read.

Authorizations:
BearerAuth
path Parameters
project_id
required
string <= 255 characters
Example: proj1ab2c3d4

ID of the project

entitlement_id
required
string [ 1 .. 255 ] characters
Example: entla1b2c3d4e5

ID of the entitlement

query Parameters
expand
Array of strings[ items [ 1 .. 5000 ] characters ]
Items Value: "product"
Example: expand=product

Specifies which fields in the response should be expanded. Accepted values are: product (requires project_configuration:products:read permissions).

Responses

Response samples

Content type
application/json
{
  • "object": "entitlement",
  • "project_id": "proj1ab2c3d4",
  • "id": "entla1b2c3d4e5",
  • "lookup_key": "premium",
  • "display_name": "Premium",
  • "created_at": 1658399423658,
  • "products": {
    }
}

Update an entitlement

This endpoint requires the following permission(s): project_configuration:entitlements:read_write.

Authorizations:
BearerAuth
path Parameters
project_id
required
string <= 255 characters
Example: proj1ab2c3d4

ID of the project

entitlement_id
required
string [ 1 .. 255 ] characters
Example: entla1b2c3d4e5

ID of the entitlement

Request Body schema: application/json
required
display_name
required
string [ 1 .. 1500 ] characters

The display name of the entitlement

Responses

Request samples

Content type
application/json
{
  • "display_name": "Premium"
}

Response samples

Content type
application/json
{
  • "object": "entitlement",
  • "project_id": "proj1ab2c3d4",
  • "id": "entla1b2c3d4e5",
  • "lookup_key": "premium",
  • "display_name": "Premium",
  • "created_at": 1658399423658,
  • "products": {
    }
}

Delete an entitlement

This endpoint requires the following permission(s): project_configuration:entitlements:read_write.

Authorizations:
BearerAuth
path Parameters
project_id
required
string <= 255 characters
Example: proj1ab2c3d4

ID of the project

entitlement_id
required
string [ 1 .. 255 ] characters
Example: entla1b2c3d4e5

ID of the entitlement

Responses

Response samples

Content type
application/json
{
  • "object": "app",
  • "id": "string",
  • "deleted_at": 1658399423658
}

Get a list of entitlements

This endpoint requires the following permission(s): project_configuration:entitlements:read.

Authorizations:
BearerAuth
path Parameters
project_id
required
string <= 255 characters
Example: proj1ab2c3d4

ID of the project

query Parameters
starting_after
string
Example: starting_after=ent12354
limit
integer
Default: 20
Example: limit=10
expand
Array of strings[ items [ 1 .. 5000 ] characters ]
Items Value: "items.product"
Example: expand=items.product

Specifies which fields in the response should be expanded. Accepted values are: items.product (requires project_configuration:products:read permissions).

Responses

Response samples

Content type
application/json
{
  • "object": "list",
  • "items": [
    ],
  • "next_page": "/v2/projects/proj1ab2c3d4/entitlements?starting_after=entlab21dac",
  • "url": "/v2/projects/proj1ab2c3d4/entitlements"
}

Create an entitlement

This endpoint requires the following permission(s): project_configuration:entitlements:read_write.

Authorizations:
BearerAuth
path Parameters
project_id
required
string <= 255 characters
Example: proj1ab2c3d4

ID of the project

Request Body schema: application/json
required
lookup_key
required
string [ 1 .. 200 ] characters

The identifier of the entitlement

display_name
required
string [ 1 .. 1500 ] characters

The display name of the entitlement

Responses

Request samples

Content type
application/json
{
  • "lookup_key": "premium",
  • "display_name": "Premium access to all features"
}

Response samples

Content type
application/json
{
  • "object": "entitlement",
  • "project_id": "proj1ab2c3d4",
  • "id": "entla1b2c3d4e5",
  • "lookup_key": "premium",
  • "display_name": "Premium",
  • "created_at": 1658399423658,
  • "products": {
    }
}

Get a list of products attached to a given entitlement

This endpoint requires the following permission(s): project_configuration:entitlements:read.

Authorizations:
BearerAuth
path Parameters
project_id
required
string <= 255 characters
Example: proj1ab2c3d4

ID of the project

entitlement_id
required
string [ 1 .. 255 ] characters
Example: entla1b2c3d4e5

ID of the entitlement

query Parameters
starting_after
string
Example: starting_after=ent12354
limit
integer
Default: 20
Example: limit=10

Responses

Response samples

Content type
application/json
{
  • "object": "list",
  • "items": [
    ],
  • "next_page": "/v2/projects/proj1ab2c3d4/entitlements/entla1b2c3d4e5/products?starting_after=prod1a2b3c4d5",
  • "url": "/v2/projects/proj1ab2c3d4/entitlements/entla1b2c3d4e5/products"
}

Attach a set of products to an entitlement

This endpoint requires the following permission(s): project_configuration:entitlements:read_write.

Authorizations:
BearerAuth
path Parameters
project_id
required
string <= 255 characters
Example: proj1ab2c3d4

ID of the project

entitlement_id
required
string [ 1 .. 255 ] characters
Example: entla1b2c3d4e5

ID of the entitlement

Request Body schema: application/json
required
product_ids
required
Array of strings [ 1 .. 50 ] characters [ items [ 1 .. 255 ] characters ]

IDs of the products to be attached to the entitlement.

Responses

Request samples

Content type
application/json
{
  • "product_ids": [
    ]
}

Response samples

Content type
application/json
{
  • "object": "entitlement",
  • "project_id": "proj1ab2c3d4",
  • "id": "entla1b2c3d4e5",
  • "lookup_key": "premium",
  • "display_name": "Premium",
  • "created_at": 1658399423658,
  • "products": {
    }
}

Detach a set of product from an entitlement

This endpoint requires the following permission(s): project_configuration:entitlements:read_write.

Authorizations:
BearerAuth
path Parameters
project_id
required
string <= 255 characters
Example: proj1ab2c3d4

ID of the project

entitlement_id
required
string [ 1 .. 255 ] characters
Example: entla1b2c3d4e5

ID of the entitlement

Request Body schema: application/json
required
product_ids
required
Array of strings [ 1 .. 50 ] characters [ items [ 1 .. 255 ] characters ]

IDs of the products to be detached from the entitlement.

Responses

Request samples

Content type
application/json
{
  • "product_ids": [
    ]
}

Response samples

Content type
application/json
{
  • "object": "entitlement",
  • "project_id": "proj1ab2c3d4",
  • "id": "entla1b2c3d4e5",
  • "lookup_key": "premium",
  • "display_name": "Premium",
  • "created_at": 1658399423658,
  • "products": {
    }
}

Offering

Operations about offerings.

Get an offering

This endpoint requires the following permission(s): project_configuration:offerings:read.

Authorizations:
BearerAuth
path Parameters
project_id
required
string <= 255 characters
Example: proj1ab2c3d4

ID of the project

offering_id
required
string [ 1 .. 255 ] characters
Example: ofrnge1a2b3c4d5

ID of the offering

query Parameters
expand
Array of strings[ items [ 1 .. 5000 ] characters ]
Items Enum: "package" "package.product"
Example: expand=package

Specifies which fields in the response should be expanded. Accepted values are: package (requires project_configuration:packages:read permissions), package.product (requires project_configuration:products:read permissions).

Responses

Response samples

Content type
application/json
{
  • "object": "offering",
  • "id": "ofrnge1a2b3c4d5",
  • "lookup_key": "default",
  • "display_name": "The standard set of packages",
  • "is_current": true,
  • "created_at": 1658399423658,
  • "project_id": "proj1ab2c3d4",
  • "metadata": {
    },
  • "packages": {
    }
}

Update an offering

This endpoint requires the following permission(s): project_configuration:offerings:read_write.

Authorizations:
BearerAuth
path Parameters
project_id
required
string <= 255 characters
Example: proj1ab2c3d4

ID of the project

offering_id
required
string [ 1 .. 255 ] characters
Example: ofrnge1a2b3c4d5

ID of the offering

Request Body schema: application/json
required
display_name
string [ 1 .. 1500 ] characters

The display name of the offering

is_current
boolean

Indicates if the offering is the current offering

object or null (OfferingMetadata)

Custom metadata of the offering

property name*
additional property
any

Responses

Request samples

Content type
application/json
{
  • "display_name": "premium access to features",
  • "is_current": true,
  • "metadata": {
    }
}

Response samples

Content type
application/json
{
  • "object": "offering",
  • "id": "ofrnge1a2b3c4d5",
  • "lookup_key": "default",
  • "display_name": "The standard set of packages",
  • "is_current": true,
  • "created_at": 1658399423658,
  • "project_id": "proj1ab2c3d4",
  • "metadata": {
    },
  • "packages": {
    }
}

Delete an offering and its attached packages

This endpoint requires the following permission(s): project_configuration:offerings:read_write.

Authorizations:
BearerAuth
path Parameters
project_id
required
string <= 255 characters
Example: proj1ab2c3d4

ID of the project

offering_id
required
string [ 1 .. 255 ] characters
Example: ofrnge1a2b3c4d5

ID of the offering

Responses

Response samples

Content type
application/json
{
  • "object": "app",
  • "id": "string",
  • "deleted_at": 1658399423658
}

Get a list of offerings

This endpoint requires the following permission(s): project_configuration:offerings:read.

Authorizations:
BearerAuth
path Parameters
project_id
required
string <= 255 characters
Example: proj1ab2c3d4

ID of the project

query Parameters
starting_after
string
Example: starting_after=ent12354
limit
integer
Default: 20
Example: limit=10
expand
Array of strings[ items [ 1 .. 5000 ] characters ]
Items Enum: "items.package" "items.package.product"
Example: expand=items.package

Specifies which fields in the response should be expanded. Accepted values are: items.package (requires project_configuration:packages:read permissions), items.package.product (requires project_configuration:products:read permissions).

Responses

Response samples

Content type
application/json
{
  • "object": "list",
  • "items": [
    ],
  • "next_page": "/v2/projects/proj1ab2c3d4/offerings?starting_after=ofrngeab21da",
  • "url": "/v2/projects/proj1ab2c3d4/offerings"
}

Create an offering

This endpoint requires the following permission(s): project_configuration:offerings:read_write.

Authorizations:
BearerAuth
path Parameters
project_id
required
string <= 255 characters
Example: proj1ab2c3d4

ID of the project

Request Body schema: application/json
required
lookup_key
required
string [ 1 .. 200 ] characters

The custom identifier of the offering

display_name
required
string [ 1 .. 1500 ] characters

The display_name of the offering

object or null (OfferingMetadata)

Custom metadata of the offering

property name*
additional property
any

Responses

Request samples

Content type
application/json
{
  • "lookup_key": "default",
  • "display_name": "The standard set of packages",
  • "metadata": {
    }
}

Response samples

Content type
application/json
{
  • "object": "offering",
  • "id": "ofrnge1a2b3c4d5",
  • "lookup_key": "default",
  • "display_name": "The standard set of packages",
  • "is_current": true,
  • "created_at": 1658399423658,
  • "project_id": "proj1ab2c3d4",
  • "metadata": {
    },
  • "packages": {
    }
}

Package

Operations about packages.

Get a package

This endpoint requires the following permission(s): project_configuration:packages:read.

Authorizations:
BearerAuth
path Parameters
project_id
required
string <= 255 characters
Example: proj1ab2c3d4

ID of the project

package_id
required
string [ 1 .. 255 ] characters
Example: pkge1a2b3c4d5

ID of the package

query Parameters
expand
Array of strings[ items [ 1 .. 5000 ] characters ]
Items Value: "product"
Example: expand=product

Specifies which fields in the response should be expanded. Accepted values are: product (requires project_configuration:products:read permissions).

Responses

Response samples

Content type
application/json
{
  • "object": "package",
  • "id": "pkge1a2b3c4d5",
  • "lookup_key": "monthly",
  • "display_name": "Monthly discounted with 3-day trial",
  • "position": 1,
  • "created_at": 1658399423658,
  • "products": {
    }
}

Update a package

This endpoint requires the following permission(s): project_configuration:packages:read_write.

Authorizations:
BearerAuth
path Parameters
project_id
required
string <= 255 characters
Example: proj1ab2c3d4

ID of the project

package_id
required
string [ 1 .. 255 ] characters
Example: pkge1a2b3c4d5

ID of the package

Request Body schema: application/json
required
display_name
string [ 1 .. 1500 ] characters

The display name of the package

position
integer >= 1

The position of the package within the offering

Responses

Request samples

Content type
application/json
{
  • "display_name": "monthly with one-week trial",
  • "position": 2
}

Response samples

Content type
application/json
{
  • "object": "package",
  • "id": "pkge1a2b3c4d5",
  • "lookup_key": "monthly",
  • "display_name": "Monthly discounted with 3-day trial",
  • "position": 1,
  • "created_at": 1658399423658,
  • "products": {
    }
}

Delete a package

This endpoint requires the following permission(s): project_configuration:packages:read_write.

Authorizations:
BearerAuth
path Parameters
project_id
required
string <= 255 characters
Example: proj1ab2c3d4

ID of the project

package_id
required
string [ 1 .. 255 ] characters
Example: pkge1a2b3c4d5

ID of the package

Responses

Response samples

Content type
application/json
{
  • "object": "app",
  • "id": "string",
  • "deleted_at": 1658399423658
}

Get a list of packages in an offering

This endpoint requires the following permission(s): project_configuration:packages:read.

Authorizations:
BearerAuth
path Parameters
project_id
required
string <= 255 characters
Example: proj1ab2c3d4

ID of the project

offering_id
required
string [ 1 .. 255 ] characters
Example: ofrnge1a2b3c4d5

ID of the offering

query Parameters
starting_after
string
Example: starting_after=ent12354
limit
integer
Default: 20
Example: limit=10
expand
Array of strings[ items [ 1 .. 5000 ] characters ]
Items Value: "items.product"
Example: expand=items.product

Specifies which fields in the response should be expanded. Accepted values are: items.product (requires project_configuration:products:read permissions).

Responses

Response samples

Content type
application/json
{
  • "object": "list",
  • "items": [
    ],
  • "next_page": "/v2/projects/proj1ab2c3d4/offerings/ofrnge1a2b3c4d5/packages?starting_after=pkgeab21dac",
  • "url": "/v2/projects/proj1ab2c3d4/offerings/ofrnge1a2b3c4d5/packages"
}

Create a package

This endpoint requires the following permission(s): project_configuration:packages:read_write.

Authorizations:
BearerAuth
path Parameters
project_id
required
string <= 255 characters
Example: proj1ab2c3d4

ID of the project

offering_id
required
string [ 1 .. 255 ] characters
Example: ofrnge1a2b3c4d5

ID of the offering

Request Body schema: application/json
required
lookup_key
required
string [ 1 .. 200 ] characters

The lookup_key of the package

display_name
required
string [ 1 .. 1500 ] characters

The display name of the package

position
integer

The position of the package in the offering

Responses

Request samples

Content type
application/json
{
  • "lookup_key": "monthly",
  • "display_name": "monthly with one-week trial",
  • "position": 1
}

Response samples

Content type
application/json
{
  • "object": "package",
  • "id": "pkge1a2b3c4d5",
  • "lookup_key": "monthly",
  • "display_name": "Monthly discounted with 3-day trial",
  • "position": 1,
  • "created_at": 1658399423658,
  • "products": {
    }
}

Get a list of products attached to a given package of an o