GitHub Self-host free

What can I do with REST API v2?

REST API v2 follows RevenueCat's v2 paths, objects, list envelope and error format, so existing scripts keep working when you change the base URL and key. Authenticate with a secret key (Authorization: Bearer sk_...) or the dashboard session cookie. Lists return { "object": "list", "items": [...], "next_page": ..., "url": ... }; follow next_page to page. limit is 1 to 100 (default 20). RevenueDot-only endpoints are on Extensions.

Base URL: your server, for example http://localhost:8787 or https://revenuedot.example.com. The examples read REVENUEDOT_URL, PUBLIC_KEY, SECRET_KEY and PROJECT_ID from your shell.

Operations on this page (73)#

Projects#

Projects hold apps, the catalog, customers and webhooks.

List projects#

GET /v2/projects · Auth: secret key or dashboard session · Permissions: project_configuration:projects:read

A secret key sees its own project. A dashboard session sees every project the user is a member of.

Query parameters

Name Type Required Description
limit integer no Page size. Values outside 1-100 are clamped, not rejected.
starting_after string no Id of the last item of the previous page. Use next_page instead of building it.

Example request

Shell
curl -s "$REVENUEDOT_URL/v2/projects" -H "Authorization: Bearer $SECRET_KEY"

Responses

  • 200: A page of results. Returns a list of Project.
  • 401: No API key, or an unknown one. Returns V2Error.
  • 403: The key lacks a permission, or a public key was used. Returns V2Error.

Create a project#

POST /v2/projects · Auth: dashboard session · Permissions: project_configuration:projects:read_write

Needs a dashboard session: a secret key belongs to one project and cannot create another. The caller becomes the project's admin.

Request body (application/json)

Field Type Required Description
name string yes

Example request

Shell
curl -s -X POST "$REVENUEDOT_URL/v2/projects" \
  -H "Content-Type: application/json" -d '{"name":"Scanner"}'

Responses

  • 200: The project. Returns Project.
  • 400: The request is invalid. Returns V2Error.
  • 401: No API key, or an unknown one. Returns V2Error.
  • 403: The key lacks a permission, or a public key was used. Returns V2Error.

Apps#

One app per store, each with its public SDK key and store credentials.

List apps#

GET /v2/projects/{project_id}/apps · Auth: secret key or dashboard session · Permissions: project_configuration:apps:read

Path parameters

Name Type Required Description
project_id string yes Project id (proj...).

Query parameters

Name Type Required Description
limit integer no Page size. Values outside 1-100 are clamped, not rejected.
starting_after string no Id of the last item of the previous page. Use next_page instead of building it.

Example request

Shell
curl -s "$REVENUEDOT_URL/v2/projects/$PROJECT_ID/apps" -H "Authorization: Bearer $SECRET_KEY"

