diff --git a/docs/integrations/webhooks/event-types-and-fields.mdx b/docs/integrations/webhooks/event-types-and-fields.mdx index fafa1a442..7b4096dff 100644 --- a/docs/integrations/webhooks/event-types-and-fields.mdx +++ b/docs/integrations/webhooks/event-types-and-fields.mdx @@ -61,37 +61,37 @@ If we have to retry a webhook for any reason, the retry will have the same `id` ## Subscription Lifecycle Events Fields -| Field | Type | Description | Possible Values | -| ------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `product_id` | String | Product identifier of the subscription. Please note: For Google Play products set up in RevenueCat after February 2023, this identifier has the format `:`. | | -| `entitlement_ids` | Array | Entitlement identifiers of the subscription. It can be `NULL` if the `product_id` is not mapped to any entitlements. | | -| `entitlement_id` | String | Deprecated. See `entitlement_ids`. | Deprecated. See `entitlement_ids`. | -| `period_type` | String | Period type of the transaction. | `TRIAL` (for free trials), `INTRO` (for introductory pricing), `NORMAL` (standard subscription), `PROMOTIONAL` (for subscriptions granted through RevenueCat), `PREPAID` (for Play Store prepaid transactions). | -| `purchased_at_ms` | Integer | Time when the transaction was purchased. Measured in milliseconds since Unix epoch. | | -| `grace_period_expiration_at_ms` | Integer | Only available for `BILLING_ISSUE` events. The time that the grace period for the subscription would expire. Measured in milliseconds since Unix epoch. Use this field to determine if the user is currently in a grace period. It can be `NULL` if the subscription does not have a grace period. | | -| `expiration_at_ms` | Integer | Expiration of the transaction. Measured in milliseconds since Unix epoch. Use this field to determine if a subscription is still active. It can be `NULL` for non-subscription purchases. | | -| `auto_resume_at_ms` | Integer | The time when an Android subscription would resume after being paused. Measured in milliseconds since Unix epoch. Only available for Play Store subscriptions and `SUBSCRIPTION_PAUSED` events. | | -| `store` | String | Store the subscription belongs to. | `AMAZON`, `APP_STORE`, `MAC_APP_STORE`, `PADDLE`, `PLAY_STORE`, `PROMOTIONAL`, `RC_BILLING`, `ROKU`, `STRIPE`, or `TEST_STORE`. | -| `environment` | String | Store environment. | `SANDBOX`, `PRODUCTION`. | -| `is_trial_conversion` | Boolean | Only available for `RENEWAL` events. Whether the previous transaction was a free trial or not. | `true` or `false`. | -| `cancel_reason` | String | Only available for `CANCELLATION` events. See [Cancellation and Expiration Reasons](/integrations/webhooks/event-types-and-fields#cancellation-and-expiration-reasons). | `UNSUBSCRIBE`, `BILLING_ERROR`, `DEVELOPER_INITIATED`, `PRICE_INCREASE`, `CUSTOMER_SUPPORT`, `UNKNOWN`. | -| `expiration_reason` | String | Only available for `EXPIRATION` events. See [Cancellation and Expiration Reasons](/integrations/webhooks/event-types-and-fields#cancellation-and-expiration-reasons). | `UNSUBSCRIBE`, `BILLING_ERROR`, `DEVELOPER_INITIATED`, `PRICE_INCREASE`, `CUSTOMER_SUPPORT`, `UNKNOWN`. | -| `new_product_id` | String | Product identifier of the new product the subscriber has switched to. Only available in `PRODUCT_CHANGE` events for Play Store subscriptions with the `DEFERRED` replacement mode and App Store subscriptions. | | -| `presented_offering_id` | String | Not available for apps using legacy entitlements. The identifier for the offering that was presented to the user during their initial purchase. Can be `NULL` if the purchase was made using `purchaseProduct` instead of `purchasePackage` or if the purchase was made outside of your app or before you integrated RevenueCat. | | -| `price` | Double | The USD price of the transaction. Can be `NULL` if the price is unknown, and `0` for free trials. Can be negative for refunds. | | -| `currency` | String | The ISO 4217 currency code that the product was purchased in. Can be `NULL` if the currency is unknown. | `USD`, `CAD`, etc. | -| `price_in_purchased_currency` | Double | The price of the transaction in the currency the product was purchased in. Can be `NULL` if the price is unknown, and `0` for free trials. Can be negative for refunds. | | -| `tax_percentage` | Double | The estimated percentage of the transaction price that was deducted for taxes (varies by country and store). Can be `NULL` if the tax percentage is unknown. | | -| `commission_percentage` | Double | The estimated percentage of the transaction price that was deducted as a store commission / processing fee. Can be `NULL` if the commission percentage is unknown. | | -| `takehome_percentage` | Double | DEPRECATED: The estimated percentage of the transaction price that will be paid out to developers after commissions, but before VAT and DST taxes are taken into account. We recommend using `tax_percentage` and `commission_percentage` to calculate proceeds instead. [Learn more here](/dashboard-and-metrics/taxes-and-commissions). | | -| `transaction_id` | String | Transaction identifier from Apple/Amazon/Google/Stripe. | | -| `original_transaction_id` | String | `transaction_id` of the original transaction in the subscription from Apple/Amazon/Google/Stripe. | | -| `is_family_share` | Boolean | Indicates if the user made this purchase or if it was shared to them via [Family Sharing](https://help.apple.com/app-store-connect/#/dev45b03fab9). Always false for non-Apple purchases. | `true` or `false`. | -| `transferred_from` | String[] | This field is only available when `type` is set to `TRANSFER`. App User ID(s) that transactions and entitlements are being taken from, and granted to `transferred_to`. | | -| `transferred_to` | String[] | This field is only available when `type` is set to `TRANSFER`. App User ID(s) that are receiving the transactions and entitlements taken from `transferred_from`. | | -| `country_code` | String | The ISO 3166 country code that the product was purchased in. The two-letter country code (e.g., US, GB, CA) of the app user's location (this country code is derived from the last seen request from the SDK for the subscriber.) | `US`, `CA`, etc. | -| `offer_code` | String | Not available when `type` is set to `SUBSCRIBER_ALIAS` or `TRANSFER`. The offer code that the customer used to redeem the transaction. Available for App Store and Play Store. For App Store this property corresponds to the [`offerIdentifier`](https://developer.apple.com/documentation/appstoreserverapi/offeridentifier). For Play Store this corresponds to the [`promotionCode`](https://developers.google.com/android-publisher/api-ref/rest/v3/purchases.subscriptions). Can be null if no offer code was used for this product. | | -| `renewal_number` | Integer | The number of renewals that this subscription has already gone through. Always starts at 1. Trial conversions are counted as renewals. `is_trial_conversion` is used to signify whether a transaction was a trial conversion. | | +| Field | Type | Description | Possible Values | +| ------------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `product_id` | String | Product identifier of the subscription. Please note: For Google Play products set up in RevenueCat after February 2023, this identifier has the format `:`. | | +| `entitlement_ids` | Array | Entitlement identifiers of the subscription. It can be `NULL` if the `product_id` is not mapped to any entitlements. | | +| `entitlement_id` | String | Deprecated. See `entitlement_ids`. | Deprecated. See `entitlement_ids`. | +| `period_type` | String | Period type of the transaction. | `TRIAL` (for free trials), `INTRO` (for introductory pricing), `NORMAL` (standard subscription), `PROMOTIONAL` (for subscriptions granted through RevenueCat), `PREPAID` (for Play Store prepaid transactions). | +| `purchased_at_ms` | Integer | Time when the transaction was purchased. Measured in milliseconds since Unix epoch. | | +| `grace_period_expiration_at_ms` | Integer | Only available for `BILLING_ISSUE` events. The time that the grace period for the subscription would expire. Measured in milliseconds since Unix epoch. Use this field to determine if the user is currently in a grace period. It can be `NULL` if the subscription does not have a grace period. | | +| `expiration_at_ms` | Integer | Expiration of the transaction. Measured in milliseconds since Unix epoch. Use this field to determine if a subscription is still active. It can be `NULL` for non-subscription purchases. | | +| `auto_resume_at_ms` | Integer | The time when an Android subscription would resume after being paused. Measured in milliseconds since Unix epoch. Only available for Play Store subscriptions and `SUBSCRIPTION_PAUSED` events. | | +| `store` | String | Store the subscription belongs to. | `AMAZON`, `APP_STORE`, `MAC_APP_STORE`, `PADDLE`, `PLAY_STORE`, `PROMOTIONAL`, `RC_BILLING`, `ROKU`, `STRIPE`, or `TEST_STORE`. | +| `environment` | String | Store environment. | `SANDBOX`, `PRODUCTION`. | +| `is_trial_conversion` | Boolean | Only available for `RENEWAL` events. Whether the previous transaction was a free trial or not. | `true` or `false`. | +| `cancel_reason` | String | Only available for `CANCELLATION` events. See [Cancellation and Expiration Reasons](/integrations/webhooks/event-types-and-fields#cancellation-and-expiration-reasons). | `UNSUBSCRIBE`, `BILLING_ERROR`, `DEVELOPER_INITIATED`, `PRICE_INCREASE`, `CUSTOMER_SUPPORT`, `UNKNOWN`. | +| `expiration_reason` | String | Only available for `EXPIRATION` events. See [Cancellation and Expiration Reasons](/integrations/webhooks/event-types-and-fields#cancellation-and-expiration-reasons). | `UNSUBSCRIBE`, `BILLING_ERROR`, `DEVELOPER_INITIATED`, `PRICE_INCREASE`, `CUSTOMER_SUPPORT`, `UNKNOWN`. | +| `new_product_id` | String | Product identifier of the new product the subscriber has switched to. Only available in `PRODUCT_CHANGE` events for Play Store subscriptions with the `DEFERRED` replacement mode and App Store subscriptions. | | +| `presented_offering_id` | String | Not available for apps using legacy entitlements. The identifier for the offering that was presented to the user during their initial purchase. Can be `NULL` if the purchase was made using `purchaseProduct` instead of `purchasePackage` or if the purchase was made outside of your app or before you integrated RevenueCat. | | +| `price` | Double | The USD price of the transaction. Can be `NULL` if the price is unknown, and `0` for free trials. Can be negative for refunds. | | +| `currency` | String | The ISO 4217 currency code that the product was purchased in. Can be `NULL` if the currency is unknown. | `USD`, `CAD`, etc. | +| `price_in_purchased_currency` | Double | The price of the transaction in the currency the product was purchased in. Can be `NULL` if the price is unknown, and `0` for free trials. Can be negative for refunds. | | +| `tax_percentage` | Double | The estimated percentage of the transaction price that was deducted for taxes (varies by country and store). Can be `NULL` if the tax percentage is unknown. | | +| `commission_percentage` | Double | The estimated percentage of the transaction price that was deducted as a store commission / processing fee. Can be `NULL` if the commission percentage is unknown. | | +| `takehome_percentage` | Double | DEPRECATED: The estimated percentage of the transaction price that will be paid out to developers after commissions, but before VAT and DST taxes are taken into account. We recommend using `tax_percentage` and `commission_percentage` to calculate proceeds instead. [Learn more here](/dashboard-and-metrics/taxes-and-commissions). | | +| `transaction_id` | String | Transaction identifier from Apple/Amazon/Google/Stripe. | | +| `original_transaction_id` | String | `transaction_id` of the original transaction in the subscription from Apple/Amazon/Google/Stripe. | | +| `is_family_share` | Boolean | Indicates if the user made this purchase or if it was shared to them via [Family Sharing](https://help.apple.com/app-store-connect/#/dev45b03fab9). Always false for non-Apple purchases. | `true` or `false`. | +| `transferred_from` | String[] | This field is only available when `type` is set to `TRANSFER`. App User ID(s) that transactions and entitlements are being taken from, and granted to `transferred_to`. | | +| `transferred_to` | String[] | This field is only available when `type` is set to `TRANSFER`. App User ID(s) that are receiving the transactions and entitlements taken from `transferred_from`. | | +| `country_code` | String | The ISO 3166 country code that the product was purchased in. The two-letter country code (e.g., US, GB, CA) of the app user's location (this country code is derived from the last seen request from the SDK for the subscriber.) | `US`, `CA`, etc. | +| `offer_code` | String | Not available when `type` is set to `SUBSCRIBER_ALIAS` or `TRANSFER`. The code or identifier that the customer used to redeem the transaction. Available for App Store and Play Store. For App Store this property corresponds to the [`offerIdentifier`](https://developer.apple.com/documentation/appstoreserverapi/offeridentifier). For Play Store this corresponds to the [`promotionCode`](https://developers.google.com/android-publisher/api-ref/rest/v3/purchases.subscriptions). Can be null if no offer code was used for this product. | | +| `renewal_number` | Integer | The number of renewals that this subscription has already gone through. Always starts at 1. Trial conversions are counted as renewals. `is_trial_conversion` is used to signify whether a transaction was a trial conversion. | | :::info Determine trial and subscription duration To get a trial or subscription's duration from a webhook, you can subtract purchased_at_ms from expiration_at_ms and you will get the duration of the trial in milliseconds.