RevenueCat Webhooks for Affiliate Commissions Explained

Affiliate commissions on a subscription app are computed from RevenueCat webhooks, and RevenueCat's event reference lists more than twenty event types. Four should change what a creator is owed: INITIAL_PURCHASE, RENEWAL, NON_RENEWING_PURCHASE, and the CANCELLATION carrying a cancel_reason of CUSTOMER_SUPPORT. The rest are funnel signal and entitlement bookkeeping, to be stored and left alone.

Below: every event mapped to a ledger effect, the payload fields worth reading, and a six month worked example for one $9.99 subscriber on a 20 percent deal. Written for engineers wiring RevenueCat into their own commission code.

#What a RevenueCat webhook is, and why commissions depend on it

A RevenueCat webhook is an HTTP POST that RevenueCat sends to your server when a subscription changes state, carrying a single JSON event object and an api_version string. It is the only server side record of the money. An affiliate ledger built on client side purchase callbacks drifts the first time a renewal fires while the app is closed.

RevenueCat's webhook documentation sets the rules of engagement. Your endpoint returns a 200 status code; anything else is treated as a failure, and RevenueCat "will retry later (up to 5 times) with an increasing delay (5, 10, 20, 40, and 80 minutes)". Most events arrive within 5 to 60 seconds of the underlying transaction. Cancellations are slower, and the docs allow up to two hours. If your handler has not responded in 60 seconds, RevenueCat disconnects.

Authorization is a header you configure in the dashboard, and RevenueCat also signs the raw body with HMAC-SHA256 in an X-RevenueCat-Webhook-Signature header. Enforce one of them on every request. An unauthenticated RENEWAL endpoint lets anyone mint commissions in your database.

The payload is wide. Our normalizer declares eleven fields and ignores the rest, because parsing fields you never use is how a parser throws on an event carrying money. If you read three fields, read id, type and period_type; the rest refine amount and identity.

Field names and types verified against RevenueCat's event types and fields reference on 2026-09-12.

#Every RevenueCat event, and whether it is commissionable

Four RevenueCat events move an affiliate balance in normal operation: INITIAL_PURCHASE with a paid period_type, RENEWAL, NON_RENEWING_PURCHASE, and CANCELLATION carrying cancel_reason of CUSTOMER_SUPPORT, which is how a refund arrives. A fifth, REFUND_REVERSED, moves it back. Everything else in RevenueCat's reference is funnel data or entitlement state.

Two rules are built into the table below. An event that grants or revokes access is not an event that moves cash, and an event reporting an intention (CANCELLATION, PRICE_INCREASE_CONSENT_REQUIRED, INVOICE_ISSUANCE) is never the one you pay on. Pay on charges, reverse on refunds, record everything else as state.

Event names and descriptions checked against RevenueCat's event types and fields reference on 2026-09-12.

Our normalizer returns null for every type it does not act on, and stores the raw payload anyway: an unmapped event should be inert and inspectable, never guessed at. The row worth auditing in any mapping table, ours included, is the refund row. RevenueCat's reference has no type named REFUND, so a table listing one describes a delivery that never arrives while the real refund lands in the CANCELLATION branch and is ignored. We found exactly that in our own normalizer while writing this, and the audit that followed turned up two more billing integrations with the same shape of mistake. A mapping key nobody sends fails silently, and the test written from the same assumption passes.

#INITIAL_PURCHASE and the trial trap

INITIAL_PURCHASE fires on the first purchase of a subscription, whether or not money changed hands. The period_type field decides which happened. TRIAL means a free trial opened at a price of 0. NORMAL, INTRO and PREPAID mean the store charged the customer. PROMOTIONAL means you granted the entitlement yourself.

The shape RevenueCat sends, trimmed to the deciding fields. Full version on their sample events page.

{
  "event": {
    "type": "INITIAL_PURCHASE",
    "id": "12345678-1234-1234-1234-123456789012",
    "app_user_id": "1234567890",
    "product_id": "com.subscription.weekly",
    "period_type": "TRIAL",
    "price": 0,
    "price_in_purchased_currency": 0,
    "currency": "USD",
    "environment": "PRODUCTION",
    "store": "APP_STORE",
    "purchased_at_ms": 1658726374000,
    "expiration_at_ms": 1659331174000
  },
  "api_version": "1.0"
}

That payload should produce a funnel row, not a payable one. Our normalizer branches on those two fields and downgrades the type before the amount is computed:

let type = TYPE_MAP[e.type];
if (e.type === "INITIAL_PURCHASE" && e.period_type === "TRIAL") {
  type = "trial_start";
}

The amount is then forced to zero rather than trusted from the payload, because a store reporting a non-zero price on a trial should not be able to create a payable balance. A unit test pins both halves: type trial_start, amount 0.

The conversion is a separate delivery. RevenueCat's common webhook flows page ends the trial path with a RENEWAL carrying is_trial_conversion set to true. Pay on that one.

Commissioning trial starts is a mistake in almost every creator deal, and the arithmetic is why. 400 trial starts converting at 35 percent produce 140 paid subscriptions worth $2.00 each, so $280. A $0.50 per trial bounty on the same traffic costs $200 before a single renewal, and pays the same at a 4 percent conversion rate as at 35. Pay per trial only against a cap and a conversion floor.

#RENEWAL is where recurring commission actually accrues

RENEWAL fires when an existing subscription renews or a lapsed customer resubscribes, and on a recurring creator deal it produces most of the money. It also fires on trial conversion and after a billing failure recovers inside a grace period, which makes it the busiest path in a commission engine.

Two price fields arrive on the same payload and they are not interchangeable. RevenueCat's reference defines price as the transaction price converted to USD and price_in_purchased_currency as the price in the currency the customer paid, with currency holding the ISO 4217 code. Our normalizer prefers the second and falls back to the first:

const priceUnits = e.price_in_purchased_currency ?? e.price ?? 0;
const amountUsdCents = Math.max(0, Math.round(priceUnits * 100));

That keeps your numbers reconcilable against store reports, which are denominated in what the customer paid. It also means the integer you store is not always USD, so the currency code has to travel with the amount and conversion happens once, at payout, at a recorded rate. An amount field named for a currency it does not always hold reconciles fine for a year and then does not.

The commission itself is arithmetic on cents. Our webhook reference gives the formula as amount_usd_cents × rate_bps / 10000, rate snapshotted at the event. On a $9.99 plan at 20 percent that is 999 × 2000 / 10000, or 199.8 cents. Pick a rounding rule and write it down: rounding to 200 rather than truncating to 199 costs 0.8 cents per renewal, 9.6 cents across a 12 month recurrence, per subscriber.

Cap recurrence on renewal_number, documented as renewals completed starting at 1. A 12 month deal on a $9.99 plan tops out at 12 payable events and $24.00. Snapshot the rate on the first event; reading the current rate on every renewal means changing an affiliate's rate silently rewrites last year's economics.

#CANCELLATION is not the end of the money

A RevenueCat CANCELLATION means auto renew was switched off. It does not mean access ended, and with one exception it does not mean money came back. RevenueCat's flows page is explicit: "At the end of the billing cycle, an EXPIRATION webhook is sent and entitlements are revoked." Until then the subscriber is still paying.

The cancel_reason field carries the distinction, and it is the field most commission code forgets to read.

Values verified against RevenueCat's event types and fields reference on 2026-09-12. Only CUSTOMER_SUPPORT touches the balance.

Our normalizer maps CANCELLATION to a cancel event and EXPIRATION to an expiration event, and neither is commissionable. What both do is stop the recurrence clock: after EXPIRATION there is no future RENEWAL to pay on, so a creator report should show the recurrence closed rather than the earnings withdrawn.

A subscriber on the $9.99 plan at 20 percent who bought on 8 March and cancelled on 1 June after three paid periods earned the creator $6.00. The CANCELLATION reverses none of it, and neither does the 8 June EXPIRATION. A smaller number on the dashboard is a reporting bug, and the one most likely to end a creator relationship: they watch that balance more carefully than you watch your handler.

#Refunds arrive as CANCELLATION, not as a refund event

RevenueCat's event reference contains no type named REFUND. A refunded subscription arrives as a CANCELLATION carrying cancel_reason of CUSTOMER_SUPPORT, which the docs describe as covering Apple support refunds, Google Play refunds through RevenueCat, Amazon support refunds and web billing refunds. REFUND_REVERSED is the separate App Store event for a refund that is later undone.

The scope is narrow, and the reference says so: "In the case of subscription refunds, this event fires only when the latest subscription period is refunded; refunds for earlier periods do not trigger it." A customer refunded three months through Apple support may generate one webhook, not three. Catching the rest needs store report reconciliation, and we know of no way to do it from webhooks alone.

