---
title: "List checkout sessions"
method: GET
path: "/api/v1/checkout-sessions"
tags: ["Checkout"]
---

# List checkout sessions

`GET /api/v1/checkout-sessions`

## Request

- Base URL: `https://merchant.zahlo.eu`
- URL: `https://merchant.zahlo.eu/api/v1/checkout-sessions`
- Auth: API key in header `x-api-key`

List checkout sessions. Use the response status and request ID to decide whether to retry, reconcile, or ask the customer for action.

## Query parameters

- `limit` integer
- `startingAfter` string
- `endingBefore` string
- `status` 'open' | 'complete' | 'expired'
- `customerId` string
- `createdGte` string, date-time

## Response `200`

Successful response

- object
  - `object` 'list', required
  - `data` CheckoutSession[], required
    - `id` string, required
    - `object` 'checkout_session', required
    - `livemode` boolean
    - `createdAt` string, date-time
    - `type` 'payment' | 'setup' | 'subscription', required
    - `mode` 'hosted' | 'embedded', required
    - `status` 'open' | 'complete' | 'expired' | 'failed', required
    - `paymentStatus` 'unpaid' | 'paid' | 'no_payment_required', required
    - `url` string, uri, nullable: Hosted only, while open: redirect the customer here.
    - `clientToken` string, nullable: Embedded only, while open: pass it to the browser SDK.
    - `detailsRequired` boolean: Embedded only: true until the payer completed Zahlo's details step (the browser SDK mounts it first); embedUrl is null meanwhile.
    - `embedUrl` string, uri, nullable
    - `expiresAt` string, date-time, required
    - `currency` string, required
    - `amountSubtotal` integer
    - `amountDiscount` integer
    - `amountShipping` integer: The chosen shipping option, inside amountTotal; 0 without one.
    - `amountTotal` integer, required
    - `shippingOptions` object[]: The offered shipping rates with their amount at session create, in order.
      - `shippingRate` string, required
      - `shippingAmount` integer, required
    - `shippingCost` object, nullable: The chosen shipping option. amountTax is 0: VAT is inside the amount. Discounts never apply to shipping.
      - `amountSubtotal` integer, required
      - `amountTax` integer, required
      - `amountTotal` integer, required
      - `shippingRate` string, required
    - `lineItems` object[], required
      - `name` string
      - `quantity` integer
      - `unitAmountMinor` integer
      - `amountMinor` integer
      - `priceId` string, nullable
      - `adjustableQuantity` object: Present when the payer may change this line's quantity.
        - `enabled` boolean
        - `minimum` integer
        - `maximum` integer
    - `customerId` string, nullable
    - `setupFutureUsage` 'off_session', nullable: Set when the session saves the card for off-session charges.
    - `customerEmail` string, nullable
    - `couponId` string, nullable
    - `paymentId` string, nullable
    - `subscriptionId` string, nullable
    - `reference` string, nullable
    - `customFields` CustomField[]: The session's custom fields with the payer's answers; empty when it asks none.
      - `key` string, required
      - `label` object, required
        - `type` 'custom', required
        - `custom` string, required
      - `type` 'dropdown' | 'text', required
      - `optional` boolean, required
      - `dropdown` object, nullable, required
        - `options` object[], required
          - `label` string, required
          - `value` string, required
        - `defaultValue` string, nullable, required
        - `value` string, nullable, required
      - `text` object, nullable, required
        - `minimumLength` integer, nullable, required
        - `maximumLength` integer, nullable, required
        - `defaultValue` string, nullable, required
        - `value` string, nullable, required
    - `phoneNumberCollection` object: The details page asks for a phone number.
      - `enabled` boolean, required
    - `nameCollection` object: The details page asks for a full name and/or a business name.
      - `individual` object, required
        - `enabled` boolean, required
      - `business` object, required
        - `enabled` boolean, required
    - `consentCollection` object
      - `promotions` 'auto' | 'none', required
      - `termsOfService` 'required' | 'none', required
    - `allowPromotionCodes` boolean
    - `submitType` 'auto' | 'pay' | 'book' | 'donate'
    - `brandingSettings` object, nullable: This session's branding override; null fields fall back to Account → Branding.
      - `brandColor` string, nullable
      - `logoUrl` string, nullable
      - `displayName` string, nullable
    - `taxIdCollection` object
      - `enabled` boolean, required
    - `customerDetails` object: What the payer entered on the details page; null until then.
      - `email` string, nullable, required
      - `phone` string, nullable, required
      - `individualName` string, nullable, required
      - `businessName` string, nullable, required
    - `consent` object
      - `promotions` 'opt_in' | 'opt_out', nullable, required
      - `termsOfService` 'accepted', nullable, required
    - `shippingDetails` object, nullable: The shipping address the payer entered on Zahlo's page, for a payment link or a session with `shippingAddressCollection`.
      - `name` string, required
      - `address` object, required
        - `line1` string, required
        - `line2` string, nullable, required
        - `city` string, required
        - `postalCode` string, required
        - `country` string, required: ISO 3166-1 alpha-2
    - `successUrl` string
    - `cancelUrl` string
    - `locale` string
    - `paymentMethodTypes` string[]
    - `appearance` CheckoutAppearance
      - `theme` 'light' | 'dark' | 'auto'
      - `logoUrl` string, uri
      - `iconUrl` string, uri
      - `fontFamily` string
      - `colors` object
      - `spacing` 'compact' | 'normal' | 'comfortable'
      - `customCss` string
    - `metadata` object: Up to 50 key-value pairs; keys up to 40 characters, values strings up to 500 characters.
  - `hasMore` boolean, required

## Other responses

- `400`: Invalid request
- `401`: Authentication failed
- `404`: Resource not found
- `409`: Request conflicts with existing state

---

[API](https://skmtc.dev/zahlo/apis/zahlo-merchant-api.md) - [All operations](https://skmtc.dev/zahlo/apis/zahlo-merchant-api/llms.txt) - [OpenAPI document](https://skmtc.dev/zahlo/apis/zahlo-merchant-api/revisions/8fcbef981e0d?raw)