Checkout links

Create a checkout link

Creates a link a buyer can pay.

POST

POST/checkout/organizations/{orgId}/links

IDEMPOTENCY_KEY=$(uuidgen)  # new key per call; reuse it only to retry this exact request
curl -s -X POST "$AVVIO_BASE_URL/checkout/organizations/$AVVIO_ORG_ID/links" \
  -H "x-api-key: $AVVIO_API_KEY" \
  -H "Idempotency-Key: $IDEMPOTENCY_KEY" \
  -H "content-type: application/json" \
  -d '{
        "productId": "2a7b8c9d-1e2f-4a5b-8c9d-0e1f2a3b4c5d",
        "successUrl": "https://example.com/thanks",
        "cancelUrl": "https://example.com/pricing",
        "clientReferenceId": "order_1042",
        "metadata": {
          "orderId": "1042"
        },
        "publish": true
      }'

const idempotencyKey = crypto.randomUUID(); // new key per call; reuse it only to retry this exact request

const res = await fetch(`${process.env.AVVIO_BASE_URL}/checkout/organizations/${process.env.AVVIO_ORG_ID}/links`, {
  method: 'POST',
  headers: {
    'x-api-key': process.env.AVVIO_API_KEY,
    'Idempotency-Key': idempotencyKey,
    'content-type': 'application/json',
  },
  body: JSON.stringify({
    "productId": "2a7b8c9d-1e2f-4a5b-8c9d-0e1f2a3b4c5d",
    "successUrl": "https://example.com/thanks",
    "cancelUrl": "https://example.com/pricing",
    "clientReferenceId": "order_1042",
    "metadata": {
      "orderId": "1042"
    },
    "publish": true
  }),
});
console.log(res.status, await res.json());

import os
import uuid
import requests

idempotency_key = str(uuid.uuid4())  # new key per call; reuse it only to retry this exact request

res = requests.post(
    f"{os.environ['AVVIO_BASE_URL']}/checkout/organizations/{os.environ['AVVIO_ORG_ID']}/links",
    headers={
        "x-api-key": os.environ["AVVIO_API_KEY"],
        "Idempotency-Key": idempotency_key,
    },
    json={
        "productId": "2a7b8c9d-1e2f-4a5b-8c9d-0e1f2a3b4c5d",
        "successUrl": "https://example.com/thanks",
        "cancelUrl": "https://example.com/pricing",
        "clientReferenceId": "order_1042",
        "metadata": {
            "orderId": "1042"
        },
        "publish": True
    },
)
print(res.status_code, res.json())

201Created

{
  "id": "4f1c2a9e-8f7d-4c3b-9a2e-6b5d4c3f2a10",
  "slug": "7e2a9c4b1d0f",
  "status": "sent",
  "shareUrl": "https://business.avvio.xyz/i/7e2a9c4b1d0f",
  "fromName": "Northstar Consulting",
  "currency": "USD",
  "total": "150.00",
  "clientReferenceId": "order_1042",
  "metadata": {
    "orderId": "1042"
  },
  "product": {
    "id": "2a7b8c9d-1e2f-4a5b-8c9d-0e1f2a3b4c5d",
    "name": "Consulting (60 min)"
  },
  "received": null,
  "successUrl": "https://example.com/thanks",
  "cancelUrl": "https://example.com/pricing",
  "createdAt": "2026-09-12T09:58:00.000Z",
  "expiresAt": null,
  "source": "api"
}

{
  "type": "BAD_REQUEST",
  "status": 400,
  "detail": "Send either productId or currency and items, never both.",
  "requestId": "req-apb",
  "message": "Send either productId or currency and items, never both.",
  "statusCode": 400
}

{
  "type": "UNAUTHORIZED",
  "status": 401,
  "detail": "Invalid API key",
  "resolution": "Check the API key was copied whole and has not been revoked.",
  "requestId": "req-9bz",
  "message": "Invalid API key",
  "statusCode": 401
}

{
  "type": "FORBIDDEN",
  "status": 403,
  "detail": "This API key cannot access that organization",
  "resolution": "This key is scoped to a different organization.",
  "requestId": "req-9d0",
  "message": "This API key cannot access that organization",
  "statusCode": 403
}