Six rules for the reversal path:

1. Match the refund to a period, not a subscriber: reverse the commission created by the INITIAL_PURCHASE or RENEWAL whose expiration_at_ms covers it.
2. Reverse at the snapshotted rate. Recomputing from the cancellation payload gives you whatever price that event carries.
3. Hold new commissions before they become payable. Our engine writes them pending and matures them after the hold.
4. Reverse a pending commission by cancelling it. Nothing left your account, so nothing is owed back.
5. Reverse a paid commission as a negative on the next statement. Invoicing a creator for money you already sent is a support ticket, not a recovery.
6. Implement REFUND_REVERSED, which is rare enough to skip and rare enough that nobody notices the gap until a creator does.

The hold length is the trade off, and it is arithmetic. Under a 30 day hold, a refund on 20 May against a commission created on 8 May finds it 12 days old and still pending, so the reversal is a status change. The same refund on 20 June finds a commission that matured on 7 June and shipped in the June payout. We default to 30 days: it covers most store refund activity while still paying creators inside a month, and a 7 day hold pushes more reversals into the clawback path, which costs more goodwill than waiting does.

#SUBSCRIBER_ALIAS and TRANSFER can move revenue off the attributed user

SUBSCRIBER_ALIAS and TRANSFER are RevenueCat's identity events, and both can detach revenue from the user you attributed. SUBSCRIBER_ALIAS reports a new App User ID registered for an existing subscriber; the reference marks it deprecated and says new projects do not receive it. TRANSFER reports transactions and entitlements moving between App User IDs.

The harder problem starts before either event fires. RevenueCat's user ids documentation says "the RevenueCat SDK will generate anonymous App User IDs for customers" by default, and one customer may be referenced by several ids, called aliases. Their sample CANCELLATION payload shows it on the wire:

{
  "app_user_id": "$RCAnonymousID:12345678-1234-1234-1234-123456789123",
  "aliases": [
    "$RCAnonymousID:12345678-1234-ABCD-1234-123456789123",
    "user_1234"
  ],
  "original_app_user_id": "$RCAnonymousID:12345678-1234-ABCD-1234-123456789123"
}

The identified id, user_1234, sits in aliases while app_user_id is still anonymous. Code that joins on app_user_id alone finds nothing and pays nobody. It is the most common attribution miss we see behind a working RevenueCat integration and an empty commission table.

Match on the whole identity set instead:

1. Collect app_user_id, original_app_user_id and every entry in aliases into one candidate set.
2. Match an attribution record on any candidate, newest first, inside the window.
3. On TRANSFER, read transferred_from and transferred_to and decide whether attribution follows the entitlement.
4. Re-run the match on the next money event instead of caching a failure. The alias that fixes it may arrive later.

A second route sidesteps the alias graph entirely. Every event carries a subscriber_attributes object, so an affiliate id written on the client before the purchase arrives attached to the money. The mechanics are in getting the affiliate id into the payload.

Our normalizer reads app_user_id and nothing else, and returns null when it is absent. The boundary is deliberate: normalization stays a pure mapping, and identity resolution lives one layer up, where it can see the alias graph and the click history. An identity change can then be replayed against stored events without re-ingesting anything.

We would let attribution follow the transfer, and we hold that loosely. A subscription moving from user_a to user_b keeps firing RENEWAL at $9.99, and the creator who earned it stops receiving $2.00 a month while the revenue continues. The counter argument is that a transfer can be a handover to someone the creator never reached. Pick one, put it in the affiliate terms, and log every TRANSFER.

#Keeping sandbox and TestFlight purchases out of payouts

The environment field is the gate. RevenueCat sets it to SANDBOX or PRODUCTION on every event, and the sandbox documentation says RevenueCat "automatically detects the environment (production vs. sandbox) in which a purchase occurs". There is nothing to configure and no excuse for missing it. Gate at ingest, before attribution runs.

Three signals separate real money from test money, and a commission engine should check all of them.

A missing environment check is worth real money to anyone who notices it. Sandbox subscriptions renew on a compressed schedule, so 52 RENEWAL events are an afternoon's work for one tester. At 20 percent of a $9.99 plan that is 52 × $2.00, or $104.00 of fictional commission in an affiliate's balance, created by your own QA.

