---
title: "List checkouts"
method: GET
path: "/api/checkouts"
tags: ["checkouts"]
---

# List checkouts

`GET /api/checkouts`

## Request

- Base URL: `https://api.depixapp.com`
- URL: `https://api.depixapp.com/api/checkouts`
- Auth: HTTP bearer

Paginated checkout list for the authenticated merchant, filtered to the key's mode (sk_test_ sees only sandbox checkouts). Requires scope `merchant_read` on the API-key path.

**This list is paginated and `limit` caps at 100.** `stats` is computed over the WHOLE filter, not over the page, so `stats.total` is what tells you whether you have every row — summing `amount` across one page and calling it a total is how a reconciliation silently comes out short.

**Held sales**: a sale whose money is not released yet stays in `processing` and carries `vault_hours` (the wait it was booked for) and, once the provider answers, `delay_until` (the release date). `?status=processing` with `vault_hours > 0` or a `delay_until` is the reconciliation query for "paid, not settled yet" — money received but not landed, and until it lands the provider can still reverse it (see `rejection_reasons`). On a sale the hold policy decided not to hold, `vault_hours` is `0` and `delay_until` is null; on one it never saw, `vault_hours` is null too (see the field description — null is not zero).

## Query parameters

- `status` union: Checkout lifecycle status — the enum below is the complete, closed set. `completed` is the terminal SUCCESS state. Terminal states (safe to stop polling): completed, expired, cancelled.
  - 'pending': Awaiting payment; the PIX QR is active until expires_at.
  - 'processing': PIX paid; settlement in progress.
  - 'approved': Payment approved by the provider; DePix on the way to the merchant.
  - 'completed': TERMINAL — success: DePix delivered to the merchant.
  - 'expired': TERMINAL — QR expired unpaid.
  - 'cancelled': TERMINAL — cancelled upstream by the provider (refund/error).
- `product_id` string
- `from` string
- `to` string
- `q` string
- `limit` integer
- `offset` integer

## Response `200`

Checkout list.

- CheckoutListResponse: Paginated checkout list with aggregate stats.
  - `checkouts` object[], required: Checkout rows, newest first.
    - `id` string, required: Checkout id (chk_*).
    - `status` union, required: Checkout lifecycle status — the enum below is the complete, closed set. `completed` is the terminal SUCCESS state. Terminal states (safe to stop polling): completed, expired, cancelled.
      - 'pending': Awaiting payment; the PIX QR is active until expires_at.
      - 'processing': PIX paid; settlement in progress.
      - 'approved': Payment approved by the provider; DePix on the way to the merchant.
      - 'completed': TERMINAL — success: DePix delivered to the merchant.
      - 'expired': TERMINAL — QR expired unpaid.
      - 'cancelled': TERMINAL — cancelled upstream by the provider (refund/error).
    - `amount` integer, required: Charge amount in cents.
    - `description` string, nullable, required: Checkout description.
    - `created_at` string, required: Creation timestamp (RFC 3339 UTC).
    - `expires_at` string, required: QR expiry timestamp (RFC 3339 UTC).
    - `is_live` 0 | 1, required: 1 = live, 0 = sandbox (raw SQLite boolean).
    - `processing_at` string, nullable, required: When the checkout entered processing (null if never).
    - `approved_at` string, nullable, required: When the checkout was approved (null if never).
    - `metadata` string, nullable, required: Merchant metadata as the raw stored JSON string (not parsed on the list endpoint).
    - `product_name` string, nullable, required: Name of the linked product (null for generic checkouts).
    - `payment_method` 'pix' | 'depix': Which rail settles the checkout. `pix` (default): the payer pays a PIX QR and the provider delivers DePix to the merchant. `depix`: the payer sends DePix wallet-to-wallet on Liquid to an address dedicated to this merchant, and settlement is observed on-chain — no PIX QR exists on this rail.
    - `depix_discount_pct` integer, nullable: depix rail only: the discount percentage applied to this checkout (0–90). Null on the pix rail.
    - `depix_due_cents` integer, nullable: depix rail only: the discounted, uniqueness-adjusted amount in cents that had to arrive (and did, once settled — attribution is exact-match). This, not `amount` (the face value), is what the merchant received. Null on the pix rail.
    - `rejection_reasons` string[], required: Provider reasons for a refunded/held payment on the underlying deposit — e.g. PAYER_MISMATCH, PAST_DAILY_LIMIT, BLOCKED_USER, HIGH_VELOCITY. Empty array when the payment was not refused. New reason codes may appear; display unknown codes as-is.
    - `payer_name` string, nullable: Name the provider reports for whoever paid, off the underlying deposit. Null while the sale is unpaid, on the depix rail (no Pix payer to name), and on any sale the provider settled without one.
    - `blockchain_tx_id` string, nullable: Liquid txid that settled this sale, on either rail. Null until the money lands — and for a short while after, on the pix rail, when the provider reports the txid in a later callback than the one that completed the sale.
    - `delay_until` string, nullable: When this sale's money is released, if it is being held. Same RFC 3339 UTC instant as every other timestamp here (`"2026-08-13T12:03:00.000Z"`). Non-null only once the provider has answered with a date, so a sale that is held right now still reads null for a while; it also stays set after the money lands, so it is a hold RECORD, not a live flag. Pair it with `status`: a sale still waiting sits in `processing`. Never a reason — what triggered the hold is not published.
    - `vault_hours` integer, nullable: How many hours this sale was booked to wait when it was created. `0` means the hold policy looked at it and imposed no wait. **Null is not zero**: it means no hold decision was recorded against this sale at all — a sandbox checkout (no paired deposit exists), a row created before the mechanism shipped, or one created while the mechanism was switched off. Today the vast majority of rows read null. Use it as an answer to WHETHER, never to WHEN: the real wait starts when the payer pays, not when the sale was created, so `created_at + vault_hours` lands EARLY and must not be presented as a release date. `delay_until` is the only date.
  - `stats` object, required: Aggregates over the CURRENT FILTER (not just the current page).
    - `total` integer, required: Total checkouts matching the filter.
    - `pending` integer, required: Checkouts currently pending.
    - `completed` integer, required: Checkouts completed.
    - `completed_amount` integer, required: Sum of completed amounts in cents.
  - `limit` integer, required: Applied page size (1–100).
  - `offset` integer, required: Applied offset.

## Other responses

- `401`: Missing/invalid credentials. `invalid_api_key` for a failed sk_* lookup (revoked/expired/unknown); `invalid_token` for a bad or missing JWT/Authorization header.
- `403`: The API key lacks the `merchant_read` scope required by this operation. May also be `account_blocked`, or an operation-specific 403 — see the error catalog.
- `429`: Rate limited. Beyond the endpoint's own limit when set (`rate_limited`), API-key calls are also bounded by the shared per-merchant budget (`merchant_rate_limited`, default 30 req/min across all endpoints) and by the key's own rate limit when configured (`rate_limited`). Retry after `retry_after` seconds (also in the Retry-After header).

---

[API](https://skmtc.dev/depixapp/apis/depix-api.md) · [All operations](https://skmtc.dev/depixapp/apis/depix-api/llms.txt) · [OpenAPI document](https://skmtc.dev/depixapp/apis/depix-api/revisions/04094536dd0f?raw)