{
  "type": "IDEMPOTENCY_KEY_CONFLICT",
  "status": 409,
  "detail": "This Idempotency-Key was already used with a different request body. Use a new key for a different request.",
  "resolution": "This key was used with a different body. Do not retry — use a new key for a new request.",
  "requestId": "req-9g3",
  "message": "This Idempotency-Key was already used with a different request body. Use a new key for a different request.",
  "statusCode": 409
}

{
  "type": "RATE_LIMITED",
  "status": 429,
  "detail": "ThrottlerException: Too Many Requests",
  "resolution": "Back off and retry after the Retry-After interval.",
  "requestId": "req-9e1",
  "message": "ThrottlerException: Too Many Requests",
  "statusCode": 429
}

{
  "type": "INTERNAL",
  "status": 500,
  "detail": "Internal server error",
  "resolution": "Nothing was recorded under this Idempotency-Key, so retrying with the same key is safe. If it persists, send us the requestId.",
  "requestId": "req-apd",
  "message": "Internal server error",
  "statusCode": 500
}

Path parameters

orgIdstringRequired
The opaque organization id issued to you, normally CUID-shaped (for example cmsx…). It is not an org_-prefixed alias. Pass it unchanged in every organization-scoped path.

Headers

Idempotency-KeystringRequired
A unique value per logical operation, 1-255 chars of A-Z a-z 0-9 _ . : -.
More
Reuse it to retry. Same key with the same body replays the stored response; same key with a different body is a 409, because answering with the first call's result would hand you a receipt for a payout you did not request. A 4xx releases the key, so you can fix the body and reuse it.

Reuse it; do not generate one per attempt. A key minted per attempt defeats replay entirely: every retry looks like a new request, so every retry pays. We also watch for an identical body arriving under a different key within 15 minutes and refuse it with DUPLICATE_REQUEST_DETECTED.

Records are kept for 7 days. That is a retention window only: there is no path where an expired key is re-executed.

Body

This endpoint expects a JSON object.

productIdstring<uuid>Optional
Sell a catalog product; its name and price become the one line item and its currency the link's.
currencystringOptional
Required without productId. Card links are refused in currencies the processor cannot price; the error names it.
Allowed values:USDEURGBPAED
Show 10 more values
MXNBRLARSINRCNYHKDPHPSGDIDRTHB
itemsarray of objectOptional
Required without productId.
Show 6 properties
- idstringOptional
  Response only. The line's id.
- descriptionstringOptional
- detailstring | nullOptional
- quantitystringOptional
- unitAmountstringOptional
- amountstringOptional
  quantity × unitAmount, rounded once at the currency's precision. Response only.
methodsarray of objectOptional
Omitted means [{ "kind": "card" }]. An empty array is a link nothing can pay.
Show 7 properties
- kindstringRequired
  How a buyer may pay. card is the hosted card page (card, wallets and PayPal in one).
  Allowed values:cardbankcryptocashapp
- enabledbooleanOptionalDefaults to true
- bankAccountRefobjectOptional
  Bank rail only. The receiving account snapshot; at least beneficiaryName and an account identifier.
- tokenstringOptional
  Crypto rail only, e.g. USDC. One of the supported tokens (USDC, USDT, EURC, DAI, PYUSD, BTC, ETH, SOL, …, upper or lower case); anything else is 400 VALIDATION_ERROR.
- chainstringOptional
  Crypto rail only, e.g. base. One of the supported networks (base, ethereum, polygon, arbitrum, optimism, solana, bitcoin, bnb, …); anything else is 400 VALIDATION_ERROR.
- depositAddressstringOptional
  Crypto rail only.
- currencystringOptional
  Bank rail only. The account's currency when it differs from the link's.
  Allowed values:USDEURGBPAED
  Show 10 more values
  MXNBRLARSINRCNYHKDPHPSGDIDRTHB
