# Checkout intents (/docs/api-reference/checkout-intents)

A **checkout intent** is one payable checkout: a priced cart, the amount due, and the ways the buyer can pay. Create one per purchase attempt. See [Headless checkout](/docs/payments/headless-checkout) for the full guide.

## Create a checkout [#create-a-checkout]

<EndpointHeader method="POST" path="/api/v5/merchant/checkout-intents" />

Scope: **`commerce.checkout`**

### Body [#body]

| Field | Type | Required | Notes |
|---|---|---|---|
| `items` | array | Yes | 1 to 60 lines |
| `items[].productId` | string | Yes | A product `_id` from your store (24 hex characters) |
| `items[].quantity` | integer | No | 1 to 999, default 1 |
| `items[].selectedOptions` | object | When the product has options | e.g. `{ "Color": "Black", "Size": "M" }` |
| `customerInfo` | object | For physical items | `name`, `email`, `phone`, `address { line1, line2, city, state, postalCode, country }` |
| `paymentRail` | string | No | Omit for crypto only; `"buyer_choice"` to offer card when eligible |
| `description` | string | No | Defaults to one built from the items |
| `expiresAt` | ISO 8601 | No | Default 24 hours, maximum 30 days |

Sending `price`, `amount` or `unitPrice` on any item is rejected with `400`. Swop always prices from your catalogue.

```bash tab="curl"
curl -X POST https://apps.apiswop.co/api/v5/merchant/checkout-intents \
  -H "Authorization: Bearer $SWOP_MERCHANT_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [ { "productId": "66a1b2c3d4e5f6a7b8c9d0e1", "quantity": 1, "selectedOptions": { "Color": "Black" } } ],
    "customerInfo": {
      "name": "Ada Buyer",
      "email": "ada@example.com",
      "address": { "line1": "1 Main St", "city": "Austin", "state": "TX", "postalCode": "78701", "country": "US" }
    },
    "paymentRail": "buyer_choice"
  }'
```

```js tab="Node"
const res = await fetch('https://apps.apiswop.co/api/v5/merchant/checkout-intents', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.SWOP_MERCHANT_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    items: [{ productId: '66a1b2c3d4e5f6a7b8c9d0e1', quantity: 1, selectedOptions: { Color: 'Black' } }],
    customerInfo: {
      name: 'Ada Buyer',
      email: 'ada@example.com',
      address: { line1: '1 Main St', city: 'Austin', state: 'TX', postalCode: '78701', country: 'US' },
    },
    paymentRail: 'buyer_choice',
  }),
});
const { data } = await res.json();
```

```python tab="Python"
import os, requests

r = requests.post(
    "https://apps.apiswop.co/api/v5/merchant/checkout-intents",
    headers={"Authorization": f"Bearer {os.environ['SWOP_MERCHANT_KEY']}"},
    json={
        "items": [{"productId": "66a1b2c3d4e5f6a7b8c9d0e1", "quantity": 1, "selectedOptions": {"Color": "Black"}}],
        "customerInfo": {
            "name": "Ada Buyer",
            "email": "ada@example.com",
            "address": {"line1": "1 Main St", "city": "Austin", "state": "TX", "postalCode": "78701", "country": "US"},
        },
        "paymentRail": "buyer_choice",
    },
)
data = r.json()["data"]
```

### Response `201` [#response-201]

```json
{
  "success": true,
  "data": {
    "intentId": "co_7Hk2mPq9xR4s",
    "status": "active",
    "paymentRail": "crypto",
    "checkoutMode": "online",
    "description": "Swop Classic Card",
    "amount": { "value": 30, "currency": "USDC" },
    "fees": {
      "currency": "USDC",
      "feesPayer": "merchant",
      "subtotalAmount": 30,
      "platformFeeBps": 50,
      "platformFeeAmount": 0.15,
      "royaltyAmount": 0,
      "merchantReceivesAmount": 29.85,
      "totalDueAmount": 30
    },
    "lineItems": [
      {
        "productId": "66a1b2c3d4e5f6a7b8c9d0e1",
        "name": "Swop Classic Card",
        "quantity": 1,
        "unitAmount": 25,
        "totalAmount": 25,
        "requiresShipping": true,
        "shippingAmount": 5,
        "productType": "physical",
        "selectedOptions": { "Color": "Black" }
      }
    ],
    "merchant": { "id": "65f0c1…", "name": "Acme", "wallet": { "address": "…" } },
    "customerInfo": { "name": "Ada Buyer", "email": "ada@example.com", "address": { "line1": "1 Main St", "city": "Austin", "state": "TX", "postalCode": "78701", "country": "US" } },
    "checkoutUrl": "https://www.swopme.app/checkout/co_7Hk2mPq9xR4s",
    "paymentRequest": {
      "rail": "solana_pay",
      "recipient": "…",
      "amount": 30,
      "currency": "USDC",
      "tokenMint": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
      "tokenDecimals": 6,
      "reference": "…",
      "memo": "swop:co_7Hk2mPq9xR4s",
      "url": "solana:…",
      "status": "awaiting_payment",
      "expiresAt": "2026-10-30T18:00:00.000Z"
    },
    "cardOffered": false,
    "marketplaceOrder": null,
    "expiresAt": "2026-10-30T18:00:00.000Z",
    "createdAt": "2026-10-29T18:00:00.000Z",
    "updatedAt": "2026-10-29T18:00:00.000Z"
  }
}
```

