Billing events
The reference card for billing.* deliveries — types, envelope, and the data payload, in one place.
Fictura → your server, POST, JSON, an 8-second timeout per try, and up to 5 retries (schedule and pausing). Every try carries the same event_id in the body and X-Fictura-Event-Id header, so drop repeats; X-Fictura-Attempt counts the tries. Setup and integration guidance live in Billing webhooks; this page is the contract.
type | data.event_name | Semantics |
|---|---|---|
billing.purchase | subscription_started | Paid subscription, no trial. |
billing.trial_start | trial_started | Trial began; price is 0. |
billing.conversion | trial_converted | The trial's first paid period. |
billing.renewal | subscription_renewed | Paid period renewed. |
billing.cancellation | subscription_cancelled, trial_cancelled or subscription_refunded | Auto-renew off; access continues to expires_at. subscription_refunded is a refund (RevenueCat's cancel reason CUSTOMER_SUPPORT). |
billing.expiration | subscription_expired or trial_expired | Access ended. |
billing.billing_issue | billing_issue | Payment failed; grace period. |
billing.non_renewing_purchase | non_renewing_purchase | A one-off purchase, like a lifetime unlock. |
billing.pause / billing.extension | subscription_paused / subscription_extended | Paused (Play Store; access stops while it holds) or extended by the store. |
billing.product_change / billing.transfer | subscription_product_changed / subscription_transferred | Plan change at next renewal; moved between users. |
billing.other | varies, e.g. subscription_uncancelled, refund_reversed, price_increase_pending, entitlement_granted | Everything else. |
RevenueCat's TEST ping is recorded as a webhook_test event and is never delivered here. Event names follow the canonical billing names; deliveries made before the switch used subscription_renewed for a conversion and subscription_cancelled for a refund, so a handler that matches on data.event_name should accept both (old → new). Stripe conversions still arrive as subscription_renewed. Matching on type is unaffected.
{
"type": "billing.purchase",
"app_id": "6b8506b9-2f01-499b-a95a-e64ee67b2d3a",
"sent_at": "2026-08-10T18:22:41.000Z",
"event_id": "b1c2d3e4-5f6a-4b7c-8d9e-0f1a2b3c4d5e",
"data": {
"event_name": "subscription_started",
"app_user_id": "8f14e45f-ceea-467f-a9d2-5f9e4b1c2d3e",
"product_id": "price_1TmKgSDnJtk7pxNB…",
"price": 9.99,
"currency": "USD",
"store": "STRIPE",
"country": "US",
"expires_at": "2026-09-10T18:22:41.000Z",
"period_type": "NORMAL",
"environment": "PRODUCTION",
"master_user_id": "0f1e2d3c-4b5a-6978-8695-a4b3c2d1e0f9"
}
}currency is the currency the buyer paid in. On a RevenueCat delivery price is USD and price_local is the amount in currency (equal to price for a USD sale). On a Stripe delivery price is already in currency, and there is no price_local.
Stripe-originated and RevenueCat-originated events otherwise arrive in this same shape — store tells them apart (STRIPE, or RevenueCat's store name, such as RC_BILLING, APP_STORE or PLAY_STORE). Skip environment: "SANDBOX" in production handlers. The same connection also delivers error.*, uptime.* and experiment events — the full catalog is on Outgoing webhooks.