---
title: "Pay for your cart"
method: POST
path: "/api/v1/cart/checkout"
tags: ["Cart"]
---

# Pay for your cart

`POST /api/v1/cart/checkout`

## Request

- Base URL: `https://spoofy.social`
- URL: `https://spoofy.social/api/v1/cart/checkout`
- Auth: one of:
  - HTTP bearer
  - API key in cookie `better-auth.session_token`

Pays every line (or the `items` given, by line id; the others stay in the cart) in one go — the same rules as `POST /api/v1/orders/batch`: all checked first at today’s price, none placed if any cannot go, then each placed on its own. The lines placed leave the cart; one that failed at the last moment stays, with its reason. Send an `Idempotency-Key` per attempt (a retry with it is that same attempt) and `max_total`, the total you showed. `dry_run: true` checks only and also returns the cart; when your balance holds only part of it, the answer’s `fit` names the lines it pays for now — send those as `items`, with `max_total` = `fit.total`, under the same key.

## Headers

- `Idempotency-Key` string

## Request body

- object
  - `dry_run` boolean
  - `max_total` string
  - `items` string[]: Only these lines (ids); default the whole cart.

## Response `200`

A dry run (with the cart) — or a replay of an earlier attempt with the same Idempotency-Key.

- BatchCheck: A dry run: every order checked at today’s price, nothing charged.
  - `dry_run` unknown
  - `ok` boolean: Every order can go, nothing stops the batch, and your balance holds it.
  - `items` BatchItemCheck[]
    - `index` integer: Its place in `items`, from 0.
    - `ok` boolean: It can be placed as it is.
    - `service` integer
    - `link` string
    - `quantity` integer, nullable: The units charged.
    - `total` string, nullable: Its price now (a schedule: its whole plan). USD as a decimal string.
    - `needs` string, nullable: What your balance must hold for it now: the order, a plan, or a repeat’s first run.
    - `scheduled` boolean: It becomes an automation.
    - `textReview` boolean: Our team may check its text before it starts.
    - `done` boolean: Placed already by an earlier try with the same Idempotency-Key.
    - `cartItemId` string: Paying the cart: the line it is.
    - `error` object: Why it cannot be placed: `code` (from the error table), `message`, `details`.
      - `code` string
      - `message` string
      - `details` object
  - `total` string: Today’s price of all of it. USD as a decimal string.
  - `needs` string: What your balance must hold now. USD as a decimal string.
  - `balance` string: Your balance. USD as a decimal string.
  - `sufficient` boolean
  - `shortfall` string: What to top up first (0.00 when nothing). USD as a decimal string.
  - `problem` object, nullable: A reason for the whole batch (orders per minute, the key’s daily cap, prices moved past `max_total`), else null.
    - `code` string
    - `message` string
  - `fit` object: Paying the cart only, when your balance holds some of its lines but not all and nothing else stops them: the lines it pays for now (`items`, by line id, in cart order — a line that does not fit waits and the ones after it may still fit) and those that wait (`keep`). Pay with `items` and `max_total` = `total` under the same Idempotency-Key: those are placed, the rest stays in the cart. Absent otherwise.
    - `items` string[]
    - `keep` string[]
    - `total` string: Today’s price of the lines that go now. USD as a decimal string.
    - `needs` string: What your balance must hold for them now. USD as a decimal string.

## Other responses

- `201`: Paid (each line says how it went).
- `400`: Nothing to pay, or a line cannot go; none was placed.
- `401`: No valid API key or session.
- `402`: Your balance does not hold all of it; none was placed.
- `409`: Prices moved past `max_total`; none was placed.
- `413`: The request body is too big (uploads up to 4 MB, everything else up to 64 KB).
- `429`: Slow down: too many requests in a short time. Wait `Retry-After` seconds and carry on.

---

[API](https://skmtc.dev/spoofy/apis/spoofy-api.md) · [All operations](https://skmtc.dev/spoofy/apis/spoofy-api/llms.txt) · [OpenAPI document](https://skmtc.dev/spoofy/apis/spoofy-api/revisions/58adc986f826?raw)