Fanvue API Documentation

Refund and dispute events report when money on a creator’s on-platform sale is returned or contested. They have no legacy flat equivalent; before them, only checkout-link payments emitted refund and dispute events.

Event (`type`)	Resource	Fires when
`creator.refund.created`	refund	An on-platform payment is refunded
`creator.dispute.flagged`	dispute	An early pre-chargeback alert is raised
`creator.dispute.created`	dispute	A formal dispute (chargeback) is opened

All three require the read:creator scope. Each event arrives in the envelope, and the tables below describe data. Amounts are integers in USD cents; see Units and currency. Get spending reversal data is the API view of the same reversals.

Refund resource

Field	Type	Description
`object`	string	Always `"refund"`
`id`	string	Reversal invoice identifier
`payment_id`	string	Invoice number of the original (refunded) payment
`amount`	integer	Refunded amount in minor units (positive)
`currency`	string \| null	ISO 4217 currency code
`reason`	string \| null	Reserved; always `null` on this event
`full_amount`	boolean	Always `true`
`created_at`	string \| null	ISO 8601 time the refund was created
`purchaser`	object	The buyer, see Purchaser. `email` is always `null`
`creator`	object	`{ uuid }` of the creator
`metadata`	object	Your passthrough metadata map, echoed from the original payment

Fanvue reverses the entire original payment (partial refunds are not modelled), so full_amount is always true and amount equals the original gross. The refund resource carries no client_reference_id, so metadata is the only attribution that survives onto this event.

Example: `creator.refund.created`

{
  "id": "f1a2b3c4-9999-4a2b-9c3d-aaaaaaaaaaaa",
  "type": "creator.refund.created",
  "timestamp": "2026-06-09T08:40:00.000Z",
  "data": {
    "object": "refund",
    "id": "FVC-12345",
    "payment_id": "FV-12345",
    "amount": 1999,
    "currency": "USD",
    "reason": null,
    "full_amount": true,
    "created_at": "2026-06-09T08:40:00.000Z",
    "purchaser": {
      "uuid": "fan-uuid",
      "email": null,
      "handle": "janed",
      "display_name": "Jane D"
    },
    "creator": { "uuid": "creator-uuid" },
    "metadata": { "campaign": "spring-promo" }
  }
}

Dispute resource

creator.dispute.flagged and creator.dispute.created share the dispute resource, and status tells them apart.

creator.dispute.flagged (status: "warning") is an early chargeback warning. A dispute has been signalled as likely, but no formal chargeback has been filed yet. Use it to prepare evidence or refund pre-emptively.
creator.dispute.created (status: "open") is the formal dispute (chargeback) being opened against the payment.

The same payment can produce a flagged event and later a created event.

Field	Type	Description
`object`	string	Always `"dispute"`
`id`	string	Processor dispute / alert id
`status`	string	`warning` on `creator.dispute.flagged`, `open` on `creator.dispute.created`
`amount`	integer \| null	Disputed amount in minor units
`currency`	string \| null	ISO 4217 currency code
`reason`	string \| null	Dispute reason, if the processor provided one
`created_at`	string \| null	ISO 8601 time the dispute was reported
`payment`	object	The disputed payment: `{ id, transaction_id, purchaser }`. `purchaser` is the same shape as on the refund
`creator`	object	`{ uuid }` of the creator
`metadata`	object	Your passthrough metadata map, echoed from the original payment

The dispute resource carries no source and no client_reference_id, and the reporting provider is not exposed on this event.

Example: `creator.dispute.created`

{
  "id": "f1a2b3c4-aaaa-4a2b-9c3d-aaaaaaaaaaaa",
  "type": "creator.dispute.created",
  "timestamp": "2026-06-09T08:41:00.000Z",
  "data": {
    "object": "dispute",
    "id": "dp_abc123",
    "status": "open",
    "amount": 1999,
    "currency": "USD",
    "reason": "fraudulent",
    "created_at": "2026-06-09T08:41:00.000Z",
    "payment": {
      "id": "FV-12345",
      "transaction_id": "txn_abc",
      "purchaser": {
        "uuid": "fan-uuid",
        "email": null,
        "handle": "janed",
        "display_name": "Jane D"
      }
    },
    "creator": { "uuid": "creator-uuid" },
    "metadata": { "campaign": "spring-promo" }
  }
}

The creator.dispute.flagged event uses the identical shape with "type": "creator.dispute.flagged" and "status": "warning". Treat it as the moment to prepare evidence before a formal chargeback is filed.

Receiving events

Creator events

Checkout link events

App events

Legacy events (deprecated)

Creator refund and dispute events

Refund resource

Example: `creator.refund.created`

Dispute resource

Example: `creator.dispute.created`

​Refund resource

​Example: creator.refund.created

​Dispute resource

​Example: creator.dispute.created

Refund resource

Example: `creator.refund.created`

Dispute resource

Example: `creator.dispute.created`