> ## Documentation Index
> Fetch the complete documentation index at: https://api.fanvue.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Checkout webhooks overview

> Real-time webhook events for a creator’s Fanvue checkout-link sales: payments, subscriptions, refunds, disputes, BNPL installments, and payouts.

Checkout webhooks notify your backend in real time about the commercial activity on a creator's checkout links: payments, subscriptions, refunds, disputes, BNPL installments, and payouts. They are designed for integrators who need to reconcile Fanvue sales against their own systems (a CRM, a fulfillment flow, an affiliate ledger, an accounting tool).

They are **scoped to a creator's checkout-link activity**, so you receive only the events relevant to your integration, not the creator's whole platform feed.

<Note>
  Checkout webhooks use a different payload shape from the platform event webhooks (New Follower, Purchase Received, etc.). They wrap a resource object in a **Standard-Webhooks envelope**. See [Event envelope](#event-envelope). The platform event webhooks keep their original flat payloads.
</Note>

## One subscription, both webhook families

Checkout webhooks and the [platform event webhooks](/docs/webhooks/webhooks-overview) (`follow.new`, `message.*`, `purchase.new`, `subscription.*`, `tip.new`) are delivered over the **same creator-tenant subscription**. There is no separate receiver to configure for each family.

Which events actually reach you depends on how you subscribed (see [Configuring checkout webhooks](/docs/checkout/configuring)):

* **Zapier**: each Zap subscribes to a single trigger, so add one Zap per event you want to act on.
* **API or app**: you choose exactly which events to subscribe to, so to receive both families include the platform event types **and** the `checkout_link.*` / `payout.paid` types. A subscription only delivers the events it was created with, so one set up for platform events alone won't start sending checkout events until you add them.

<Note>
  Two entry points, depending on who you are. **App builders** add an endpoint and tick the events (including the Checkout links group) in the App Store **Events** tab; see [Webhooks Overview](/docs/webhooks/webhooks-overview). **Creators and no-code integrators** use **Configure webhooks** in the dashboard (Zapier or the connector API), see [Configuring checkout webhooks](/docs/checkout/configuring). Both authorize with `read:creator` and deliver the same events to the creator's tenant.
</Note>

Because several event types can arrive at one endpoint, **branch on the event `type`** (and, for checkout events, on `data.object`) to route each delivery to the right handler.

Next steps:

* [Configuring checkout webhooks](/docs/checkout/configuring): set up a receiver via Zapier or the API, and verify signatures.
* [Attribution](/docs/checkout/attribution): attach your own `client_reference_id` and `metadata` to every event.

## Amounts and currency

All monetary amounts are integers in the currency's **minor units** (for USD, cents, so `9999` means `$99.99`). Each resource carries its own `currency` (ISO 4217), which may be `null` when not yet known.

For Buy Now, Pay Later (BNPL) sales, the processing currency is the currency the **fan is charged**; the BNPL provider settles to Fanvue in USD. See [BNPL installments](/docs/checkout/installments).

## Event envelope

Every checkout webhook is delivered as an HTTP `POST` with this envelope:

```json theme={null}
{
  "id": "f1a2b3c4-1111-4a2b-9c3d-aaaaaaaaaaaa",
  "type": "checkout_link.payment.succeeded",
  "timestamp": "2026-06-09T08:39:33.139Z",
  "data": { "object": "payment", "...": "resource fields" }
}
```

* `id`: unique event id, stable across delivery retries (use it to dedupe). Also delivered as the Standard-Webhooks `webhook-id`. Every `checkout_link.*` and `payout.*` event carries a per-event id, so it is safe as an idempotency key, see [Delivery, Retries and Idempotency](/docs/webhooks/delivery-and-idempotency#deduplicating-events).
* `type`: the event name (one of the topics in [Available events](#available-events)).
* `timestamp`: ISO 8601 time the event was emitted.
* `data`: the resource object. `data.object` tells you the resource type (`payment`, `subscription`, `refund`, `dispute`, `installment`, `plan`, `payout`).

Fields inside `data` are **snake\_case**.

## Available events

All checkout events require the `read:creator` OAuth scope. Each group below links to a reference page with full field definitions and example payloads.

### Payments ([reference](/docs/checkout/payments))

* `checkout_link.payment.pending`: a checkout payment is awaiting confirmation
* `checkout_link.payment.succeeded`: a checkout payment succeeds (one-off, initial subscription, or renewal)
* `checkout_link.payment.failed`: a checkout payment fails

### Subscriptions ([reference](/docs/checkout/subscriptions))

A *subscription* is a fan's active, recurring access to a product sold through a checkout link.

* `checkout_link.subscription.activated`: a subscription becomes active
* `checkout_link.subscription.deactivated`: a subscription ends (expired or otherwise deactivated)
* `checkout_link.subscription.cancel_at_period_end_changed`: auto-renew is turned off or back on

### Refunds and disputes ([reference](/docs/checkout/refunds-disputes))

* `checkout_link.refund.created`: a checkout payment is refunded
* `checkout_link.dispute.flagged`: an early chargeback warning, before a formal dispute
* `checkout_link.dispute.created`: a formal dispute (chargeback) is opened

### BNPL installments ([reference](/docs/checkout/installments))

Repayments on a Buy Now, Pay Later (BNPL) financed sale are financing movement, not new sales (see [BNPL financing](#bnpl-financing)).

* `checkout_link.installment.paid`: a BNPL repayment (installment `2..N`) is collected
* `checkout_link.installment.failed`: a BNPL repayment attempt fails
* `checkout_link.plan.completed`: a BNPL plan is fully paid off

### Payouts ([reference](/docs/checkout/payouts))

* `payout.paid`: a creator payout is paid out (creator-level, not link-scoped)

## BNPL financing

<Info>
  BNPL is currently powered by Splitit.
</Info>

When a fan finances a checkout sale with Buy Now, Pay Later (BNPL), **Fanvue is paid in full upfront**. The fan repays the BNPL provider over time. So:

* The sale is a normal [`checkout_link.payment.succeeded`](/docs/checkout/payments) with `paid_in_full: false` and `installment: { number: 1, of: N }`.
* The later repayments (installments `2..N`) arrive as [`checkout_link.installment.paid`](/docs/checkout/installments) (or `.failed`), **not** as new `payment.succeeded` events.
* When the plan is fully repaid you receive [`checkout_link.plan.completed`](/docs/checkout/installments).

Treat installment repayments as financing movement, **not** additional revenue, so you don't double-count the sale.