Skip to main content
API docs by Redocly

Developer API (2.0.0)

Download OpenAPI specification:Download

Subscription Data Model

object
required
string
Value: "subscription"

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

id
required
string [ 1 .. 255 ] characters

The ID of the subscription (generated by RevenueCat)

customer_id
required
string [ 1 .. 1500 ] characters

The ID of the customer

original_customer_id
required
string [ 1 .. 1500 ] characters

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

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

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

starts_at
required
integer <int64>

The date when the subscription originally started in ms since epoch

current_period_starts_at
required
integer <int64>

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

current_period_ends_at
required
integer or null <int64>

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

ends_at
required
integer or null <int64>

The date when the latest subscription billing period is expected to end in ms since epoch. It will only be different from current_period_ends_at if auto_renewal_status is has_already_renewed, in which case it indicates the end of the next billing period. Can be null if the subscription is paused until an indefinite date.

gives_access
required
boolean

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

pending_payment
required
boolean

Determines whether there is a pending payment associated with the subscription

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

The auto renewal status of a subscription.

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

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

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

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

required
MonetaryAmount (object)

Total revenue generated by a subscription in USD

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

ISO 4217 currency code

gross
required
number

Total revenue generated (excluding taxes and commission)

commission
number

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

tax
required
number

Estimated taxes deducted from gross revenue

proceeds
required
number

Net revenue after store commission / fees and taxes

property name*
additional property
any
presented_offering_id
required
string or null [ 1 .. 200 ] characters

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

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

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

required
Array of objects (Entitlement)

Details about each object.

next_page
required
string or null

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

url
required
string <= 5000 characters

The URL where this list can be accessed.

required
Environment (string)

The store environment

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

The store environment

store
required
string
Enum: "amazon" "app_store" "mac_app_store" "play_store" "promotional" "stripe" "rc_billing" "external" "roku" "paddle" … 3 more

Store the subscription belongs to

store_subscription_identifier
required
string [ 1 .. 255 ] characters

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

required
Ownership (string)

Ownership of the subscription

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

Ownership of the subscription

object or null

Expected changes to the subscription that will occur at the end of the current period. Present when the subscription has a pending product change, has already renewed for the next period, or has a failed upcoming renewal. Only fields that differ from the current subscription state are included.

object or null

The product that will be active as of the next renewal

current_period_starts_at
integer or null <int64>

Expected start of the next billing period in ms since epoch. Omitted when unchanged from the current subscription.

current_period_ends_at
integer or null <int64>

Expected end of the next billing period in ms since epoch. Omitted when unchanged from the current subscription.

store_subscription_identifier
string or null [ 1 .. 255 ] characters

Expected store subscription identifier for the next period. Omitted when unchanged from the current subscription.

auto_renewal_status
string or null
Enum: "will_renew" "will_not_renew" "will_change_product" "will_pause" "requires_price_increase_consent" "has_already_renewed"

Expected auto renewal status for the next period. Omitted when unchanged from the current subscription.

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

Expected subscription status for the next period. Omitted when unchanged from the current subscription.

pending_payment
boolean or null

Expected pending payment flag for the next period. Omitted when unchanged from the current subscription.

gives_access
boolean or null

Expected access flag for the next period. Omitted when unchanged from the current subscription.

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

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

management_url
required
string or null

The URL to manage the subscription

object or null (Redemption)

Information about the most recent successful redemption of the purchase's redemption link. Only applicable to Web Billing web-to-web purchases; null if the purchase has never been successfully redeemed (or has no redemption link, e.g. purchases from other stores).

object
required
string
Value: "redemption"

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

redeemed_at
required
integer <int64>

The date of the most recent successful redemption of the purchase's redemption link in ms since epoch.

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