Responses

  • 200: A page of results. Returns a list of App.
  • 401: No API key, or an unknown one. Returns V2Error.
  • 403: The key lacks a permission, or a public key was used. Returns V2Error.
  • 404: Not found in this project (another project's ids also answer 404). Returns V2Error.

Create an app#

POST /v2/projects/{project_id}/apps · Auth: secret key or dashboard session · Permissions: project_configuration:apps:read_write

One app per store. app_store and mac_app_store need bundle_id; play_store and amazon need package_name. The app gets a public SDK key with the store's prefix. Other fields in the store object are saved as store credentials (for example subscription_private_key, subscription_key_id, subscription_key_issuer, play_service_account_credentials_json). They are never returned.

Path parameters

Name Type Required Description
project_id string yes Project id (proj...).

Request body (application/json)

Field Type Required Description
name string yes
type amazon, app_store, mac_app_store, play_store, stripe, rc_billing, roku, paddle, test_store yes
app_store object no bundle_id plus optional credentials.
mac_app_store object no
play_store object no package_name plus optional credentials.
amazon object no
stripe object no
rc_billing object or null no
roku object or null no
paddle object or null no

Example request

Shell
curl -s -X POST "$REVENUEDOT_URL/v2/projects/$PROJECT_ID/apps" -H "Authorization: Bearer $SECRET_KEY" \
  -H "Content-Type: application/json" -d '{"name":"Scanner (iOS)","type":"app_store","app_store":{"bundle_id":"com.example.scanner"}}'

Responses

  • 201: The app. Returns App.
  • 400: The request is invalid. Returns V2Error.
  • 401: No API key, or an unknown one. Returns V2Error.
  • 403: The key lacks a permission, or a public key was used. Returns V2Error.
  • 404: Not found in this project (another project's ids also answer 404). Returns V2Error.

Example 201 response:

JSON
{
  "object": "app",
  "id": "appugfw01uy",
  "name": "Scanner (iOS)",
  "created_at": 1790801342594,
  "type": "app_store",
  "project_id": "proj18pzzkao",
  "custom_url_scheme": "rc-4d13549313",
  "app_store": {
    "bundle_id": "com.example.scanner",
    "app_store_connect_api_key_configured": false,
    "subscription_key_configured": false,
    "app_store_connect_vendor_number": null
  }
}

Get an app#

GET /v2/projects/{project_id}/apps/{app_id} · Auth: secret key or dashboard session · Permissions: project_configuration:apps:read

Path parameters

Name Type Required Description
project_id string yes Project id (proj...).
app_id string yes App id (app...).

Example request

Shell
curl -s "$REVENUEDOT_URL/v2/projects/$PROJECT_ID/apps/$APP_ID" -H "Authorization: Bearer $SECRET_KEY"

Responses

  • 200: The app. Returns App.
  • 401: No API key, or an unknown one. Returns V2Error.
  • 403: The key lacks a permission, or a public key was used. Returns V2Error.
  • 404: Not found in this project (another project's ids also answer 404). Returns V2Error.

Update an app and its store credentials#

POST /v2/projects/{project_id}/apps/{app_id} · Auth: secret key or dashboard session · Permissions: project_configuration:apps:read_write

Send only the store object of the app's own type. A field set to null removes that credential; other values replace it. RevenueDot extensions in the store object: notification_forward_url (copy store notifications to another URL, for example RevenueCat during a dual run; null or "" turns it off), track_new_purchases, allow_unsigned_receipts, xcode_certificate, app_apple_id, pubsub_audience, pubsub_service_account. See App Store setup and Google Play setup.

Path parameters

Name Type Required Description
project_id string yes Project id (proj...).
app_id string yes App id (app...).

Request body (application/json)

Field Type Required Description
name string no
app_store object no
mac_app_store object no
play_store object no
amazon object no
stripe object no
rc_billing object no
roku object no
paddle object no

Example request

Shell
curl -s -X POST "$REVENUEDOT_URL/v2/projects/$PROJECT_ID/apps/$APP_ID" -H "Authorization: Bearer $SECRET_KEY" \
  -H "Content-Type: application/json" -d '{"app_store":{"subscription_private_key":"-----BEGIN PRIVATE KEY-----\n…\n-----END PRIVATE KEY-----","subscription_key_id":"ABC123DEFG","subscription_key_issuer":"57246542-96fe-1a63-e053-0824d011072a"}}'

Responses

  • 200: The app. Returns App.
  • 400: The request is invalid. Returns V2Error.
  • 401: No API key, or an unknown one. Returns V2Error.
  • 403: The key lacks a permission, or a public key was used. Returns V2Error.
  • 404: Not found in this project (another project's ids also answer 404). Returns V2Error.

Delete an app#

DELETE /v2/projects/{project_id}/apps/{app_id} · Auth: secret key or dashboard session · Permissions: project_configuration:apps:read_write

Deletes the app and its products. Purchase history stays.

Path parameters

Name Type Required Description
project_id string yes Project id (proj...).
app_id string yes App id (app...).

Example request

Shell
curl -s -X DELETE "$REVENUEDOT_URL/v2/projects/$PROJECT_ID/apps/$APP_ID" -H "Authorization: Bearer $SECRET_KEY"

Responses

  • 200: Deleted. Returns Deleted.
  • 401: No API key, or an unknown one. Returns V2Error.
  • 403: The key lacks a permission, or a public key was used. Returns V2Error.
  • 404: Not found in this project (another project's ids also answer 404). Returns V2Error.

Example 200 response:

JSON
{
  "object": "app",
  "id": "…",
  "deleted_at": 1790801342625
}

Get an app's public SDK key#

GET /v2/projects/{project_id}/apps/{app_id}/public_api_keys · Auth: secret key or dashboard session · Permissions: project_configuration:apps:read

Path parameters

Name Type Required Description
project_id string yes Project id (proj...).
app_id string yes App id (app...).

Example request

Shell
curl -s "$REVENUEDOT_URL/v2/projects/$PROJECT_ID/apps/$APP_ID/public_api_keys" -H "Authorization: Bearer $SECRET_KEY"

Responses

  • 200: One key. Returns a list of PublicApiKey.
  • 401: No API key, or an unknown one. Returns V2Error.
  • 403: The key lacks a permission, or a public key was used. Returns V2Error.
  • 404: Not found in this project (another project's ids also answer 404). Returns V2Error.

Example 200 response:

JSON
{
  "object": "list",
  "items": [
    {
      "object": "public_api_key",
      "id": "pk_appvnrm0a5h",
      "key": "test_ea5120a23e7b9626f8eff225a627762c",
      "environment": "sandbox",
      "app_id": "appvnrm0a5h",
      "created_at": 1790800900758
    }
  ],
  "next_page": null,
  "url": "/v2/projects/proj18pzzkao/apps/appvnrm0a5h/public_api_keys"
}

Products#

Store products.

List products#

GET /v2/projects/{project_id}/products · Auth: secret key or dashboard session · Permissions: project_configuration:products:read

Path parameters

Name Type Required Description
project_id string yes Project id (proj...).

Query parameters

Name Type Required Description
app_id string no Only this app's products.
expand array of items.app, items.indicative_price no items.app embeds each product's app. items.indicative_price adds each product's Test Store price.
limit integer no Page size. Values outside 1-100 are clamped, not rejected.
starting_after string no Id of the last item of the previous page. Use next_page instead of building it.

Example request

Shell
curl -s "$REVENUEDOT_URL/v2/projects/$PROJECT_ID/products" -H "Authorization: Bearer $SECRET_KEY"

Responses

  • 200: A page of results. Returns a list of Product.
  • 401: No API key, or an unknown one. Returns V2Error.
  • 403: The key lacks a permission, or a public key was used. Returns V2Error.
  • 404: Not found in this project (another project's ids also answer 404). Returns V2Error.

Create a product#

POST /v2/projects/{project_id}/products · Auth: secret key or dashboard session · Permissions: project_configuration:products:read_write

store_identifier is the store's product id. For Google Play subscriptions use subscriptionId:basePlanId. Set subscription.duration (ISO 8601, for example P1M): the Test Store uses it as the period, and MRR uses it for every store. test_store_price sets what the SDK shows for a Test Store product.

Path parameters

Name Type Required Description
project_id string yes Project id (proj...).

Query parameters

Name Type Required Description
expand array of indicative_price no indicative_price adds the Test Store price in RevenueCat's IndicativePrice shape (null for other stores and for products without a price).

Request body (application/json)

Field Type Required Description
store_identifier string yes
app_id string yes
type subscription, one_time, consumable, non_consumable, non_renewing_subscription yes
display_name string or null no
title string or null no Alias of display_name.
price_identifier string or null no Accepted and ignored.
subscription object or null no
subscription.duration string or null no ISO 8601 period such as P1W, P1M, P1Y or P3D.
test_store_price object or null no RevenueDot extension. The Test Store price the SDK shows for this product (Test Store products only). Null clears it. Read it back with expand=indicative_price.
test_store_price.amount_micros integer yes Price in micros: 9.99 is 9990000.
test_store_price.currency string yes ISO 4217 code such as USD or EUR.

Example request

Shell
curl -s -X POST "$REVENUEDOT_URL/v2/projects/$PROJECT_ID/products" -H "Authorization: Bearer $SECRET_KEY" \
  -H "Content-Type: application/json" -d '{"store_identifier":"pro_monthly","app_id":"appvnrm0a5h","type":"subscription","display_name":"Pro monthly","subscription":{"duration":"P1M"}}'

Responses

  • 201: The product. Returns Product.
  • 400: The request is invalid. Returns V2Error.
  • 401: No API key, or an unknown one. Returns V2Error.
  • 403: The key lacks a permission, or a public key was used. Returns V2Error.
  • 404: Not found in this project (another project's ids also answer 404). Returns V2Error.
  • 409: It already exists, or it conflicts with another object. Returns V2Error.

Example 201 response:

JSON
{
  "object": "product",
  "id": "prode0zhpfisko",
  "store_identifier": "pro_monthly",
  "type": "subscription",
  "state": "active",
  "subscription": {
    "duration": "P1M",
    "grace_period_duration": null,
    "trial_duration": null
  },
  "created_at": 1790800900948,
  "app_id": "appvnrm0a5h",
  "display_name": "Pro monthly"
}

Get a product#

GET /v2/projects/{project_id}/products/{product_id} · Auth: secret key or dashboard session · Permissions: project_configuration:products:read

Path parameters

Name Type Required Description
project_id string yes Project id (proj...).
product_id string yes Product id (prod...).

Query parameters

Name Type Required Description
expand array of app, indicative_price no app embeds the app. indicative_price adds the Test Store price in RevenueCat's IndicativePrice shape (null for other stores and for products without a price).

Example request

Shell
curl -s "$REVENUEDOT_URL/v2/projects/$PROJECT_ID/products/$PRODUCT_ID" -H "Authorization: Bearer $SECRET_KEY"

Responses

  • 200: The product. Returns Product.
  • 401: No API key, or an unknown one. Returns V2Error.
  • 403: The key lacks a permission, or a public key was used. Returns V2Error.
  • 404: Not found in this project (another project's ids also answer 404). Returns V2Error.

Example 200 response:

JSON
{
  "object": "product",
  "id": "prode0zhpfisko",
  "store_identifier": "pro_monthly",
  "type": "subscription",
  "state": "active",
  "subscription": {
    "duration": "P1M",
    "grace_period_duration": null,
    "trial_duration": null
  },
  "created_at": 1790800900948,
  "app_id": "appvnrm0a5h",
  "display_name": "Pro monthly"
}

Update a product#

POST /v2/projects/{project_id}/products/{product_id} · Auth: secret key or dashboard session · Permissions: project_configuration:products:read_write

RevenueDot also lets you correct type and subscription.duration (null clears it), and set or clear test_store_price.

Path parameters

Name Type Required Description
project_id string yes Project id (proj...).
product_id string yes Product id.

Query parameters

Name Type Required Description
expand array of app, indicative_price no indicative_price adds the Test Store price in RevenueCat's IndicativePrice shape (null for other stores and for products without a price).

Request body (application/json)

Field Type Required Description
display_name string no
type subscription, one_time, consumable, non_consumable, non_renewing_subscription no
subscription object no
subscription.duration string or null no
test_store_price object or null no RevenueDot extension. The Test Store price the SDK shows for this product (Test Store products only). Null clears it. Read it back with expand=indicative_price.
test_store_price.amount_micros integer yes Price in micros: 9.99 is 9990000.
test_store_price.currency string yes ISO 4217 code such as USD or EUR.

Example request

Shell
curl -s -X POST "$REVENUEDOT_URL/v2/projects/$PROJECT_ID/products/$PRODUCT_ID" -H "Authorization: Bearer $SECRET_KEY" \
  -H "Content-Type: application/json" -d '{"display_name":"Pro (monthly)","test_store_price":{"amount_micros":9990000,"currency":"USD"}}'

Responses

  • 200: The product. Returns Product.
  • 400: The request is invalid. Returns V2Error.
  • 401: No API key, or an unknown one. Returns V2Error.
  • 403: The key lacks a permission, or a public key was used. Returns V2Error.
  • 404: Not found in this project (another project's ids also answer 404). Returns V2Error.

Delete a product#

DELETE /v2/projects/{project_id}/products/{product_id} · Auth: secret key or dashboard session · Permissions: project_configuration:products:read_write

Detaches it from entitlements and packages. Purchase history keeps the store id.

Path parameters

Name Type Required Description
project_id string yes Project id (proj...).
product_id string yes Product id.

Example request

Shell
curl -s -X DELETE "$REVENUEDOT_URL/v2/projects/$PROJECT_ID/products/$PRODUCT_ID" -H "Authorization: Bearer $SECRET_KEY"

Responses

  • 200: Deleted. Returns Deleted.
  • 401: No API key, or an unknown one. Returns V2Error.
  • 403: The key lacks a permission, or a public key was used. Returns V2Error.
  • 404: Not found in this project (another project's ids also answer 404). Returns V2Error.

Example 200 response:

JSON
{
  "object": "product",
  "id": "…",
  "deleted_at": 1790801342625
}

Archive a product#

POST /v2/projects/{project_id}/products/{product_id}/actions/archive · Auth: secret key or dashboard session · Permissions: project_configuration:products:read_write

Path parameters

Name Type Required Description
project_id string yes Project id (proj...).
product_id string yes Product id.

Example request

Shell
curl -s -X POST "$REVENUEDOT_URL/v2/projects/$PROJECT_ID/products/$PRODUCT_ID/actions/archive" -H "Authorization: Bearer $SECRET_KEY"

Responses

  • 200: The archived product. Returns Product.
  • 401: No API key, or an unknown one. Returns V2Error.
  • 403: The key lacks a permission, or a public key was used. Returns V2Error.
  • 404: Not found in this project (another project's ids also answer 404). Returns V2Error.

Unarchive a product#

POST /v2/projects/{project_id}/products/{product_id}/actions/unarchive · Auth: secret key or dashboard session · Permissions: project_configuration:products:read_write

Path parameters

Name Type Required Description
project_id string yes Project id (proj...).
product_id string yes Product id.

Example request

Shell
curl -s -X POST "$REVENUEDOT_URL/v2/projects/$PROJECT_ID/products/$PRODUCT_ID/actions/unarchive" -H "Authorization: Bearer $SECRET_KEY"

Responses

  • 200: The product. Returns Product.
  • 401: No API key, or an unknown one. Returns V2Error.
  • 403: The key lacks a permission, or a public key was used. Returns V2Error.
  • 404: Not found in this project (another project's ids also answer 404). Returns V2Error.

Entitlements#

The access your app checks, unlocked by products.

List entitlements#

GET /v2/projects/{project_id}/entitlements · Auth: secret key or dashboard session · Permissions: project_configuration:entitlements:read

Path parameters

Name Type Required Description
project_id string yes Project id (proj...).

Query parameters

Name Type Required Description
expand array of items.product no items.product embeds the attached products.
limit integer no Page size. Values outside 1-100 are clamped, not rejected.
starting_after string no Id of the last item of the previous page. Use next_page instead of building it.

Example request

Shell
curl -s "$REVENUEDOT_URL/v2/projects/$PROJECT_ID/entitlements" -H "Authorization: Bearer $SECRET_KEY"

Responses

  • 200: A page of results. Returns a list of Entitlement.
  • 401: No API key, or an unknown one. Returns V2Error.
  • 403: The key lacks a permission, or a public key was used. Returns V2Error.
  • 404: Not found in this project (another project's ids also answer 404). Returns V2Error.

Create an entitlement#

POST /v2/projects/{project_id}/entitlements · Auth: secret key or dashboard session · Permissions: project_configuration:entitlements:read_write

Path parameters

Name Type Required Description
project_id string yes Project id (proj...).

Request body (application/json)

Field Type Required Description
lookup_key string yes What apps check, for example pro.
display_name string yes

Example request

Shell
curl -s -X POST "$REVENUEDOT_URL/v2/projects/$PROJECT_ID/entitlements" -H "Authorization: Bearer $SECRET_KEY" \
  -H "Content-Type: application/json" -d '{"lookup_key":"pro","display_name":"Pro access"}'

Responses

  • 201: The entitlement. Returns Entitlement.
  • 400: The request is invalid. Returns V2Error.
  • 401: No API key, or an unknown one. Returns V2Error.
  • 403: The key lacks a permission, or a public key was used. Returns V2Error.
  • 404: Not found in this project (another project's ids also answer 404). Returns V2Error.
  • 409: It already exists, or it conflicts with another object. Returns V2Error.

Example 201 response:

JSON
{
  "object": "entitlement",
  "id": "entl1v0bp6r0qs",
  "project_id": "proj18pzzkao",
  "lookup_key": "pro",
  "display_name": "Pro access",
  "created_at": 1790800901115,
  "state": "active"
}

Get an entitlement#

GET /v2/projects/{project_id}/entitlements/{entitlement_id} · Auth: secret key or dashboard session · Permissions: project_configuration:entitlements:read

Path parameters

Name Type Required Description
project_id string yes Project id (proj...).
entitlement_id string yes Entitlement id (entl...).

Query parameters

Name Type Required Description
expand array of product no product embeds the attached products.

Example request

Shell
curl -s "$REVENUEDOT_URL/v2/projects/$PROJECT_ID/entitlements/$ENTITLEMENT_ID" -H "Authorization: Bearer $SECRET_KEY"

Responses

  • 200: The entitlement. Returns Entitlement.
  • 401: No API key, or an unknown one. Returns V2Error.
  • 403: The key lacks a permission, or a public key was used. Returns V2Error.
  • 404: Not found in this project (another project's ids also answer 404). Returns V2Error.

Example 200 response:

JSON
{
  "object": "entitlement",
  "id": "entl1v0bp6r0qs",
  "project_id": "proj18pzzkao",
  "lookup_key": "pro",
  "display_name": "Pro access",
  "created_at": 1790800901115,
  "state": "active"
}

Rename an entitlement#

POST /v2/projects/{project_id}/entitlements/{entitlement_id} · Auth: secret key or dashboard session · Permissions: project_configuration:entitlements:read_write

Path parameters

Name Type Required Description
project_id string yes Project id (proj...).
entitlement_id string yes Entitlement id.

Request body (application/json)

Field Type Required Description
display_name string yes

Example request

Shell
curl -s -X POST "$REVENUEDOT_URL/v2/projects/$PROJECT_ID/entitlements/$ENTITLEMENT_ID" -H "Authorization: Bearer $SECRET_KEY"

Responses

  • 200: The entitlement. Returns Entitlement.
  • 400: The request is invalid. Returns V2Error.
  • 401: No API key, or an unknown one. Returns V2Error.
  • 403: The key lacks a permission, or a public key was used. Returns V2Error.
  • 404: Not found in this project (another project's ids also answer 404). Returns V2Error.

Delete an entitlement#

DELETE /v2/projects/{project_id}/entitlements/{entitlement_id} · Auth: secret key or dashboard session · Permissions: project_configuration:entitlements:read_write

Path parameters

Name Type Required Description
project_id string yes Project id (proj...).
entitlement_id string yes Entitlement id.

Example request

Shell
curl -s -X DELETE "$REVENUEDOT_URL/v2/projects/$PROJECT_ID/entitlements/$ENTITLEMENT_ID" -H "Authorization: Bearer $SECRET_KEY"

Responses

  • 200: Deleted. Returns Deleted.
  • 401: No API key, or an unknown one. Returns V2Error.
  • 403: The key lacks a permission, or a public key was used. Returns V2Error.
  • 404: Not found in this project (another project's ids also answer 404). Returns V2Error.

Example 200 response:

JSON
{
  "object": "entitlement",
  "id": "…",
  "deleted_at": 1790801342625
}

Archive an entitlement#

POST /v2/projects/{project_id}/entitlements/{entitlement_id}/actions/archive · Auth: secret key or dashboard session · Permissions: project_configuration:entitlements:read_write

Path parameters

Name Type Required Description
project_id string yes Project id (proj...).
entitlement_id string yes Entitlement id.

Example request

Shell
curl -s -X POST "$REVENUEDOT_URL/v2/projects/$PROJECT_ID/entitlements/$ENTITLEMENT_ID/actions/archive" -H "Authorization: Bearer $SECRET_KEY"

Responses

  • 200: The archived entitlement. Returns Entitlement.
  • 401: No API key, or an unknown one. Returns V2Error.
  • 403: The key lacks a permission, or a public key was used. Returns V2Error.
  • 404: Not found in this project (another project's ids also answer 404). Returns V2Error.

Unarchive an entitlement#

POST /v2/projects/{project_id}/entitlements/{entitlement_id}/actions/unarchive · Auth: secret key or dashboard session · Permissions: project_configuration:entitlements:read_write

Path parameters

Name Type Required Description
project_id string yes Project id (proj...).
entitlement_id string yes Entitlement id.

Example request

Shell
curl -s -X POST "$REVENUEDOT_URL/v2/projects/$PROJECT_ID/entitlements/$ENTITLEMENT_ID/actions/unarchive" -H "Authorization: Bearer $SECRET_KEY"

Responses

  • 200: The entitlement. Returns Entitlement.
  • 401: No API key, or an unknown one. Returns V2Error.
  • 403: The key lacks a permission, or a public key was used. Returns V2Error.
  • 404: Not found in this project (another project's ids also answer 404). Returns V2Error.

List an entitlement's products#

GET /v2/projects/{project_id}/entitlements/{entitlement_id}/products · Auth: secret key or dashboard session · Permissions: project_configuration:entitlements:read

Path parameters

Name Type Required Description
project_id string yes Project id (proj...).
entitlement_id string yes Entitlement id.

Query parameters

Name Type Required Description
limit integer no Page size. Values outside 1-100 are clamped, not rejected.
starting_after string no Id of the last item of the previous page. Use next_page instead of building it.

Example request

Shell
curl -s "$REVENUEDOT_URL/v2/projects/$PROJECT_ID/entitlements/$ENTITLEMENT_ID/products" -H "Authorization: Bearer $SECRET_KEY"

Responses

  • 200: A page of results. Returns a list of Product.
  • 401: No API key, or an unknown one. Returns V2Error.
  • 403: The key lacks a permission, or a public key was used. Returns V2Error.
  • 404: Not found in this project (another project's ids also answer 404). Returns V2Error.

Attach products to an entitlement#

POST /v2/projects/{project_id}/entitlements/{entitlement_id}/actions/attach_products · Auth: secret key or dashboard session · Permissions: project_configuration:entitlements:read_write

Any of these products unlocks the entitlement. Every id must belong to the project, or nothing changes.

Path parameters

Name Type Required Description
project_id string yes Project id (proj...).
entitlement_id string yes Entitlement id.

Request body (application/json)

Field Type Required Description
product_ids array of string yes

Example request

Shell
curl -s -X POST "$REVENUEDOT_URL/v2/projects/$PROJECT_ID/entitlements/$ENTITLEMENT_ID/actions/attach_products" -H "Authorization: Bearer $SECRET_KEY" \
  -H "Content-Type: application/json" -d '{"product_ids":["prode0zhpfisko","prodz2c0dt6z9x"]}'

Responses

  • 200: The entitlement with its products. Returns Entitlement.
  • 400: The request is invalid. Returns V2Error.
  • 401: No API key, or an unknown one. Returns V2Error.
  • 403: The key lacks a permission, or a public key was used. Returns V2Error.
  • 404: Not found in this project (another project's ids also answer 404). Returns V2Error.

Detach products from an entitlement#

POST /v2/projects/{project_id}/entitlements/{entitlement_id}/actions/detach_products · Auth: secret key or dashboard session · Permissions: project_configuration:entitlements:read_write

Path parameters

Name Type Required Description
project_id string yes Project id (proj...).
entitlement_id string yes Entitlement id.

Request body (application/json)

Field Type Required Description
product_ids array of string yes

Example request

Shell
curl -s -X POST "$REVENUEDOT_URL/v2/projects/$PROJECT_ID/entitlements/$ENTITLEMENT_ID/actions/detach_products" -H "Authorization: Bearer $SECRET_KEY"

Responses

  • 200: The entitlement with its products. Returns Entitlement.
  • 400: The request is invalid. Returns V2Error.
  • 401: No API key, or an unknown one. Returns V2Error.
  • 403: The key lacks a permission, or a public key was used. Returns V2Error.
  • 404: Not found in this project (another project's ids also answer 404). Returns V2Error.

Offerings#

Groups of packages the paywall shows.

List offerings#

GET /v2/projects/{project_id}/offerings · Auth: secret key or dashboard session · Permissions: project_configuration:offerings:read

Path parameters

Name Type Required Description
project_id string yes Project id (proj...).

Query parameters

Name Type Required Description
expand array of items.package, items.package.product no Embed packages, and their products.
limit integer no Page size. Values outside 1-100 are clamped, not rejected.
starting_after string no Id of the last item of the previous page. Use next_page instead of building it.

Example request

Shell
curl -s "$REVENUEDOT_URL/v2/projects/$PROJECT_ID/offerings" -H "Authorization: Bearer $SECRET_KEY"

Responses

  • 200: A page of results. Returns a list of Offering.
  • 401: No API key, or an unknown one. Returns V2Error.
  • 403: The key lacks a permission, or a public key was used. Returns V2Error.
  • 404: Not found in this project (another project's ids also answer 404). Returns V2Error.

Create an offering#

POST /v2/projects/{project_id}/offerings · Auth: secret key or dashboard session · Permissions: project_configuration:offerings:read_write

The project's first offering becomes current.

Path parameters

Name Type Required Description
project_id string yes Project id (proj...).

Request body (application/json)

Field Type Required Description
lookup_key string yes
display_name string yes
metadata object or null no

Example request

Shell
curl -s -X POST "$REVENUEDOT_URL/v2/projects/$PROJECT_ID/offerings" -H "Authorization: Bearer $SECRET_KEY" \
  -H "Content-Type: application/json" -d '{"lookup_key":"default","display_name":"Standard plans"}'

Responses

  • 201: The offering. Returns Offering.
  • 400: The request is invalid. Returns V2Error.
  • 401: No API key, or an unknown one. Returns V2Error.
  • 403: The key lacks a permission, or a public key was used. Returns V2Error.
  • 404: Not found in this project (another project's ids also answer 404). Returns V2Error.
  • 409: It already exists, or it conflicts with another object. Returns V2Error.

Get an offering#

GET /v2/projects/{project_id}/offerings/{offering_id} · Auth: secret key or dashboard session · Permissions: project_configuration:offerings:read

Path parameters

Name Type Required Description
project_id string yes Project id (proj...).
offering_id string yes Offering id (ofrng...).

Query parameters

Name Type Required Description
expand array of package, package.product no Embed packages, and their products.

Example request

Shell
curl -s "$REVENUEDOT_URL/v2/projects/$PROJECT_ID/offerings/$OFFERING_ID" -H "Authorization: Bearer $SECRET_KEY"

Responses

  • 200: The offering. Returns Offering.
  • 401: No API key, or an unknown one. Returns V2Error.
  • 403: The key lacks a permission, or a public key was used. Returns V2Error.
  • 404: Not found in this project (another project's ids also answer 404). Returns V2Error.

Update an offering or make it current#

POST /v2/projects/{project_id}/offerings/{offering_id} · Auth: secret key or dashboard session · Permissions: project_configuration:offerings:read_write

is_current: true makes it the only current offering. An archived offering cannot be made current (422).

Path parameters

Name Type Required Description
project_id string yes Project id (proj...).
offering_id string yes Offering id.

Request body (application/json)

Field Type Required Description
display_name string no
is_current boolean no
metadata object or null no

Example request

Shell
curl -s -X POST "$REVENUEDOT_URL/v2/projects/$PROJECT_ID/offerings/$OFFERING_ID" -H "Authorization: Bearer $SECRET_KEY" \
  -H "Content-Type: application/json" -d '{"is_current":true}'

Responses

  • 200: The offering. Returns Offering.
  • 400: The request is invalid. Returns V2Error.
  • 401: No API key, or an unknown one. Returns V2Error.
  • 403: The key lacks a permission, or a public key was used. Returns V2Error.
  • 404: Not found in this project (another project's ids also answer 404). Returns V2Error.
  • 422: The request is valid but cannot be done in this state or for this store. Returns V2Error.

Delete an offering#

DELETE /v2/projects/{project_id}/offerings/{offering_id} · Auth: secret key or dashboard session · Permissions: project_configuration:offerings:read_write

Deletes its packages and clears customer overrides that point to it.

Path parameters

Name Type Required Description
project_id string yes Project id (proj...).
offering_id string yes Offering id.

Example request

Shell
curl -s -X DELETE "$REVENUEDOT_URL/v2/projects/$PROJECT_ID/offerings/$OFFERING_ID" -H "Authorization: Bearer $SECRET_KEY"

Responses

  • 200: Deleted. Returns Deleted.
  • 401: No API key, or an unknown one. Returns V2Error.
  • 403: The key lacks a permission, or a public key was used. Returns V2Error.
  • 404: Not found in this project (another project's ids also answer 404). Returns V2Error.

Example 200 response:

JSON
{
  "object": "offering",
  "id": "…",
  "deleted_at": 1790801342625
}

Archive an offering#

POST /v2/projects/{project_id}/offerings/{offering_id}/actions/archive · Auth: secret key or dashboard session · Permissions: project_configuration:offerings:read_write

Path parameters

Name Type Required Description
project_id string yes Project id (proj...).
offering_id string yes Offering id.

Example request

Shell
curl -s -X POST "$REVENUEDOT_URL/v2/projects/$PROJECT_ID/offerings/$OFFERING_ID/actions/archive" -H "Authorization: Bearer $SECRET_KEY"

Responses

  • 200: The archived offering. Returns Offering.
  • 401: No API key, or an unknown one. Returns V2Error.
  • 403: The key lacks a permission, or a public key was used. Returns V2Error.
  • 404: Not found in this project (another project's ids also answer 404). Returns V2Error.
  • 422: The request is valid but cannot be done in this state or for this store. Returns V2Error.

Unarchive an offering#

POST /v2/projects/{project_id}/offerings/{offering_id}/actions/unarchive · Auth: secret key or dashboard session · Permissions: project_configuration:offerings:read_write

Path parameters

Name Type Required Description
project_id string yes Project id (proj...).
offering_id string yes Offering id.

Request body (application/json)

Field Type Required Description
unarchive_referenced_entities boolean no Also unarchive the products in its packages.

Example request

Shell
curl -s -X POST "$REVENUEDOT_URL/v2/projects/$PROJECT_ID/offerings/$OFFERING_ID/actions/unarchive" -H "Authorization: Bearer $SECRET_KEY"

Responses

  • 200: The offering. Returns Offering.
  • 401: No API key, or an unknown one. Returns V2Error.
  • 403: The key lacks a permission, or a public key was used. Returns V2Error.
  • 404: Not found in this project (another project's ids also answer 404). Returns V2Error.

Packages#

One choice on the paywall, with one product per app.

List an offering's packages#

GET /v2/projects/{project_id}/offerings/{offering_id}/packages · Auth: secret key or dashboard session · Permissions: project_configuration:packages:read

Ordered by position, then creation: the order the SDK shows them in.

Path parameters

Name Type Required Description
project_id string yes Project id (proj...).
offering_id string yes Offering id.

Query parameters

Name Type Required Description
expand array of items.product no Embed products.
limit integer no Page size. Values outside 1-100 are clamped, not rejected.
starting_after string no Id of the last item of the previous page. Use next_page instead of building it.

Example request

Shell
curl -s "$REVENUEDOT_URL/v2/projects/$PROJECT_ID/offerings/$OFFERING_ID/packages" -H "Authorization: Bearer $SECRET_KEY"

Responses

  • 200: A page of results. Returns a list of Package.
  • 401: No API key, or an unknown one. Returns V2Error.
  • 403: The key lacks a permission, or a public key was used. Returns V2Error.
  • 404: Not found in this project (another project's ids also answer 404). Returns V2Error.

Create a package#

POST /v2/projects/{project_id}/offerings/{offering_id}/packages · Auth: secret key or dashboard session · Permissions: project_configuration:packages:read_write

Use the standard lookup keys ($rc_monthly, $rc_annual, $rc_weekly, $rc_lifetime ...) so the SDK's convenience accessors work. Without position, the package goes last.

Path parameters

Name Type Required Description
project_id string yes Project id (proj...).
offering_id string yes Offering id.

Request body (application/json)

Field Type Required Description
lookup_key string yes
display_name string yes
position integer no

Example request

Shell
curl -s -X POST "$REVENUEDOT_URL/v2/projects/$PROJECT_ID/offerings/$OFFERING_ID/packages" -H "Authorization: Bearer $SECRET_KEY" \
  -H "Content-Type: application/json" -d '{"lookup_key":"$rc_monthly","display_name":"Monthly","position":0}'

Responses

  • 201: The package. Returns Package.
  • 400: The request is invalid. Returns V2Error.
  • 401: No API key, or an unknown one. Returns V2Error.
  • 403: The key lacks a permission, or a public key was used. Returns V2Error.
  • 404: Not found in this project (another project's ids also answer 404). Returns V2Error.
  • 409: It already exists, or it conflicts with another object. Returns V2Error.

Get a package#

GET /v2/projects/{project_id}/packages/{package_id} · Auth: secret key or dashboard session · Permissions: project_configuration:packages:read

Path parameters

Name Type Required Description
project_id string yes Project id (proj...).
package_id string yes Package id (pkge...).

Query parameters

Name Type Required Description
expand array of product no Embed products.

Example request

Shell
curl -s "$REVENUEDOT_URL/v2/projects/$PROJECT_ID/packages/$PACKAGE_ID" -H "Authorization: Bearer $SECRET_KEY"

Responses

  • 200: The package. Returns Package.
  • 401: No API key, or an unknown one. Returns V2Error.
  • 403: The key lacks a permission, or a public key was used. Returns V2Error.
  • 404: Not found in this project (another project's ids also answer 404). Returns V2Error.

Update a package#

POST /v2/projects/{project_id}/packages/{package_id} · Auth: secret key or dashboard session · Permissions: project_configuration:packages:read_write

Path parameters

Name Type Required Description
project_id string yes Project id (proj...).
package_id string yes Package id.

Request body (application/json)

Field Type Required Description
display_name string no
position integer no

Example request

Shell
curl -s -X POST "$REVENUEDOT_URL/v2/projects/$PROJECT_ID/packages/$PACKAGE_ID" -H "Authorization: Bearer $SECRET_KEY"

Responses

  • 200: The package. Returns Package.
  • 400: The request is invalid. Returns V2Error.
  • 401: No API key, or an unknown one. Returns V2Error.
  • 403: The key lacks a permission, or a public key was used. Returns V2Error.
  • 404: Not found in this project (another project's ids also answer 404). Returns V2Error.

Delete a package#

DELETE /v2/projects/{project_id}/packages/{package_id} · Auth: secret key or dashboard session · Permissions: project_configuration:packages:read_write

Path parameters

Name Type Required Description
project_id string yes Project id (proj...).
package_id string yes Package id.

Example request

Shell
curl -s -X DELETE "$REVENUEDOT_URL/v2/projects/$PROJECT_ID/packages/$PACKAGE_ID" -H "Authorization: Bearer $SECRET_KEY"

Responses

  • 200: Deleted. Returns Deleted.
  • 401: No API key, or an unknown one. Returns V2Error.
  • 403: The key lacks a permission, or a public key was used. Returns V2Error.
  • 404: Not found in this project (another project's ids also answer 404). Returns V2Error.

Example 200 response:

JSON
{
  "object": "package",
  "id": "…",
  "deleted_at": 1790801342625
}

List a package's products#

GET /v2/projects/{project_id}/packages/{package_id}/products · Auth: secret key or dashboard session · Permissions: project_configuration:packages:read

Path parameters

Name Type Required Description
project_id string yes Project id (proj...).
package_id string yes Package id.

Query parameters

Name Type Required Description
limit integer no Page size. Values outside 1-100 are clamped, not rejected.
starting_after string no Id of the last item of the previous page. Use next_page instead of building it.

Example request

Shell
curl -s "$REVENUEDOT_URL/v2/projects/$PROJECT_ID/packages/$PACKAGE_ID/products" -H "Authorization: Bearer $SECRET_KEY"

Responses

  • 200: A page of results. Returns a list of PackageProduct.
  • 401: No API key, or an unknown one. Returns V2Error.
  • 403: The key lacks a permission, or a public key was used. Returns V2Error.
  • 404: Not found in this project (another project's ids also answer 404). Returns V2Error.

Attach products to a package#

POST /v2/projects/{project_id}/packages/{package_id}/actions/attach_products · Auth: secret key or dashboard session · Permissions: project_configuration:packages:read_write

One product per app, so each app's SDK finds its product. Two products of the same app can share a package only with non-overlapping eligibility_criteria (409 otherwise).

Path parameters

Name Type Required Description
project_id string yes Project id (proj...).
package_id string yes Package id.

Request body (application/json)

Field Type Required Description
products array of object yes
products[].product_id string yes
products[].eligibility_criteria all, google_sdk_lt_6, google_sdk_ge_6 yes

Example request

Shell
curl -s -X POST "$REVENUEDOT_URL/v2/projects/$PROJECT_ID/packages/$PACKAGE_ID/actions/attach_products" -H "Authorization: Bearer $SECRET_KEY" \
  -H "Content-Type: application/json" -d '{"products":[{"product_id":"prode0zhpfisko","eligibility_criteria":"all"}]}'

Responses

  • 200: The package with its products. Returns Package.
  • 400: The request is invalid. Returns V2Error.
  • 401: No API key, or an unknown one. Returns V2Error.
  • 403: The key lacks a permission, or a public key was used. Returns V2Error.
  • 404: Not found in this project (another project's ids also answer 404). Returns V2Error.
  • 409: It already exists, or it conflicts with another object. Returns V2Error.

Detach products from a package#

POST /v2/projects/{project_id}/packages/{package_id}/actions/detach_products · Auth: secret key or dashboard session · Permissions: project_configuration:packages:read_write

Path parameters

Name Type Required Description
project_id string yes Project id (proj...).
package_id string yes Package id.

Request body (application/json)

Field Type Required Description
product_ids array of string yes

Example request

Shell
curl -s -X POST "$REVENUEDOT_URL/v2/projects/$PROJECT_ID/packages/$PACKAGE_ID/actions/detach_products" -H "Authorization: Bearer $SECRET_KEY"

Responses

  • 200: The package with its products. Returns Package.
  • 400: The request is invalid. Returns V2Error.
  • 401: No API key, or an unknown one. Returns V2Error.
  • 403: The key lacks a permission, or a public key was used. Returns V2Error.
  • 404: Not found in this project (another project's ids also answer 404). Returns V2Error.

Customers#

Customers, their attributes, entitlements, subscriptions, purchases and events.

List or search customers#

GET /v2/projects/{project_id}/customers · Auth: secret key or dashboard session · Permissions: customer_information:customers:read

Newest first (by first seen).

Path parameters

Name Type Required Description
project_id string yes Project id (proj...).

Query parameters

Name Type Required Description
search string no Exact match on an app user id, the $email attribute (any case) or a store transaction id.
limit integer no Page size. Values outside 1-100 are clamped, not rejected.
starting_after string no Id of the last item of the previous page. Use next_page instead of building it.

Example request

Shell
curl -s "$REVENUEDOT_URL/v2/projects/$PROJECT_ID/customers" -H "Authorization: Bearer $SECRET_KEY"

Responses

  • 200: A page of results. Returns a list of Customer.
  • 400: The request is invalid. Returns V2Error.
  • 401: No API key, or an unknown one. Returns V2Error.
  • 403: The key lacks a permission, or a public key was used. Returns V2Error.
  • 404: Not found in this project (another project's ids also answer 404). Returns V2Error.

Create a customer#

POST /v2/projects/{project_id}/customers · Auth: secret key or dashboard session · Permissions: customer_information:customers:read_write

Path parameters

Name Type Required Description
project_id string yes Project id (proj...).

Request body (application/json)

Field Type Required Description
id string yes App user id.
attributes array of object no
attributes[].name string yes
attributes[].value string yes

Example request

Shell
curl -s -X POST "$REVENUEDOT_URL/v2/projects/$PROJECT_ID/customers" -H "Authorization: Bearer $SECRET_KEY" \
  -H "Content-Type: application/json" -d '{"id":"user_42","attributes":[{"name":"$email","value":"ana@example.com"}]}'

Responses

  • 201: The customer. Returns Customer.
  • 400: The request is invalid. Returns V2Error.
  • 401: No API key, or an unknown one. Returns V2Error.
  • 403: The key lacks a permission, or a public key was used. Returns V2Error.
  • 404: Not found in this project (another project's ids also answer 404). Returns V2Error.
  • 409: It already exists, or it conflicts with another object. Returns V2Error.

Get a customer#

GET /v2/projects/{project_id}/customers/{customer_id} · Auth: secret key or dashboard session · Permissions: customer_information:customers:read

Path parameters

Name Type Required Description
project_id string yes Project id (proj...).
customer_id string yes Any app user id of the customer.

Query parameters

Name Type Required Description
expand array of attributes no attributes embeds the customer's attributes.

Example request

Shell
curl -s "$REVENUEDOT_URL/v2/projects/$PROJECT_ID/customers/user_1" -H "Authorization: Bearer $SECRET_KEY"

Responses

  • 200: The customer. Returns Customer.
  • 401: No API key, or an unknown one. Returns V2Error.
  • 403: The key lacks a permission, or a public key was used. Returns V2Error.
  • 404: Not found in this project (another project's ids also answer 404). Returns V2Error.

Example 200 response:

JSON
{
  "object": "customer",
  "id": "user_1",
  "project_id": "proj18pzzkao",
  "first_seen_at": 1790800914012,
  "last_seen_at": 1790800914034,
  "last_seen_app_version": null,
  "last_seen_country": null,
  "last_seen_platform": null,
  "last_seen_platform_version": null,
  "active_entitlements": {
    "object": "list",
    "items": [
      {
        "object": "customer.active_entitlement",
        "entitlement_id": "entl1v0bp6r0qs",
        "expires_at": 1793392914000
      }
    ],
    "next_page": null,
    "url": "/v2/projects/proj18pzzkao/customers/user_1/active_entitlements"
  },
  "experiment": null
}

Delete a customer#

DELETE /v2/projects/{project_id}/customers/{customer_id} · Auth: secret key or dashboard session · Permissions: customer_information:customers:read_write

Deletes aliases, attributes, subscriptions, purchases, transactions and events. Cannot be undone.

Path parameters

Name Type Required Description
project_id string yes Project id (proj...).
customer_id string yes Any app user id of the customer.

Example request

Shell
curl -s -X DELETE "$REVENUEDOT_URL/v2/projects/$PROJECT_ID/customers/user_1" -H "Authorization: Bearer $SECRET_KEY"

Responses

  • 200: Deleted. Returns Deleted.
  • 401: No API key, or an unknown one. Returns V2Error.
  • 403: The key lacks a permission, or a public key was used. Returns V2Error.
  • 404: Not found in this project (another project's ids also answer 404). Returns V2Error.

Example 200 response:

JSON
{
  "object": "customer",
  "id": "…",
  "deleted_at": 1790801342625
}

List a customer's app user ids#

GET /v2/projects/{project_id}/customers/{customer_id}/aliases · Auth: secret key or dashboard session · Permissions: customer_information:customers:read

Path parameters

Name Type Required Description
project_id string yes Project id (proj...).
customer_id string yes Any app user id of the customer.

Query parameters

Name Type Required Description
limit integer no Page size. Values outside 1-100 are clamped, not rejected.
starting_after string no Id of the last item of the previous page. Use next_page instead of building it.

Example request

Shell
curl -s "$REVENUEDOT_URL/v2/projects/$PROJECT_ID/customers/user_1/aliases" -H "Authorization: Bearer $SECRET_KEY"

Responses

  • 200: A page of results. Returns a list of CustomerAlias.
  • 401: No API key, or an unknown one. Returns V2Error.
  • 403: The key lacks a permission, or a public key was used. Returns V2Error.
  • 404: Not found in this project (another project's ids also answer 404). Returns V2Error.

List a customer's attributes#

GET /v2/projects/{project_id}/customers/{customer_id}/attributes · Auth: secret key or dashboard session · Permissions: customer_information:customers:read

Path parameters

Name Type Required Description
project_id string yes Project id (proj...).
customer_id string yes Any app user id of the customer.

Query parameters

Name Type Required Description
limit integer no Page size. Values outside 1-100 are clamped, not rejected.
starting_after string no Id of the last item of the previous page. Use next_page instead of building it.

Example request

Shell
curl -s "$REVENUEDOT_URL/v2/projects/$PROJECT_ID/customers/user_1/attributes" -H "Authorization: Bearer $SECRET_KEY"

Responses

  • 200: A page of results. Returns a list of CustomerAttribute.
  • 401: No API key, or an unknown one. Returns V2Error.
  • 403: The key lacks a permission, or a public key was used. Returns V2Error.
  • 404: Not found in this project (another project's ids also answer 404). Returns V2Error.

Set a customer's attributes#

POST /v2/projects/{project_id}/customers/{customer_id}/attributes · Auth: secret key or dashboard session · Permissions: customer_information:customers:read_write

API writes always win over older SDK writes. A null value deletes the attribute.

Path parameters

Name Type Required Description
project_id string yes Project id (proj...).
customer_id string yes Any app user id of the customer.

Request body (application/json)

Field Type Required Description
attributes array of object yes
attributes[].name string yes
attributes[].value string or null yes

Example request

Shell
curl -s -X POST "$REVENUEDOT_URL/v2/projects/$PROJECT_ID/customers/user_1/attributes" -H "Authorization: Bearer $SECRET_KEY" \
  -H "Content-Type: application/json" -d '{"attributes":[{"name":"$displayName","value":"Ana"}]}'

Responses

  • 200: Every attribute of the customer. Returns a list of CustomerAttribute.
  • 400: The request is invalid. Returns V2Error.
  • 401: No API key, or an unknown one. Returns V2Error.
  • 403: The key lacks a permission, or a public key was used. Returns V2Error.
  • 404: Not found in this project (another project's ids also answer 404). Returns V2Error.

List a customer's active entitlements#

GET /v2/projects/{project_id}/customers/{customer_id}/active_entitlements · Auth: secret key or dashboard session · Permissions: customer_information:customers:read

Path parameters

Name Type Required Description
project_id string yes Project id (proj...).
customer_id string yes Any app user id of the customer.

Query parameters

Name Type Required Description
limit integer no Page size. Values outside 1-100 are clamped, not rejected.
starting_after string no Id of the last item of the previous page. Use next_page instead of building it.

Example request

Shell
curl -s "$REVENUEDOT_URL/v2/projects/$PROJECT_ID/customers/user_1/active_entitlements" -H "Authorization: Bearer $SECRET_KEY"

Responses

  • 200: A page of results. Returns a list of ActiveEntitlement.
  • 401: No API key, or an unknown one. Returns V2Error.
  • 403: The key lacks a permission, or a public key was used. Returns V2Error.
  • 404: Not found in this project (another project's ids also answer 404). Returns V2Error.

List a customer's subscriptions#

GET /v2/projects/{project_id}/customers/{customer_id}/subscriptions · Auth: secret key or dashboard session · Permissions: customer_information:subscriptions:read

Path parameters

Name Type Required Description
project_id string yes Project id (proj...).
customer_id string yes Any app user id of the customer.

Query parameters

Name Type Required Description
environment production, sandbox no Only this environment. Default: both.
limit integer no Page size. Values outside 1-100 are clamped, not rejected.
starting_after string no Id of the last item of the previous page. Use next_page instead of building it.

Example request

Shell
curl -s "$REVENUEDOT_URL/v2/projects/$PROJECT_ID/customers/user_1/subscriptions" -H "Authorization: Bearer $SECRET_KEY"

Responses

  • 200: A page of subscriptions. Returns a list of Subscription.
  • 400: The request is invalid. Returns V2Error.
  • 401: No API key, or an unknown one. Returns V2Error.
  • 403: The key lacks a permission, or a public key was used. Returns V2Error.
  • 404: Not found in this project (another project's ids also answer 404). Returns V2Error.

Example 200 response:

JSON
{
  "object": "list",
  "items": [
    {
      "object": "subscription",
      "id": "sub_k1u15wepvw0dfh25",
      "customer_id": "user_1",
      "original_customer_id": "user_1",
      "product_id": "prode0zhpfisko",
      "starts_at": 1790800914000,
      "current_period_starts_at": 1790800914000,
      "current_period_ends_at": 1793392914000,
      "ends_at": 1793392914000,
      "gives_access": true,
      "pending_payment": false,
      "auto_renewal_status": "will_renew",
      "status": "active",
      "total_revenue_in_usd": {
        "currency": "USD",
        "gross": 9.99,
        "commission": 0,
        "tax": 0,
        "proceeds": 9.99
      },
      "presented_offering_id": null,
      "entitlements": {
        "object": "list",
        "items": [
          {
            "object": "entitlement",
            "id": "entl1v0bp6r0qs",
            "project_id": "proj18pzzkao",
            "lookup_key": "pro",
            "display_name": "Pro access",
            "created_at": 1790800901115,
            "state": "active"
          }
        ],
        "next_page": null,
        "url": "/v2/projects/proj18pzzkao/subscriptions/sub_k1u15wepvw0dfh25/entitlements"
      },
      "environment": "sandbox",
      "store": "test_store",
      "store_subscription_identifier": "test_1790800914000_quickstart",
      "ownership": "purchased",
      "management_url": null
    }
  ],
  "next_page": null,
  "url": "/v2/projects/proj18pzzkao/customers/user_1/subscriptions"
}

List a customer's one-time purchases#

GET /v2/projects/{project_id}/customers/{customer_id}/purchases · Auth: secret key or dashboard session · Permissions: customer_information:purchases:read

Path parameters

Name Type Required Description
project_id string yes Project id (proj...).
customer_id string yes Any app user id of the customer.

Query parameters

Name Type Required Description
environment production, sandbox no Only this environment. Default: both.
limit integer no Page size. Values outside 1-100 are clamped, not rejected.
starting_after string no Id of the last item of the previous page. Use next_page instead of building it.

Example request

Shell
curl -s "$REVENUEDOT_URL/v2/projects/$PROJECT_ID/customers/user_1/purchases" -H "Authorization: Bearer $SECRET_KEY"

Responses

  • 200: A page of results. Returns a list of Purchase.
  • 400: The request is invalid. Returns V2Error.
  • 401: No API key, or an unknown one. Returns V2Error.
  • 403: The key lacks a permission, or a public key was used. Returns V2Error.
  • 404: Not found in this project (another project's ids also answer 404). Returns V2Error.

List a customer's events#

GET /v2/projects/{project_id}/customers/{customer_id}/events · Auth: secret key or dashboard session · Permissions: customer_information:customers:read

Newest first. body is the webhook event.

Path parameters

Name Type Required Description
project_id string yes Project id (proj...).
customer_id string yes Any app user id of the customer.

Query parameters

Name Type Required Description
environment production, sandbox no Only this environment. Default: both.
limit integer no Page size. Values outside 1-100 are clamped, not rejected.
starting_after string no Id of the last item of the previous page. Use next_page instead of building it.

Example request

Shell
curl -s "$REVENUEDOT_URL/v2/projects/$PROJECT_ID/customers/user_1/events" -H "Authorization: Bearer $SECRET_KEY"

Responses

  • 200: A page of results. Returns a list of CustomerEvent.
  • 400: The request is invalid. Returns V2Error.
  • 401: No API key, or an unknown one. Returns V2Error.
  • 403: The key lacks a permission, or a public key was used. Returns V2Error.
  • 404: Not found in this project (another project's ids also answer 404). Returns V2Error.

Grant an entitlement#

POST /v2/projects/{project_id}/customers/{customer_id}/actions/grant_entitlement · Auth: secret key or dashboard session · Permissions: customer_information:customers:read_write

Promotional access until expires_at. A grant ending within 2 hours of an existing grant for the same entitlement changes nothing.

Path parameters

Name Type Required Description
project_id string yes Project id (proj...).
customer_id string yes Any app user id of the customer.

Request body (application/json)

Field Type Required Description
entitlement_id string yes Entitlement id (entl...).
expires_at integer yes Epoch milliseconds, in the future.

Example request

Shell
curl -s -X POST "$REVENUEDOT_URL/v2/projects/$PROJECT_ID/customers/user_1/actions/grant_entitlement" -H "Authorization: Bearer $SECRET_KEY" \
  -H "Content-Type: application/json" -d '{"entitlement_id":"entl1v0bp6r0qs","expires_at":1830000000000}'

Responses

  • 201: The customer. Returns Customer.
  • 400: The request is invalid. Returns V2Error.
  • 401: No API key, or an unknown one. Returns V2Error.
  • 403: The key lacks a permission, or a public key was used. Returns V2Error.
  • 404: Not found in this project (another project's ids also answer 404). Returns V2Error.

Revoke a granted entitlement#

POST /v2/projects/{project_id}/customers/{customer_id}/actions/revoke_granted_entitlement · Auth: secret key or dashboard session · Permissions: customer_information:customers:read_write

Path parameters

Name Type Required Description
project_id string yes Project id (proj...).
customer_id string yes Any app user id of the customer.

Request body (application/json)

Field Type Required Description
entitlement_id string yes

Example request

Shell
curl -s -X POST "$REVENUEDOT_URL/v2/projects/$PROJECT_ID/customers/user_1/actions/revoke_granted_entitlement" -H "Authorization: Bearer $SECRET_KEY"

Responses

  • 200: The customer. Returns Customer.
  • 400: The request is invalid. Returns V2Error.
  • 401: No API key, or an unknown one. Returns V2Error.
  • 403: The key lacks a permission, or a public key was used. Returns V2Error.
  • 404: Not found in this project (another project's ids also answer 404). Returns V2Error.

Assign an offering to a customer#

POST /v2/projects/{project_id}/customers/{customer_id}/actions/assign_offering · Auth: secret key or dashboard session · Permissions: project_configuration:offerings:read, customer_information:customers:read_write

The customer sees this offering as current. null removes the override.

Path parameters

Name Type Required Description
project_id string yes Project id (proj...).
customer_id string yes Any app user id of the customer.

Request body (application/json)

Field Type Required Description
offering_id string or null yes Offering id (ofrng...) or null.

Example request

Shell
curl -s -X POST "$REVENUEDOT_URL/v2/projects/$PROJECT_ID/customers/user_1/actions/assign_offering" -H "Authorization: Bearer $SECRET_KEY" \
  -H "Content-Type: application/json" -d '{"offering_id":"ofrngjfr71v5awb"}'

Responses

  • 200: Done.
  • 400: The request is invalid. Returns V2Error.
  • 401: No API key, or an unknown one. Returns V2Error.
  • 403: The key lacks a permission, or a public key was used. Returns V2Error.
  • 404: Not found in this project (another project's ids also answer 404). Returns V2Error.

Example 200 response:

JSON
{}

Subscriptions#

Subscriptions across customers, and store actions on them.

Find subscriptions by store id#

GET /v2/projects/{project_id}/subscriptions · Auth: secret key or dashboard session · Permissions: customer_information:subscriptions:read

Path parameters

Name Type Required Description
project_id string yes Project id (proj...).

Query parameters

Name Type Required Description
store_subscription_identifier string yes Store transaction id, original transaction id or purchase token.

Example request

Shell
curl -s "$REVENUEDOT_URL/v2/projects/$PROJECT_ID/subscriptions" -H "Authorization: Bearer $SECRET_KEY"

Responses

  • 200: A page of results. Returns a list of Subscription.
  • 400: The request is invalid. Returns V2Error.
  • 401: No API key, or an unknown one. Returns V2Error.
  • 403: The key lacks a permission, or a public key was used. Returns V2Error.
  • 404: Not found in this project (another project's ids also answer 404). Returns V2Error.

Get a subscription#

GET /v2/projects/{project_id}/subscriptions/{subscription_id} · Auth: secret key or dashboard session · Permissions: customer_information:subscriptions:read

Path parameters

Name Type Required Description
project_id string yes Project id (proj...).
subscription_id string yes Subscription id (sub_...).

Example request

Shell
curl -s "$REVENUEDOT_URL/v2/projects/$PROJECT_ID/subscriptions/$SUBSCRIPTION_ID" -H "Authorization: Bearer $SECRET_KEY"

Responses

  • 200: The subscription. Returns Subscription.
  • 401: No API key, or an unknown one. Returns V2Error.
  • 403: The key lacks a permission, or a public key was used. Returns V2Error.
  • 404: Not found in this project (another project's ids also answer 404). Returns V2Error.

Example 200 response:

JSON
{
  "object": "subscription",
  "id": "sub_k1u15wepvw0dfh25",
  "customer_id": "user_1",
  "original_customer_id": "user_1",
  "product_id": "prode0zhpfisko",
  "starts_at": 1790800914000,
  "current_period_starts_at": 1790800914000,
  "current_period_ends_at": 1793392914000,
  "ends_at": 1793392914000,
  "gives_access": true,
  "pending_payment": false,
  "auto_renewal_status": "will_renew",
  "status": "active",
  "total_revenue_in_usd": {
    "currency": "USD",
    "gross": 9.99,
    "commission": 0,
    "tax": 0,
    "proceeds": 9.99
  },
  "presented_offering_id": null,
  "entitlements": {
    "object": "list",
    "items": [
      {
        "object": "entitlement",
        "id": "entl1v0bp6r0qs",
        "project_id": "proj18pzzkao",
        "lookup_key": "pro",
        "display_name": "Pro access",
        "created_at": 1790800901115,
        "state": "active"
      }
    ],
    "next_page": null,
    "url": "/v2/projects/proj18pzzkao/subscriptions/sub_k1u15wepvw0dfh25/entitlements"
  },
  "environment": "sandbox",
  "store": "test_store",
  "store_subscription_identifier": "test_1790800914000_quickstart",
  "ownership": "purchased",
  "management_url": null
}

List the entitlements a subscription unlocks#

GET /v2/projects/{project_id}/subscriptions/{subscription_id}/entitlements · Auth: secret key or dashboard session · Permissions: customer_information:subscriptions:read

Path parameters

Name Type Required Description
project_id string yes Project id (proj...).
subscription_id string yes Subscription id.

Query parameters

Name Type Required Description
limit integer no Page size. Values outside 1-100 are clamped, not rejected.
starting_after string no Id of the last item of the previous page. Use next_page instead of building it.

Example request

Shell
curl -s "$REVENUEDOT_URL/v2/projects/$PROJECT_ID/subscriptions/$SUBSCRIPTION_ID/entitlements" -H "Authorization: Bearer $SECRET_KEY"

Responses

  • 200: A page of results. Returns a list of Entitlement.
  • 401: No API key, or an unknown one. Returns V2Error.
  • 403: The key lacks a permission, or a public key was used. Returns V2Error.
  • 404: Not found in this project (another project's ids also answer 404). Returns V2Error.

List a subscription's payments#

GET /v2/projects/{project_id}/subscriptions/{subscription_id}/transactions · Auth: secret key or dashboard session · Permissions: customer_information:subscriptions:read

One item per paid store transaction of the subscription (purchase, trial start, renewal). A refunded payment's effective_expiration_date is the refund time.

Path parameters

Name Type Required Description
project_id string yes Project id (proj...).
subscription_id string yes Subscription id.

Query parameters

Name Type Required Description
sort id, purchased_at no Default id.
direction asc, desc no Default asc.
limit integer no Page size. Values outside 1-100 are clamped, not rejected.
starting_after string no Id of the last item of the previous page. Use next_page instead of building it.

Example request

Shell
curl -s "$REVENUEDOT_URL/v2/projects/$PROJECT_ID/subscriptions/$SUBSCRIPTION_ID/transactions" -H "Authorization: Bearer $SECRET_KEY"

Responses

  • 200: A page of results. Returns a list of SubscriptionTransaction.
  • 400: The request is invalid. Returns V2Error.
  • 401: No API key, or an unknown one. Returns V2Error.
  • 403: The key lacks a permission, or a public key was used. Returns V2Error.
  • 404: Not found in this project (another project's ids also answer 404). Returns V2Error.

Cancel a subscription (Google Play)#

POST /v2/projects/{project_id}/subscriptions/{subscription_id}/actions/cancel · Auth: secret key or dashboard session · Permissions: customer_information:subscriptions:read_write

Google Play only: turns auto-renew off. Other stores answer 422.

Path parameters

Name Type Required Description
project_id string yes Project id (proj...).
subscription_id string yes Subscription id.

Example request

Shell
curl -s -X POST "$REVENUEDOT_URL/v2/projects/$PROJECT_ID/subscriptions/$SUBSCRIPTION_ID/actions/cancel" -H "Authorization: Bearer $SECRET_KEY"

Responses

  • 200: The subscription. Returns Subscription.
  • 401: No API key, or an unknown one. Returns V2Error.
  • 403: The key lacks a permission, or a public key was used. Returns V2Error.
  • 404: Not found in this project (another project's ids also answer 404). Returns V2Error.
  • 422: The request is valid but cannot be done in this state or for this store. Returns V2Error.
  • 503: The store could not be reached. Retry later. Returns V2Error.

Refund and revoke a subscription (Google Play)#

POST /v2/projects/{project_id}/subscriptions/{subscription_id}/actions/refund · Auth: secret key or dashboard session · Permissions: customer_information:subscriptions:read_write

Google Play only: refunds the latest payment and ends access now. App Store refunds go through Apple. Other stores answer 422.

Path parameters

Name Type Required Description
project_id string yes Project id (proj...).
subscription_id string yes Subscription id.

Example request

Shell
curl -s -X POST "$REVENUEDOT_URL/v2/projects/$PROJECT_ID/subscriptions/$SUBSCRIPTION_ID/actions/refund" -H "Authorization: Bearer $SECRET_KEY"

Responses

  • 200: The subscription. Returns Subscription.
  • 401: No API key, or an unknown one. Returns V2Error.
  • 403: The key lacks a permission, or a public key was used. Returns V2Error.
  • 404: Not found in this project (another project's ids also answer 404). Returns V2Error.
  • 422: The request is valid but cannot be done in this state or for this store. Returns V2Error.
  • 503: The store could not be reached. Retry later. Returns V2Error.

Extend a subscription#

POST /v2/projects/{project_id}/subscriptions/{subscription_id}/actions/extend · Auth: secret key or dashboard session · Permissions: customer_information:subscriptions:read_write

App Store: Apple extends the renewal date (1 to 90 days, extend_reason_code required, needs the in-app purchase key). Google Play: the renewal is deferred (up to 365 days). Send extend_by_days or extend_until_ms, not both.

Path parameters

Name Type Required Description
project_id string yes Project id (proj...).
subscription_id string yes Subscription id.

Request body (application/json)

Field Type Required Description
extend_by_days integer yes
extend_reason_code undeclared, customer_satisfaction, other, service_issue_or_outage no Apple's reason for the extension. Required for App Store subscriptions.
extend_until_ms integer yes New end, epoch milliseconds.

Example request

Shell
curl -s -X POST "$REVENUEDOT_URL/v2/projects/$PROJECT_ID/subscriptions/$SUBSCRIPTION_ID/actions/extend" -H "Authorization: Bearer $SECRET_KEY" \
  -H "Content-Type: application/json" -d '{"extend_by_days":7,"extend_reason_code":"customer_satisfaction"}'

Responses

  • 200: The subscription. Returns Subscription.
  • 400: The request is invalid. Returns V2Error.
  • 401: No API key, or an unknown one. Returns V2Error.
  • 403: The key lacks a permission, or a public key was used. Returns V2Error.
  • 404: Not found in this project (another project's ids also answer 404). Returns V2Error.
  • 422: The request is valid but cannot be done in this state or for this store. Returns V2Error.
  • 503: The store could not be reached. Retry later. Returns V2Error.

Refund one payment of a subscription (Google Play)#

POST /v2/projects/{project_id}/subscriptions/{subscription_id}/transactions/{transaction_id}/actions/refund · Auth: secret key or dashboard session · Permissions: customer_information:subscriptions:read_write

Path parameters

Name Type Required Description
project_id string yes Project id (proj...).
subscription_id string yes Subscription id.
transaction_id string yes Google order id of the payment.

Example request

Shell
curl -s -X POST "$REVENUEDOT_URL/v2/projects/$PROJECT_ID/subscriptions/$SUBSCRIPTION_ID/transactions/$TRANSACTION_ID/actions/refund" -H "Authorization: Bearer $SECRET_KEY"

Responses

  • 200: The refunded payment. Returns SubscriptionTransaction.
  • 401: No API key, or an unknown one. Returns V2Error.
  • 403: The key lacks a permission, or a public key was used. Returns V2Error.
  • 404: Not found in this project (another project's ids also answer 404). Returns V2Error.
  • 422: The request is valid but cannot be done in this state or for this store. Returns V2Error.
  • 503: The store could not be reached. Retry later. Returns V2Error.

Purchases#

One-time purchases across customers.

Find one-time purchases by store id#

GET /v2/projects/{project_id}/purchases · Auth: secret key or dashboard session · Permissions: customer_information:purchases:read

Path parameters

Name Type Required Description
project_id string yes Project id (proj...).

Query parameters

Name Type Required Description
store_purchase_identifier string yes Store transaction id.

Example request

Shell
curl -s "$REVENUEDOT_URL/v2/projects/$PROJECT_ID/purchases" -H "Authorization: Bearer $SECRET_KEY"

Responses

  • 200: A page of results. Returns a list of Purchase.
  • 400: The request is invalid. Returns V2Error.
  • 401: No API key, or an unknown one. Returns V2Error.
  • 403: The key lacks a permission, or a public key was used. Returns V2Error.
  • 404: Not found in this project (another project's ids also answer 404). Returns V2Error.

Get a one-time purchase#

GET /v2/projects/{project_id}/purchases/{purchase_id} · Auth: secret key or dashboard session · Permissions: customer_information:purchases:read

Path parameters

Name Type Required Description
project_id string yes Project id (proj...).
purchase_id string yes Purchase id.

Example request

Shell
curl -s "$REVENUEDOT_URL/v2/projects/$PROJECT_ID/purchases/$PURCHASE_ID" -H "Authorization: Bearer $SECRET_KEY"

Responses

  • 200: The purchase. Returns Purchase.
  • 401: No API key, or an unknown one. Returns V2Error.
  • 403: The key lacks a permission, or a public key was used. Returns V2Error.
  • 404: Not found in this project (another project's ids also answer 404). Returns V2Error.

List the entitlements a purchase unlocks#

GET /v2/projects/{project_id}/purchases/{purchase_id}/entitlements · Auth: secret key or dashboard session · Permissions: customer_information:purchases:read

Path parameters

Name Type Required Description
project_id string yes Project id (proj...).
purchase_id string yes Purchase id.

Query parameters

Name Type Required Description
limit integer no Page size. Values outside 1-100 are clamped, not rejected.
starting_after string no Id of the last item of the previous page. Use next_page instead of building it.

Example request

Shell
curl -s "$REVENUEDOT_URL/v2/projects/$PROJECT_ID/purchases/$PURCHASE_ID/entitlements" -H "Authorization: Bearer $SECRET_KEY"

Responses

  • 200: A page of results. Returns a list of Entitlement.
  • 401: No API key, or an unknown one. Returns V2Error.
  • 403: The key lacks a permission, or a public key was used. Returns V2Error.
  • 404: Not found in this project (another project's ids also answer 404). Returns V2Error.

Refund a one-time purchase (Google Play)#

POST /v2/projects/{project_id}/purchases/{purchase_id}/actions/refund · Auth: secret key or dashboard session · Permissions: customer_information:purchases:read_write

Google Play refunds and revokes the order. Other stores answer 422.

Path parameters

Name Type Required Description
project_id string yes Project id (proj...).
purchase_id string yes Purchase id.

Example request

Shell
curl -s -X POST "$REVENUEDOT_URL/v2/projects/$PROJECT_ID/purchases/$PURCHASE_ID/actions/refund" -H "Authorization: Bearer $SECRET_KEY"

Responses

  • 200: The purchase. Returns Purchase.
  • 401: No API key, or an unknown one. Returns V2Error.
  • 403: The key lacks a permission, or a public key was used. Returns V2Error.
  • 404: Not found in this project (another project's ids also answer 404). Returns V2Error.
  • 422: The request is valid but cannot be done in this state or for this store. Returns V2Error.
  • 503: The store could not be reached. Retry later. Returns V2Error.

Metrics#

The dashboard overview numbers.

Overview metrics#

GET /v2/projects/{project_id}/metrics/overview · Auth: secret key or dashboard session · Permissions: charts_metrics:overview:read

Computed live: active trials, active paid subscriptions, MRR (USD price normalised to a month), revenue in the last 28 days, new and active customers in the last 28 days.

Path parameters

Name Type Required Description
project_id string yes Project id (proj...).

Query parameters

Name Type Required Description
currency "USD" no Only USD is supported.
environment production, sandbox no RevenueDot extension. Default production.

Example request

Shell
curl -s "$REVENUEDOT_URL/v2/projects/$PROJECT_ID/metrics/overview" -H "Authorization: Bearer $SECRET_KEY"

Responses

  • 200: The metrics. Returns OverviewMetrics.
  • 400: The request is invalid. Returns V2Error.
  • 401: No API key, or an unknown one. Returns V2Error.
  • 403: The key lacks a permission, or a public key was used. Returns V2Error.
  • 404: Not found in this project (another project's ids also answer 404). Returns V2Error.

Webhook integrations#

Where events are sent.

List webhooks#

GET /v2/projects/{project_id}/integrations/webhooks · Auth: secret key or dashboard session · Permissions: project_configuration:integrations:read

Path parameters

Name Type Required Description
project_id string yes Project id (proj...).

Query parameters

Name Type Required Description
limit integer no Page size. Values outside 1-100 are clamped, not rejected.
starting_after string no Id of the last item of the previous page. Use next_page instead of building it.

Example request

Shell
curl -s "$REVENUEDOT_URL/v2/projects/$PROJECT_ID/integrations/webhooks" -H "Authorization: Bearer $SECRET_KEY"

Responses

  • 200: A page of results. Returns a list of WebhookIntegration.
  • 401: No API key, or an unknown one. Returns V2Error.
  • 403: The key lacks a permission, or a public key was used. Returns V2Error.
  • 404: Not found in this project (another project's ids also answer 404). Returns V2Error.

Create a webhook#

POST /v2/projects/{project_id}/integrations/webhooks · Auth: secret key or dashboard session · Permissions: project_configuration:integrations:read_write

The answer includes signing_secret (whsec_...) once. Store it: it verifies the X-RevenueCat-Webhook-Signature header. See Webhooks.

Path parameters

Name Type Required Description
project_id string yes Project id (proj...).

Request body (application/json)

Field Type Required Description
name string yes
url string yes http(s) URL.
authorization_header string or null no Sent as the Authorization header.
environment production, sandbox, null no Null or absent: both.
event_types array of initial_purchase, renewal, product_change, cancellation, billing_issue, non_renewing_purchase, uncancellation, transfer, subscription_paused, expiration, subscription_extended, invoice_issuance, temporary_entitlement_grant, refund_reversed, virtual_currency_transaction, test, experiment_enrollment, purchase_redeemed, subscriber_alias, price_increase_consent_required, price_increase_consent_approved no Empty or absent: every type.
app_id string or null no Only this app's events.

Example request

Shell
curl -s -X POST "$REVENUEDOT_URL/v2/projects/$PROJECT_ID/integrations/webhooks" -H "Authorization: Bearer $SECRET_KEY" \
  -H "Content-Type: application/json" -d '{"name":"Backend","url":"https://api.example.com/webhooks/revenuedot","authorization_header":"Bearer my-shared-token","environment":"production","event_types":["initial_purchase","renewal"]}'

Responses

  • 201: The webhook with its signing secret. Returns WebhookIntegration.
  • 400: The request is invalid. Returns V2Error.
  • 401: No API key, or an unknown one. Returns V2Error.
  • 403: The key lacks a permission, or a public key was used. Returns V2Error.
  • 404: Not found in this project (another project's ids also answer 404). Returns V2Error.

Example 201 response:

JSON
{
  "object": "webhook_integration",
  "id": "wh_ceps8nr7mczvhaqw",
  "project_id": "proj18pzzkao",
  "name": "Backend",
  "url": "https://api.example.com/webhooks/revenuedot",
  "environment": "production",
  "event_types": [
    "initial_purchase",
    "renewal"
  ],
  "app_id": null,
  "created_at": 1790801342625,
  "signing_secret": "whsec_3f5b7fb5a591c17aaa9108376df0bddbe1555f0a908bfdc0"
}

Get a webhook#

GET /v2/projects/{project_id}/integrations/webhooks/{webhook_integration_id} · Auth: secret key or dashboard session · Permissions: project_configuration:integrations:read

Path parameters

Name Type Required Description
project_id string yes Project id (proj...).
webhook_integration_id string yes Webhook id (wh_...).

Example request

Shell
curl -s "$REVENUEDOT_URL/v2/projects/$PROJECT_ID/integrations/webhooks/$WEBHOOK_INTEGRATION_ID" -H "Authorization: Bearer $SECRET_KEY"

Responses

  • 200: The webhook. Returns WebhookIntegration.
  • 401: No API key, or an unknown one. Returns V2Error.
  • 403: The key lacks a permission, or a public key was used. Returns V2Error.
  • 404: Not found in this project (another project's ids also answer 404). Returns V2Error.

Update a webhook#

POST /v2/projects/{project_id}/integrations/webhooks/{webhook_integration_id} · Auth: secret key or dashboard session · Permissions: project_configuration:integrations:read_write

enabled is a RevenueDot extension: false pauses deliveries without deleting the webhook. Events recorded while it is off are not sent; queued retries resume when it is turned on. Read it with GET /v2/projects/{project_id}/webhooks.

Path parameters

Name Type Required Description
project_id string yes Project id (proj...).
webhook_integration_id string yes Webhook id.

Request body (application/json)

Field Type Required Description
name string no
url string no
authorization_header string or null no
environment string or null no
event_types array of string no
app_id string or null no
enabled boolean no RevenueDot extension. False pauses deliveries.

Example request

Shell
curl -s -X POST "$REVENUEDOT_URL/v2/projects/$PROJECT_ID/integrations/webhooks/$WEBHOOK_INTEGRATION_ID" -H "Authorization: Bearer $SECRET_KEY" \
  -H "Content-Type: application/json" -d '{"enabled":false}'

Responses

  • 200: The webhook. Returns WebhookIntegration.
  • 400: The request is invalid. Returns V2Error.
  • 401: No API key, or an unknown one. Returns V2Error.
  • 403: The key lacks a permission, or a public key was used. Returns V2Error.
  • 404: Not found in this project (another project's ids also answer 404). Returns V2Error.

Delete a webhook#

DELETE /v2/projects/{project_id}/integrations/webhooks/{webhook_integration_id} · Auth: secret key or dashboard session · Permissions: project_configuration:integrations:read_write

Pending deliveries are deleted with it.

Path parameters

Name Type Required Description
project_id string yes Project id (proj...).
webhook_integration_id string yes Webhook id.

Example request

Shell
curl -s -X DELETE "$REVENUEDOT_URL/v2/projects/$PROJECT_ID/integrations/webhooks/$WEBHOOK_INTEGRATION_ID" -H "Authorization: Bearer $SECRET_KEY"

Responses

  • 200: Deleted. Returns Deleted.
  • 401: No API key, or an unknown one. Returns V2Error.
  • 403: The key lacks a permission, or a public key was used. Returns V2Error.
  • 404: Not found in this project (another project's ids also answer 404). Returns V2Error.

Example 200 response:

JSON
{
  "object": "webhook_integration",
  "id": "…",
  "deleted_at": 1790801342625
}

Collaborators#

Dashboard users of the project.

List collaborators#

GET /v2/projects/{project_id}/collaborators · Auth: secret key or dashboard session · Permissions: project_configuration:collaborators:read

Path parameters

Name Type Required Description
project_id string yes Project id (proj...).

Example request

Shell
curl -s "$REVENUEDOT_URL/v2/projects/$PROJECT_ID/collaborators" -H "Authorization: Bearer $SECRET_KEY"

Responses

  • 200: A page of results. Returns a list of Collaborator.
  • 401: No API key, or an unknown one. Returns V2Error.
  • 403: The key lacks a permission, or a public key was used. Returns V2Error.
  • 404: Not found in this project (another project's ids also answer 404). Returns V2Error.

Objects#

The shapes the operations above send and return.

ActiveEntitlement#

Field Type Required Description
object "customer.active_entitlement" yes
entitlement_id string yes Entitlement id (entl...), not the lookup key.
expires_at integer or null yes When access ends. Epoch milliseconds, or null.

App#

Only the object for the app's own type is present. Store secrets are never returned.

Field Type Required Description
object "app" yes
id string yes App id (app...).
name string yes
created_at integer yes Creation time. Epoch milliseconds.
type amazon, app_store, mac_app_store, play_store, stripe, rc_billing, roku, paddle, test_store yes
project_id string yes
custom_url_scheme string no Derived from the public key.
app_store object no
app_store.bundle_id string no
app_store.app_store_connect_api_key_configured boolean no
app_store.subscription_key_configured boolean no True when the in-app purchase key (.p8, key id, issuer id) is set.
app_store.app_store_connect_vendor_number string or null no
mac_app_store object no
mac_app_store.bundle_id string no
play_store object no
play_store.package_name string no
play_store.play_service_account_credentials_configured boolean no
amazon object no
amazon.package_name string no
stripe object no
stripe.stripe_account_id string or null no
rc_billing object no
rc_billing.stripe_account_id string or null no
rc_billing.seller_company_name string no
rc_billing.app_name string no
rc_billing.support_email string or null no
rc_billing.default_currency string no
roku object no
roku.roku_channel_id string or null no
roku.roku_channel_name string or null no
paddle object no
paddle.paddle_is_sandbox boolean no
paddle.paddle_api_key null no

Collaborator#

Field Type Required Description
object "collaborator" yes
id string yes
name string or null no
email string yes
role admin, developer, read_only yes RevenueCat's role names. read_only is the dashboard's Viewer role.
accepted_at integer no When the user joined. Epoch milliseconds.
has_mfa boolean no Always false.

Customer#

active_entitlements and experiment are present on single-customer answers; attributes only with expand=attributes.

Field Type Required Description
object "customer" yes
id string yes The customer's original app user id.
project_id string yes
first_seen_at integer yes First seen. Epoch milliseconds.
last_seen_at integer or null yes Last seen. Epoch milliseconds, or null.
last_seen_app_version string or null no
last_seen_country string or null no
last_seen_platform string or null no
last_seen_platform_version null no
active_entitlements object no
active_entitlements.object "list" yes
active_entitlements.items array of ActiveEntitlement yes
active_entitlements.next_page string or null yes Path of the next page, or null on the last page.
active_entitlements.url string yes Path of this list.
experiment null no
attributes object no
attributes.object "list" yes
attributes.items array of CustomerAttribute yes
attributes.next_page string or null yes Path of the next page, or null on the last page.
attributes.url string yes Path of this list.

CustomerAlias#

Field Type Required Description
object "customer.alias" yes
id string yes An app user id of the customer.
created_at integer yes When it was linked. Epoch milliseconds.

CustomerAttribute#

Field Type Required Description
object "customer.attribute" yes
name string yes
value string yes
updated_at integer yes Last update. Epoch milliseconds.

CustomerEvent#

Field Type Required Description
object "customer.event" yes
id string yes
app_id string or null no
type string yes Webhook event type, for example INITIAL_PURCHASE.
body object yes The webhook event object.
created_at integer yes Recorded. Epoch milliseconds.
occurred_at integer yes When it happened. Epoch milliseconds.

Deleted#

Field Type Required Description
object string yes The deleted object's type.
id string yes
deleted_at integer yes When it was deleted. Epoch milliseconds.

Entitlement#

Field Type Required Description
object "entitlement" yes
id string yes Entitlement id (entl...).
project_id string yes
lookup_key string yes What apps check, for example pro.
display_name string yes
created_at integer yes Creation time. Epoch milliseconds.
state active, inactive yes
products object no
products.object "list" yes
products.items array of Product yes
products.next_page string or null yes Path of the next page, or null on the last page.
products.url string yes Path of this list.

IndicativePrice#

Field Type Required Description
object "indicative_price" yes
currency string yes ISO 4217 code.
country null yes
amount_micros integer yes Price in micros: 9.99 is 9990000.

MonetaryAmount#

Field Type Required Description
currency string yes ISO 4217 currency code.
gross number yes Gross amount.
commission number yes Estimated store commission.
tax number yes Tax. Always 0 today.
proceeds number yes Gross minus commission.

Offering#

Field Type Required Description
object "offering" yes
id string yes Offering id (ofrng...).
lookup_key string yes
display_name string yes
is_current boolean yes Exactly one offering per project is current.
created_at integer yes Creation time. Epoch milliseconds.
project_id string yes
state active, inactive yes
paywall_id null no
metadata object or null yes
packages object no
packages.object "list" yes
packages.items array of Package yes
packages.next_page string or null yes Path of the next page, or null on the last page.
packages.url string yes Path of this list.

OverviewMetrics#

Field Type Required Description
object "overview_metrics" yes
currency "USD" yes
metrics array of object yes
metrics[].object "overview_metric" no
metrics[].id active_trials, active_subscriptions, mrr, revenue, new_customers, active_users no
metrics[].name string no
metrics[].description string no
metrics[].unit #, $ no
metrics[].period P0D, P28D no
metrics[].value number no
metrics[].last_updated_at integer no Computed at. Epoch milliseconds.
metrics[].last_updated_at_iso8601 string no

Package#

Field Type Required Description
object "package" yes
id string yes Package id (pkge...).
lookup_key string yes For example $rc_monthly.
display_name string yes
position integer yes Order in the offering, lowest first.
created_at integer yes Creation time. Epoch milliseconds.
products object no
products.object "list" yes
products.items array of PackageProduct yes
products.next_page string or null yes Path of the next page, or null on the last page.
products.url string yes Path of this list.

PackageProduct#

Field Type Required Description
product Product yes
eligibility_criteria all, google_sdk_lt_6, google_sdk_ge_6 yes

Product#

Field Type Required Description
object "product" yes
id string yes Product id (prod...).
store_identifier string yes The store's product id. Google Play subscriptions use subscriptionId:basePlanId.
type subscription, one_time, consumable, non_consumable, non_renewing_subscription yes
state active, inactive yes
subscription object no
subscription.duration string or null no ISO 8601 period such as P1M.
subscription.grace_period_duration null no
subscription.trial_duration null no
one_time object no
one_time.is_consumable boolean or null no
created_at integer yes Creation time. Epoch milliseconds.
app_id string yes
display_name string or null yes
app App no Only the object for the app's own type is present. Store secrets are never returned.
indicative_price IndicativePrice or null no With expand=indicative_price: the Test Store price, or null.

Project#

Field Type Required Description
object "project" yes
id string yes Project id (proj...).
name string yes
created_at integer yes Creation time. Epoch milliseconds.
icon_url string or null no Always null.
icon_url_large string or null no Always null.

PublicApiKey#

Field Type Required Description
object "public_api_key" yes
id string yes
key string yes The key the SDK sends (appl_, goog_, test_ ...).
environment production, sandbox yes
app_id string yes
created_at integer yes Creation time. Epoch milliseconds.

Purchase#

Field Type Required Description
object "purchase" yes
id string yes
customer_id string yes
original_customer_id string no
product_id string yes
purchased_at integer yes Purchase time. Epoch milliseconds.
revenue_in_usd MonetaryAmount no
quantity integer no
status owned, refunded yes
presented_offering_id string or null no Offering the purchase was made from (its id, or the identifier the SDK sent when no such offering exists).
entitlements object no
entitlements.object "list" yes
entitlements.items array of Entitlement yes
entitlements.next_page string or null yes Path of the next page, or null on the last page.
entitlements.url string yes Path of this list.
environment production, sandbox yes
store string yes
store_purchase_identifier string no
ownership purchased no
country string no

Subscription#

Field Type Required Description
object "subscription" yes
id string yes Subscription id (sub_...).
customer_id string yes
original_customer_id string no
product_id string or null no Product id (prod...), null for promotional grants.
starts_at integer yes Start of the subscription. Epoch milliseconds.
current_period_starts_at integer no Start of the current period. Epoch milliseconds.
current_period_ends_at integer or null no End of the current period. Epoch milliseconds, or null.
ends_at integer or null no End of access. Epoch milliseconds, or null.
gives_access boolean yes
pending_payment boolean no
auto_renewal_status will_renew, will_not_renew, will_change_product, will_pause yes
status trialing, active, in_grace_period, in_billing_retry, paused, expired yes
total_revenue_in_usd MonetaryAmount no
presented_offering_id string or null no Offering the purchase was made from (its id, or the identifier the SDK sent when no such offering exists).
entitlements object no
entitlements.object "list" yes
entitlements.items array of Entitlement yes
entitlements.next_page string or null yes Path of the next page, or null on the last page.
entitlements.url string yes Path of this list.
environment production, sandbox yes
store string yes
store_subscription_identifier string no Latest store transaction id, order id or token.
ownership purchased, family_shared no
country string no ISO 3166-1 alpha-2, when known.
management_url null no

SubscriptionTransaction#

Field Type Required Description
object "subscription_transaction" yes
id string yes
purchased_at integer yes Purchase time. Epoch milliseconds.
product_store_identifier string no
revenue_in_local_currency MonetaryAmount or null no
revenue_in_usd MonetaryAmount no
expiration_date integer or null no End of the period. Epoch milliseconds, or null.
effective_expiration_date integer or null no When access actually ended (the refund time for a refunded period). Epoch milliseconds, or null.

V2Error#

Field Type Required Description
object "error" yes
type parameter_error, resource_already_exists, resource_missing, idempotency_error, rate_limit_error, authentication_error, authorization_error, store_error, server_error, resource_locked_error, unprocessable_entity_error, invalid_request, entity_references_archived_entities yes
message string yes What went wrong.
param string no The request field at fault, when there is one.
doc_url string yes Link to the error's section of the errors page.
retryable boolean yes True when retrying the same request can succeed.

WebhookIntegration#

Field Type Required Description
object "webhook_integration" yes
id string yes Webhook id (wh_...).
project_id string yes
name string yes
url string yes
environment production, sandbox, null yes Null sends both.
event_types array of string yes Lower-case event types. Empty sends every type.
app_id string or null yes Only events of this app, or null for all.
created_at integer yes Creation time. Epoch milliseconds.
signing_secret string no whsec_... Only in the answer that creates the webhook.
Edit the OpenAPI source on GitHub ↗ View as Markdown Last updated