> ## 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.
# Create checkout links
> Create a Fanvue checkout link with POST /checkout-links or the Checkout Links page, set price, billing cycle and tax behaviour, and share it.
A checkout link is a Fanvue-hosted payment page for one product. By the end of this page you'll have created one with `POST /checkout-links` and have its shareable URL. Fans pay by card, Apple Pay, Google Pay, their Fanvue wallet, Pix or BNPL (buy now, pay later) instalments, and they don't need a Fanvue account.
You need:
* a creator account with checkout links enabled
* an access token with `write:creator`, plus the creator permission `monetization:manage` when you create links for a creator you manage
If you'd rather not write code, open the [Checkout Links page](/docs/checkout/dashboard) in Fanvue, create a product with a one-off or subscription price, and copy the link from its row.
## Create a link with the API
`POST /checkout-links` creates a link for the authenticated creator from a product and a price. Agencies and apps acting for a creator call `POST /creators/{creatorUserUuid}/checkout-links` with the same body. Amounts are integers in [USD minor units](/docs/payments/overview#units-and-currency), so `1999` is \$19.99.
```bash theme={null}
curl -X POST "https://api.fanvue.com/checkout-links" \
-H "Authorization: Bearer " \
-H "X-Fanvue-API-Version: 2025-06-26" \
-H "Content-Type: application/json" \
-d '{
"source": {
"kind": "new_product",
"product": { "name": "Coaching call" },
"price": { "amount": 1999, "currency": "USD", "isRecurring": false }
},
"redirectUrl": "https://example.com/thanks"
}'
```
```bash theme={null}
curl -X POST "https://api.fanvue.com/checkout-links" \
-H "Authorization: Bearer " \
-H "X-Fanvue-API-Version: 2025-06-26" \
-H "Content-Type: application/json" \
-d '{
"source": {
"kind": "new_product",
"product": { "name": "Members club" },
"price": {
"amount": 2500,
"currency": "USD",
"isRecurring": true,
"cycleLength": 1,
"cycleUnit": "month",
"taxBehavior": "inclusive"
}
},
"description": "Spring campaign link"
}'
```
The response is `201` with the link. Share the `url`.
```json theme={null}
{
"uuid": "b3c4d5e6-7f8a-4b9c-8d0e-1f2a3b4c5d6e",
"name": "Coaching call",
"description": null,
"url": "https://www.fanvue.com/checkout/fvcl_4WqZz1kXo9DdPp2sT7yRfM",
"price": 1999,
"currency": "USD",
"isRecurring": false,
"cycleLength": null,
"cycleUnit": null,
"productUuid": "6f1d2c3b-4a5e-4f60-9b71-82c93d04e5f6",
"productPriceUuid": "0a9b8c7d-6e5f-4a4b-8c3d-2e1f0a9b8c7d",
"taxBehavior": "exclusive",
"displayCurrency": "localised",
"status": "active",
"createdAt": "2026-03-02T10:15:00.000Z"
}
```
### Request body
| Field | Required | Value |
| - | - | - |
| `source.kind` | Yes | `new_product` creates a product and price; `existing_product` adds a price to a product you own; `existing_price` sells a price that already exists |
| `source.product.name` | With `new_product` | 1 to 100 characters, unique among the creator's products (case-insensitive) |
| `source.product.description` | No | Up to 500 characters |
| `source.productUuid` | With `existing_product` | UUID of the product to price |
| `source.productPriceUuid` | With `existing_price` | UUID of the price to sell |
| `source.price.amount` | With `new_product` or `existing_product` | Integer minor units. `0` creates a free link; a paid link is `300` to `1000000` (\$3 to \$10,000) |
| `source.price.currency` | No | Three-letter ISO 4217 code, default `USD` |
| `source.price.isRecurring` | Yes, inside `price` | `true` bills on a cycle and needs a non-zero amount plus `cycleLength` and `cycleUnit` |
| `source.price.cycleLength` | With `isRecurring: true` | Positive integer |
| `source.price.cycleUnit` | With `isRecurring: true` | `day`, `week`, `month` or `year` |
| `source.price.taxBehavior` | No | `exclusive` adds tax on top of the amount; `inclusive` carves tax out of it. Omitted applies the creator's checkout default |
| `description` | No | Internal note up to 500 characters, shown in the Checkout Links page only |
| `redirectUrl` | No | `http` or `https` URL the fan lands on after paying |
### Response fields
| Field | Type | Meaning |
| - | - | - |
| `uuid` | string | Checkout link UUID |
| `name` | string | Creator-internal label, derived from the product name |
| `description` | string or `null` | Creator-internal note. Fans never see it |
| `url` | string or `null` | The shareable checkout URL |
| `price` | integer | Minor units. `0` for free links |
| `currency` | string | ISO 4217 code of the price |
| `isRecurring` | boolean | `true` when purchases create a subscription |
| `cycleLength` | integer or `null` | Billing cycle length. `null` for one-off prices |
| `cycleUnit` | `day`, `week`, `month`, `year` or `null` | Billing cycle unit |
| `productUuid` | string or `null` | Product the link sells |
| `productPriceUuid` | string or `null` | Product price the link sells |
| `taxBehavior` | `exclusive` or `inclusive` | Tax basis stamped on the price at creation |
| `displayCurrency` | `localised` or `usd` | Currency the checkout page shows the fan. `localised` uses the fan's local currency where a rate exists |
| `status` | `active` or `disabled` | `disabled` links reject checkout until re-enabled |
| `createdAt` | string | ISO 8601 creation time |
`displayCurrency` comes from the creator's checkout configuration, so you can't set it in the request. Links have no expiry. A link stays `active` until you disable or delete it.
### Errors
| Status | Message | Cause |
| - | - | - |
| `403` | `Checkout links are not enabled for this creator` | Available to creators who have checkout links enabled |
| `403` | `taxBehavior is not enabled for this creator` | You sent a `taxBehavior` other than `exclusive` for an account without checkout pricing configuration. Fanvue refuses the request rather than coercing the value |
| `400` | `Recurring prices require a non-zero amount` | `isRecurring: true` with `amount: 0` |
| `400` | `Recurring prices require cycleLength and cycleUnit` | `isRecurring: true` without a cycle |
| `400` | `A product with this name already exists` | Duplicate `source.product.name` |
| `404` | `Product not found` or `Product price not found` | Unknown `productUuid` or `productPriceUuid` |
## Attach your own references
Append `client_reference_id` and `metadata[]` query parameters to the URL you share. Fanvue stores them on the payment and echoes them on every related webhook. [Checkout attribution](/docs/checkout/attribution) has the limits.
```text theme={null}
https://www.fanvue.com/checkout/fvcl_4WqZz1kXo9DdPp2sT7yRfM?client_reference_id=order-123&metadata[campaign]=spring
```
## List, disable and delete links
`GET /v1/checkout-links` lists the creator's links newest first with cursor pagination: pass `size` (1 to 50, default 15) and echo `nextCursor` back as `cursor`. The v0 endpoint pages with `page` and `size` instead.
```bash theme={null}
curl "https://api.fanvue.com/v1/checkout-links?size=15" \
-H "Authorization: Bearer " \
-H "X-Fanvue-API-Version: 2025-06-26"
```
`PATCH /checkout-links/{uuid}` with `{ "status": "disabled" }` stops the checkout page, and you can re-enable it later. `DELETE /checkout-links/{uuid}` is terminal. A deleted link can't be re-enabled, though its past payments stay readable on the payments endpoints.
To do any of this for a creator you manage, use the same operations under `/creators/{creatorUserUuid}/checkout-links`. The list needs `read:creator` plus the creator permission `monetization:read`; writes need `write:creator` plus `monetization:manage`.
## Next steps
Each sale emits [checkout link payment events](/docs/checkout/payments), and [Reconcile checkout payments](/docs/checkout/reconcile) shows how to read payments back and request refunds. To receive the events, [subscribe an app to webhooks](/docs/webhooks/subscribing).
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.