Fanvue API Documentation

When a fan pays for a checkout sale with Buy Now, Pay Later (BNPL), Fanvue is paid the full amount upfront by the BNPL provider. The fan then repays the BNPL provider over N installments. These events track that repayment schedule. They are delivered in the Standard-Webhooks envelope; the fields below describe the data object.

BNPL is currently powered by Splitit.

Event (`type`)	Resource	Fires when
`checkout_link.installment.paid`	installment	A BNPL repayment (installment `2..N`) is collected
`checkout_link.installment.failed`	installment	A BNPL repayment attempt fails
`checkout_link.plan.completed`	plan	A BNPL plan is fully paid off

A fan repaying an installment is financing movement, not a new Fanvue sale. Fanvue has already been paid in full at checkout. The initial financed sale arrives as a normal checkout_link.payment.succeeded with paid_in_full: false and installment: { number: 1, of: N }. Installments 2..N then arrive as checkout_link.installment.paid, so do not count them as additional revenue.

Currency

Amounts are integers in the minor units of the resource’s currency (ISO 4217). For BNPL, the processing currency is the currency the fan is charged; the BNPL provider settles to Fanvue in USD. Reconcile installment amounts in the fan’s processing currency, not in the creator’s payout currency.

Installment resource

Shared by checkout_link.installment.paid and checkout_link.installment.failed.

Field	Type	Description
`object`	string	Always `"installment"`
`id`	string	Installment id
`status`	string	`paid` \| `failed`
`reason`	string \| null	On `failed`: `charge_failed` \| `retry_failed` \| `delayed`; `null` when `paid`
`installment_number`	integer	Which installment this is (`2..N`)
`number_of_installments`	integer	Total installments in the plan (`N`)
`amount`	integer	This installment’s amount in minor units
`currency`	string \| null	ISO 4217 currency code (the fan’s processing currency)
`outstanding_amount`	integer \| null	Amount still outstanding on the plan after this installment, in minor units
`process_date`	string \| null	ISO 8601 date the installment was (or was to be) processed
`plan_id`	string	Id of the parent BNPL plan
`payment_id`	string	Invoice number of the original financed payment
`checkout_link`	object	`{ uuid, name, product_uuid, product_price_uuid }`
`purchaser`	object	`{ uuid, email }` of the fan (`email` may be `null`)
`creator`	object	`{ uuid }` of the creator
`metadata`	object	Your passthrough metadata map

reason tells the three failure paths apart on checkout_link.installment.failed: charge_failed (the scheduled charge was declined), retry_failed (a retry of a previously failed charge was declined), and delayed (the charge was deferred rather than declined outright).

Example: `checkout_link.installment.paid`

{
  "id": "f1a2b3c4-aaaa-4a2b-9c3d-aaaaaaaaaaaa",
  "type": "checkout_link.installment.paid",
  "timestamp": "2026-07-09T08:39:33.139Z",
  "data": {
    "object": "installment",
    "id": "inst_2",
    "status": "paid",
    "reason": null,
    "installment_number": 2,
    "number_of_installments": 3,
    "amount": 10000,
    "currency": "EUR",
    "outstanding_amount": 10000,
    "process_date": "2026-07-09T08:39:33.000Z",
    "plan_id": "plan_abc",
    "payment_id": "FV-12350",
    "checkout_link": {
      "uuid": "ck-uuid",
      "name": "Premium Bundle",
      "product_uuid": "prod-uuid",
      "product_price_uuid": "pp-uuid"
    },
    "purchaser": { "uuid": "fan-uuid", "email": "fan@example.com" },
    "creator": { "uuid": "creator-uuid" },
    "metadata": { "affiliate_id": "aff_123", "campaign": "spring" }
  }
}

Example: `checkout_link.installment.failed`

{
  "id": "f1a2b3c4-bbbb-4a2b-9c3d-aaaaaaaaaaaa",
  "type": "checkout_link.installment.failed",
  "timestamp": "2026-08-09T08:39:33.139Z",
  "data": {
    "object": "installment",
    "id": "inst_3",
    "status": "failed",
    "reason": "charge_failed",
    "installment_number": 3,
    "number_of_installments": 3,
    "amount": 10000,
    "currency": "EUR",
    "outstanding_amount": 10000,
    "process_date": "2026-08-09T08:39:33.000Z",
    "plan_id": "plan_abc",
    "payment_id": "FV-12350",
    "checkout_link": {
      "uuid": "ck-uuid",
      "name": "Premium Bundle",
      "product_uuid": "prod-uuid",
      "product_price_uuid": "pp-uuid"
    },
    "purchaser": { "uuid": "fan-uuid", "email": "fan@example.com" },
    "creator": { "uuid": "creator-uuid" },
    "metadata": { "affiliate_id": "aff_123", "campaign": "spring" }
  }
}

Plan resource

checkout_link.plan.completed fires once, when the final installment of a BNPL plan is collected and the plan is fully paid off.

Field	Type	Description
`object`	string	Always `"plan"`
`id`	string	BNPL plan id
`status`	string	Always `"completed"`
`number_of_installments`	integer	Total installments in the plan (`N`)
`total_amount`	integer	Total financed amount in minor units
`currency`	string \| null	ISO 4217 currency code (the fan’s processing currency)
`payment_id`	string	Invoice number of the original financed payment
`checkout_link`	object	`{ uuid, name, product_uuid, product_price_uuid }`
`purchaser`	object	`{ uuid, email }` of the fan (`email` may be `null`)
`creator`	object	`{ uuid }` of the creator
`metadata`	object	Your passthrough metadata map

Example: `checkout_link.plan.completed`

{
  "id": "f1a2b3c4-cccc-4a2b-9c3d-aaaaaaaaaaaa",
  "type": "checkout_link.plan.completed",
  "timestamp": "2026-09-09T08:39:33.139Z",
  "data": {
    "object": "plan",
    "id": "plan_abc",
    "status": "completed",
    "number_of_installments": 3,
    "total_amount": 30000,
    "currency": "EUR",
    "payment_id": "FV-12350",
    "checkout_link": {
      "uuid": "ck-uuid",
      "name": "Premium Bundle",
      "product_uuid": "prod-uuid",
      "product_price_uuid": "pp-uuid"
    },
    "purchaser": { "uuid": "fan-uuid", "email": "fan@example.com" },
    "creator": { "uuid": "creator-uuid" },
    "metadata": { "affiliate_id": "aff_123", "campaign": "spring" }
  }
}

Overview

Creator events

Checkout

App webhooks

Legacy events (deprecated)

Checkout BNPL Installments

Currency

Installment resource

Example: `checkout_link.installment.paid`

Example: `checkout_link.installment.failed`

Plan resource

Example: `checkout_link.plan.completed`

​Currency

​Installment resource

​Example: checkout_link.installment.paid

​Example: checkout_link.installment.failed

​Plan resource

​Example: checkout_link.plan.completed

Currency

Installment resource

Example: `checkout_link.installment.paid`

Example: `checkout_link.installment.failed`

Plan resource

Example: `checkout_link.plan.completed`