{/* TODO(review): example values are illustrative, not captured from staging. The serializer also returns purpose, purposeData, cardUseCase, merchantCurrency, merchantPayout, payoutSwap, payer, preparedPayment, payment, swapTransaction, settlement, refundRequests, merchantRisk and bucksCredit; documented fields only below. */}

### Key fields [#key-fields]

| Field | Type | Meaning |
|---|---|---|
| `intentId` | string | `co_…`. Save it with your order. |
| `status` | string | See [statuses](/docs/payments/statuses-and-escrow#checkout-statuses) |
| `paymentRail` | string | The rail in use, e.g. `crypto` |
| `amount.value` | number | Total due, USDC |
| `fees.totalDueAmount` | number | What the buyer pays (shipping included) |
| `fees.platformFeeBps` | number | `50` = 0.5% |
| `fees.platformFeeAmount` | number | The fee in USDC |
| `fees.merchantReceivesAmount` | number | What you receive |
| `lineItems[]` | array | Priced lines, including `shippingAmount` and `requiresShipping` |
| `checkoutUrl` | string | Swop's hosted page for this checkout |
| `paymentRequest` | object \| null | The USDC payment request. `null` while the buyer is choosing card or crypto. |
| `paymentRequest.url` | string | A `solana:` link. Show as a link and a QR code. |
| `cardOffered` | boolean | Whether card can be used for this checkout |
| `marketplaceOrder` | object \| null | The order created once paid |
| `expiresAt` | ISO 8601 | When it stops being payable |

### Errors [#errors]

| Status | When |
|---|---|
| `400` | A price on an item; bad `productId`; product unavailable; invalid options; bad `paymentRail` (`paymentRail must be omitted (crypto) or "buyer_choice".`); bad `expiresAt` |
| `400` `SHIPPING_DETAILS_REQUIRED` | Physical item without name, email or address; see `missing` |
| `403` | Key lacks `commerce.checkout` |
| `404` | A product that isn't yours |

## Retrieve a checkout [#retrieve-a-checkout]

<EndpointHeader method="GET" path="/api/v5/merchant/checkout-intents/{intentId}" />

Scope: **`commerce.read`**

Returns the same object as create (without `cardOffered`). Only checkouts that belong to you are found; anything else is `404` (`No such checkout.`).

```bash tab="curl"
curl https://apps.apiswop.co/api/v5/merchant/checkout-intents/co_7Hk2mPq9xR4s \
  -H "Authorization: Bearer $SWOP_MERCHANT_KEY"
```

```js tab="Node"
const res = await fetch('https://apps.apiswop.co/api/v5/merchant/checkout-intents/co_7Hk2mPq9xR4s', {
  headers: { Authorization: `Bearer ${process.env.SWOP_MERCHANT_KEY}` },
});
const { data } = await res.json();
```

```python tab="Python"
import os, requests

r = requests.get(
    "https://apps.apiswop.co/api/v5/merchant/checkout-intents/co_7Hk2mPq9xR4s",
    headers={"Authorization": f"Bearer {os.environ['SWOP_MERCHANT_KEY']}"},
)
data = r.json()["data"]
```


## Public payment endpoints [#public-payment-endpoints]

These are called **without** an API key. The unguessable `intentId` authorises them, so your buyer's browser can call them directly. Base: `https://apps.apiswop.co/api/v5/checkout-intents`. Rate limit: 20 requests per 15 minutes per client.

| Method | Path | Body | Does |
|---|---|---|---|
| `POST` | `/{intentId}/select-crypto` | none | Buyer chose USDC. Read the checkout again for `paymentRequest`. |
| `POST` | `/{intentId}/card-payment-intents` | none | Buyer chose card. Returns `clientSecret` and `publishableKey` for Stripe's Payment Element. |
| `GET` | `/{intentId}/card-payment` | | Card payment state. Treat `transfer_pending`, `transfer_in_progress` or `transferred` as paid. |
| `POST` | `/{intentId}/card-payment/release` | none | Abandon card so the buyer can switch back to USDC |