TestFlight adds a second problem. RevenueCat's sandbox page notes that store APIs "often do not return accurate prices across regions, including in TestFlight on iOS", so the amounts are not trustworthy either. A build reporting a plausible price is more dangerous than one reporting zero, because plausible numbers survive review.

Store sandbox events rather than dropping them, marked non-payable. The first question anyone asks after wiring a webhook is why their test purchase did not appear, and a dropped event cannot answer it. For the wiring itself our webhook docs point at a smoke command (pnpm --filter @maa/api smoke) that rehearses the loop against the live database and leaves nothing to exclude later.

#Making ingest safe: idempotency, persist before process, retries

Idempotent ingest means a webhook delivered twice produces one stored event and one commission. RevenueCat's webhook documentation warns that "in some rare situations, your application may receive a webhook for the same event more than once", and a retry reuses the same id. A unique constraint on source plus event id is most of the defence.

Click to enlarge

Seven rules, in the order the request hits them:

1. Compare the credential in constant time. A byte by byte early return leaks the secret's prefix to anyone patient enough to time it.
2. Store the raw body before parsing, keyed by source and event id. A parser exception then costs a retry, not a financial event.
3. Return 200 as soon as the payload is durable. RevenueCat disconnects after 60 seconds and treats anything but 200 as a failure.
4. Index the pair, not the event id alone. Two billing sources can issue the same identifier.
5. Normalize in a separate step reading from storage, so a fixed parser can be replayed over yesterday's payloads.
6. Key the commission write on the same pair, so a replay cannot create a second balance entry.
7. Order by event_timestamp_ms, not arrival. RevenueCat's flows page notes a recovery RENEWAL can appear before the BILLING_ISSUE that preceded it.

create unique index events_source_event_id_key
  on events (source, source_event_id);

This is the mapping MyAppAffiliate's ingest implements. The raw payload is persisted before parsing, so a parser bug never loses a financial event, and a re-fired webhook with the same event id produces no second commission, enforced by a unique (source, sourceEventId). The Authorization header is compared in constant time against the SHA-256 stored for your app, and a bad token is recorded and rejected with a 401. Commission is amount_usd_cents × rate_bps / 10000 at a snapshotted rate, attributed to the most recent referral inside the window, created pending and matured after the hold. Endpoint shape: the webhook reference.

We return 200 on a payload we have stored but not yet understood, and we would argue with anyone who does the opposite. A 500 on an event you parsed but failed to save buys five retries and then permanent silence.

#A six month ledger for one subscriber

One subscriber on a $9.99 monthly plan, a 20 percent creator rate, a 12 month recurrence cap and a 30 day hold produces nine RevenueCat webhook events across six months. Four change the affiliate balance. The creator finishes with $4.00 against a maximum of $24.00, and every step below is arithmetic you can recompute.

Click to enlarge

Each commission is 999 × 2000 / 10000, or 199.8 cents, rounded to $2.00. Three credits and one reversal leave $4.00.

Two rows break implementations. On 2 May the billing failure arrives as a pair, BILLING_ISSUE and a CANCELLATION with cancel_reason of BILLING_ERROR, and the recovery is the 8 May RENEWAL; code that pays on both books $4.00 for one charge. On 20 May the refund reverses a commission twelve days old, still inside the hold, so nothing is clawed back from a creator already paid.

The 1 June CANCELLATION and the 8 June EXPIRATION are the quiet test. Neither touches the money. They end the recurrence at renewal_number 3 of a possible 12, so forward looking earnings on this subscriber drop from $18.00 to zero while the earned balance stays at $4.00. Two different numbers, and a dashboard showing only one of them gets argued with.

We show pending and matured as separate columns rather than one balance, because the most common creator question is why a number went down, and the honest answer is usually that it never went up.

#Wire the four money events before anything else

A correct commission ledger needs four handlers and one index. Handle INITIAL_PURCHASE with a paid period_type, RENEWAL, NON_RENEWING_PURCHASE, and CANCELLATION carrying cancel_reason of CUSTOMER_SUPPORT. Store every other event raw and payable to nobody. Add the unique index on source and event id before the first delivery, not after the first duplicate.

Do this next. Open Integrations → Webhooks in the RevenueCat dashboard, send a TEST event at your endpoint, then send it again and check that your database holds exactly one row for that id. Until a duplicate has bounced off a unique constraint in your own environment, you have a plan rather than idempotency. The attribution half of the pipeline, joining a click to an app_user_id in the first place, is in the full RevenueCat attribution setup.