fromNamestringOptional
The name the buyer sees. Defaults to your organization's name.
memostringOptional
A note shown to the buyer.
taxRatestringOptional
Percent, as a decimal string.
taxNamestringOptional
taxInclusivebooleanOptionalDefaults to false
When true the tax is disclosed inside the total rather than added to it.
statementDescriptorstringOptional
What the buyer's card statement says, without the processor's prefix. Defaults to your registered descriptor, then fromName.
adaptivePricingbooleanOptionalDefaults to false
Card rail only. The buyer sees the price in their own currency and pays on a domestic rail; the link stays priced and reported in currency.
successUrlstring<uri>Optional
Where the payer page sends the buyer after a card payment, with avvio_link=<slug> (the link's public slug, the last path segment of shareUrl) and, when known, client_reference_id=<ref> appended. https only. Bank and crypto payments settle later and never redirect. Never trust the redirect alone: confirm on the webhook or GET /links/{linkId}/payments.
cancelUrlstring<uri>Optional
Rendered as a "Back to {merchant}" link on the payer page. Same rule as successUrl.
clientReferenceIdstringOptional
Your id for what this link pays for (an order, a booking), echoed on every payment event. The authoritative join, on every rail.
metadataobjectOptional
Up to 50 keys of at most 40 characters with string values of at most 500. Echoed on every payment event, never shown to a buyer.
expiresAtstring<date-time>Optional
When the link stops taking payments: an ISO-8601 instant with a timezone (2026-10-01T09:00:00Z), in the future, at most a year away. From then the page answers 410 and status reads expired. Omitted means the link runs until it is paused. The one field a live link may still change, on its own.
publishbooleanOptionalDefaults to false
Create and publish in one call, so the response carries shareUrl. On a publish failure the draft is kept and named in the error.

Behavior

Send either a productId or currency + items. Every link carries shareUrl, the page to send your buyer to; with publish: true it is live on return.

Without publish the link is a draft: not publicly readable, editable with PATCH, deletable. POST /links/{linkId}/publish makes it live.

methods omitted means [{ "kind": "card" }], the hosted card page (card, wallets and PayPal). methods: [] is a link nothing can pay. Bank and crypto rails need the account or address to pay into.

When publish is refused inside a publish: true create, the call still answers 201 with the kept draft: the normal link body with status: "draft" and a publishError: { status, type, message } saying why (a business not yet set up for cards, a currency the processor cannot price). Branch on status !== "sent", then read publishError. Fix the cause and POST /links/{linkId}/publish, or DELETE the draft. It answers 201 rather than throwing because a stored idempotent response is only kept for a success: an error would release the key, and a client's automatic retry would create a second draft.

The exception is the card processor failing to answer at all (a timeout or a 5xx while the hosted card page is minted). That answers 500 INTERNAL, and the draft is kept. Do not retry the create: list your drafts (GET /links?status=draft) and publish or delete the one already made.

expiresAt gives the link a deadline. From that instant the page answers 410 and the link reads expired; the merchant's own booking or order logic decides what a payment that lands after it means. Omitted, the link runs until paused.

Idempotency-Key is required on an API key (400 IDEMPOTENCY_KEY_REQUIRED without it): a retry under the same key returns the same link instead of a second one.

Responses

201The link. status is sent after a successful publish: true; draft otherwise, with publishError set when a publish was refused.

Body · CheckoutLinkCreated

idstringRequired
Use this in every /links/{linkId} path.
numberstringOptional
Inherited from the invoice shape. Always CHECKOUT on a link; internal, never shown to a buyer and never the wire reference (that is slug).
paymentReferencestring | nullOptional
Inherited from the invoice shape. Null on a link; a bank payer references the slug.
deepLinkstring | nullOptional
Inherited from the invoice shape: an avvio:// app link to the same page.
fromEmailstring | nullOptional
Inherited from the invoice shape. Your contact email as shown to the buyer, when set.
fromAddressstring | nullOptional
Inherited from the invoice shape. Your address as shown to the buyer, when set.
customerName | nullOptional
Inherited from the invoice shape. Always null; a link is addressed to nobody.
customerEmail | nullOptional
Always null on a link.
customerAddress | nullOptional
Always null on a link.
customerId | nullOptional
Always null on a link.
feeTotalstringOptional
Inherited from the invoice shape. "0" on a link; processing fees are on each payment, not the link.
settlementCurrencystringOptional
Inherited from the invoice shape. The stablecoin the crypto rail settles in when offered; informational on a card link.
settlementAmountstringOptional
Inherited from the invoice shape. The total in settlementCurrency.
dueTypestringOptional
Inherited from the invoice shape. Always on_receipt on a link; a link has no due date.
dueDate | nullOptional
Always null on a link.
paidAt | nullOptional
Always null on a link. A link never closes; each payment carries its own paidAt.
emailedAt | nullOptional
Always null on a link. Links are not emailed to a customer.
slugstringRequired
The public page's path segment (the end of shareUrl), the avvio_link value on a success redirect, and the reference a bank payer types.
statusstringRequired
draft is not publicly readable. sent is live. cancelled is paused and expired is past its expiresAt: both are terminal, and the page answers 410.
Allowed values:draftsentcancelledexpired
shareUrlstring<uri> | nullRequired
The page to send buyers to. Null only when the environment has no public page URL configured.
fromNamestringRequired
currencystringRequired
subtotalstringOptional
taxRatestringOptional
taxNamestring | nullOptional
taxInclusivebooleanOptional
taxTotalstringOptional
totalstringRequired
What one buyer pays.
memostring | nullOptional
statementDescriptorstring | nullOptional
adaptivePricingbooleanOptional
issuedAtstring<date-time> | nullOptional
When it was published.
createdAtstring<date-time>Required
itemsarray of objectOptional
Show 6 properties
- idstringOptional
  Response only. The line's id.
- descriptionstringOptional
- detailstring | nullOptional
- quantitystringOptional
- unitAmountstringOptional
- amountstringOptional
  quantity × unitAmount, rounded once at the currency's precision. Response only.
methodsarray of objectOptional
Show 8 properties
- kindstringRequired
  How a buyer may pay. card is the hosted card page (card, wallets and PayPal in one).
  Allowed values:cardbankcryptocashapp
- enabledbooleanRequired
- tokenstring | nullOptional
- chainstring | nullOptional
- currencystring | nullOptional
- depositAddressstring | nullOptional
- bankAccountRefobject | nullOptional
  Bank rail only. The receiving account as you stored it on the link; the same object the public payer page shows a buyer.
- cashAppPayloadobject | nullOptional
productobject | nullRequired
The catalog product it was made from; null for an ad-hoc link.
Show 2 properties
- idstringRequired
- namestringRequired
receivedobject | nullRequired
What the link has taken in, summed over its paid and refunded payments. Base units with decimals beside them. Null on the link until the first payment lands, so "never paid" is not a zero.
Show 5 properties
- countintegerRequired
  Qualifying payments. Pending and reversed rows are not counted.
- grossBasestringRequired
  What arrived.
- refundedBasestringRequired
  What went back.
- currencystringRequired
- decimalsintegerRequired
successUrlstring<uri> | nullRequired
cancelUrlstring<uri> | nullRequired
clientReferenceIdstring | nullRequired
metadataobject | nullRequired
expiresAtstring<date-time> | nullRequired
When the link stops taking payments, or null for "until paused". Past it the page answers 410 and status reads expired within a minute.
sourcestringRequired
Who made the link (your server through an API key, or a person in the dashboard). The dashboard lists the two apart.
Allowed values:apidashboard
publishErrorobjectOptional
Only when publish: true was refused. The link is a kept draft (status: "draft"); this says why. Absent otherwise.
Show 3 properties
- statusintegerRequired
  The HTTP status the publish would have answered.
- typestringRequired
  The same vocabulary as the error envelope's type: BAD_REQUEST, CONFLICT, NOT_FOUND, FORBIDDEN, INTERNAL, or a more specific code.
- messagestringRequired

Errors

400
VALIDATION_ERROR (a field is malformed, or a token, chain or currency we do not support; errors names each), BAD_REQUEST (both productId and items; an archived product; a currency the card processor cannot price, such as CNY; a bank rail with no account), or IDEMPOTENCY_KEY_REQUIRED / IDEMPOTENCY_KEY_INVALID (no header, or a malformed one). A refused publish is not an error here: the draft comes back 201 with publishError, whose type is LINK_EXPIRED when the draft's expiresAt has already passed.
401
The key was refused. Nothing ran.
- UNAUTHORIZED: missing, invalid or revoked, or a key on a route that does not accept one.
- KEY_EXPIRED: the key passed the expiry it was issued with. Issue a new one; an expired key cannot be rotated.
- KEY_IP_NOT_ALLOWED: the key is pinned to source addresses and this request came from another.
403
A valid key that may not make this write. Nothing was changed.
- FORBIDDEN: the key belongs to a different organization, or your business has not completed verification to accept payments; detail says which.
- ACCOUNT_BLOCKED: API access for your organization is suspended.
- LIVE_KEY_ORG_NOT_APPROVED: a live key, before we have approved your business verification. Use a test key until then.
- INSUFFICIENT_SCOPE: a read-only key.
404
NOT_FOUND: the productId is not a product in this organization.
409
Either the key was reused with a different body (IDEMPOTENCY_KEY_CONFLICT: use a new key), or the first request with this key is still running (IDEMPOTENCY_KEY_REQUEST_IN_PROGRESS: back off and retry the same key).
429
Too many requests. The default ceiling is 100 requests per minute per API credential on a 60-second window. High-volume payout and reconciliation routes declare a 600/minute override, and batch submission a 30/minute ceiling. A separate 2,000/minute per-source-IP abuse ceiling always applies.

Obey Retry-After; it is in seconds and is authoritative. A 429 means the request was refused before the handler ran. Retry reads normally; retry an idempotent mutation with its same Idempotency-Key.
500
INTERNAL: with publish: true, the card processor did not answer while the card page was being set up. The draft was kept. Do not retry the create; find the draft and publish or delete it.

Error body · Error

typestringRequired
Stable machine-readable code.
detailstringRequired
What went wrong, in a sentence. Always a string, so detail.toLowerCase() is safe.
More
This is the field to read on BAD_REQUEST and PROVIDER_REJECTED, where the type alone does not name the condition.
messagestringRequired
The same text as detail, kept for integrations written before detail existed. Read detail.
resolutionstringOptional
What to do about it, when there is a specific answer. It is not on every error (it is absent on BAD_REQUEST, NOT_FOUND, PAYOUT_NOT_CANCELABLE and DESTINATION_ACCOUNT_NOT_FOUND), so treat it as optional and fall back to detail.
statusintegerRequired
HTTP status, repeated in the body.
statusCodeintegerRequired
The same value as status, kept for integrations written before status existed. Read status.
requestIdstringRequired
Quote this to support and we can find the exact request. Also sent as the x-request-id response header, which is the only place it appears on a successful response. Success bodies do not carry it. Send your own x-request-id on the request and we use it, so your trace and ours share one identifier; otherwise we mint one.
errorsarray of stringOptional
Present on VALIDATION_ERROR; names each field that failed.
originalIdempotencyKeystringOptional
On DUPLICATE_REQUEST_DETECTED only. Send the request again with this to receive the original payout instead of making a second one. Without it there is no way to recover except by risking a double payment.
originalPayoutIdstringOptional
On DUPLICATE_REQUEST_DETECTED only. The payout the first request created.
originalBatchIdstringOptional
On a batch DUPLICATE_REQUEST_DETECTED. The run the first request created.
originalRequestIdstringOptional
On a 409 PAYOUT_OUTCOME_UNKNOWN replay. The requestId of the call whose outcome is unknown; quote it to support.
existingRecipientIdstringOptional
On BANK_ACCOUNT_ALREADY_LINKED. The recipient in your organization that already holds this account.
existingMethodIdstringOptional
On BANK_ACCOUNT_ALREADY_LINKED. The payment method on that recipient.

Branch on type, never on the status or the message. Every error type is listed with what to do about it.

Avvio Checkout · Checkout links · operation createCheckoutLink

Try it: Create a checkout link

POST https://api.avvio.xyz/business/api/v1/checkout/organizations/{orgId}/links

API key Required

Test keys only. Sent as x-api-key through this site's proxy to the Avvio API, never saved, and cleared when you close this dialog.

orgId pathRequired

Idempotency-Key headerRequired

Body JSON

Was this page helpful?