# List checkout sessions

Lists checkout session objects. Results are sorted by creation date, with the most recent objects first.

Endpoint: GET /checkout-sessions
Version: 1.0.0
Security: BasicAuth

## Query parameters:

  - `charge` (string)
    Return only the checkout session related to the given charge identifier.

  - `limit` (integer)
    Number of results per page (1-100)

  - `startingAfterId` (string)
    Return results starting after the object with this ID

  - `endingBeforeId` (string)
    Return results ending before the object with this ID

  - `created[gt]` (integer)
    Filter results created strictly after this Unix timestamp

  - `created[gte]` (integer)
    Filter results created at or after this timestamp

  - `created[lt]` (integer)
    Filter results created strictly before this Unix timestamp

  - `created[lte]` (integer)
    Filter results created at or before this timestamp

## Response 200 fields (application/json):

  - `list` (array)

  - `list.id` (string)
    Unique identifier of the session.
    Example: chse_LqM4nJ8vTyRbHwKpZdFcXaS2

  - `list.clientSecret` (string)
    Token which should be passed to the `checkout.js` script to open the Checkout form.
    Example: chcs_Rd7WkTnPqLmYbFhJxVzCgA4N

  - `list.created` (integer)
    Unix timestamp (seconds) when the session was created.
    Example: 1715810511

  - `list.objectType` (string)
    Enum: "checkoutSession"

  - `list.status` (string)
    Current status of the checkout session.
    Enum: "active", "paid", "expired", "failed"

  - `list.lastCharge` (string)
    Identifier of the most recent charge created by this session.
    Example: char_Xy9TqMfL2VnRbKdWzHcJpA7S

  - `list.locale` (string)
    Two-letter abbreviation of the language in which the Checkout form is presented. If not provided, the customer's browser language is used.
    Enum: "en", "bg", "cs", "da", "de", "el", "es", "et", "fi", "fr", "hr", "hu", "it", "lt", "lv", "nl", "no", "pl", "pt", "ro", "ru", "sk", "sl", "be"

  - `list.lastOpened` (integer)
    Unix timestamp (seconds) of the last time the Checkout page was opened. If it has not been opened yet, the value is `null`.
    Example: 1715810525

  - `list.lineItems` (array)
    Products or subscriptions that require payment.

  - `list.lineItems.product` (object)
    Item being paid for. Provide `id` to reference an existing product, otherwise the details given here are used to create a new product, which also becomes available via the `/products` endpoint. For a subscription item, provide `plan` instead.

  - `list.lineItems.product.id` (string)
    Identifier of an existing product.
    Example: product_kV8XmQzR3TfBnLpAyHcDe2Wj

  - `list.lineItems.product.name` (string)
    Product name.
    Example: Premium subscription

  - `list.lineItems.product.description` (string)
    Description of the product, shown to the customer on the hosted payment page directly under the product name.
    Example: Annual access to all premium features

  - `list.lineItems.product.amount` (any)
    Payment amount definition. Provide an integer for a fixed-amount item, or an object with `options` and/or `custom` to let the customer choose the amount. A fixed amount is mutually exclusive with `options` and `custom`; a customer-chosen amount may use `options`, `custom`, or both together.

  - `list.lineItems.product.amount.options` (array)
    List of available pre-defined payment amounts, in minor units of a given currency. Allows the customer to select from a list of options for how much they want to pay. Useful whenever you want to suggest a few selectable amounts — for example pay-what-you-want pricing, tips, or donations.
    Example: [1000,2500,5000]

  - `list.lineItems.product.amount.custom` (object)
    Possible range of a custom payment amount, letting the customer enter any value between `min` and `max`.

  - `list.lineItems.product.amount.custom.min` (integer)
    Minimum value of the custom payment amount, in minor units of a given currency.
    Example: 500

  - `list.lineItems.product.amount.custom.max` (integer)
    Maximum value of the custom payment amount, in minor units of a given currency.
    Example: 100000

  - `list.lineItems.product.currency` (string)
    Three-letter ISO currency code.
    Example: USD

  - `list.lineItems.product.plan` (string)
    Identifier of the plan that should be charged. Set on subscription items instead of `amount` and `currency`.
    Example: plan_bLu3vzO8yhAFhbxFEadm6HUV

  - `list.lineItems.product.taxes` (array)
    List of taxes applied to the product.

  - `list.lineItems.product.taxes.id` (string)
    Identifier of an existing tax entry.
    Example: tax_kPzT0OjFR9AwGiWtSvKMcHzP

  - `list.lineItems.product.taxes.name` (string)
    Tax name.
    Example: VAT

  - `list.lineItems.product.taxes.value` (number)
    Tax percentage.
    Example: 23

  - `list.lineItems.quantity` (number)
    Quantity of the defined product.
    Example: 1

  - `list.collectBillingAddress` (boolean)
    Whether the customer will be asked to provide the billing address.
    Example: true

  - `list.collectShippingAddress` (boolean)
    Whether the customer will be asked to provide the shipping address.
    Example: false

  - `list.customer` (string)
    If provided, the payment form will be linked to that customer. Saved cards may appear and the payment will be associated with the customer.
    Example: cust_QmR8kZvTnJyLbWpHdXcFgA3S

  - `list.customFieldsTitle` (string)
    Title of the custom fields section.
    Example: Additional information

  - `list.customFields` (array)
    List of custom fields used to request additional information from the customer. Each custom field is displayed in the form as a new text field to fill out.

  - `list.customFields.key` (string)
    Identifier of the custom field.
    Example: engraving

  - `list.customFields.label` (string)
    Label of the field shown on the Checkout form.
    Example: Engraving text

  - `list.customFields.value` (string)
    Value provided by the customer. Only present once the customer has filled in the field.
    Example: Happy Birthday

  - `list.customFields.optional` (boolean)
    If this flag is set to `true`, the customer does not have to provide a value for this custom field.
    Example: true

  - `list.staticFields` (array)
    List of static fields shown as additional information in the Checkout form. Static fields are informational only and cannot be edited by the customer.

  - `list.staticFields.key` (string)
    Title of the custom information.
    Example: Order no.

  - `list.staticFields.value` (string)
    Text of the custom information, shown under the specified key.
    Example: #21378

  - `list.capture` (boolean)
    Whether the charge should be captured. Useful for flows such as 0-auth checkouts.
    Example: true

  - `list.allowSavedCards` (boolean)
    Whether the payment form should display the option to save the customer's card details for future transactions. A customer must be assigned to use this option.
    Example: true

  - `list.action` (string)
    Action performed by the Checkout form.
    Enum: "payment", "card_verification"

  - `list.currency` (string)
    Three-letter ISO currency code. Used only for the `card_verification` action — for a regular payment, the currency from `lineItems` is used.
    Example: USD

  - `list.url` (string)
    Link to the payment form that can be used in the Checkout redirect flow.
    Example: https://pay.shift4.com/chse_LqM4nJ8vTyRbHwKpZdFcXaS2

  - `list.redirectUrl` (string)
    URL to which the customer will be redirected upon successful payment.
    Example: https://merchant-page.com/payment-success

  - `list.vendorReference` (string)
    Merchant-defined descriptor related to the payment link (for example, an invoice number). This field is reportable on the merchant portal and settlement extract.
    Example: custom_vendor_reference

  - `hasMore` (boolean)
    Whether more results exist beyond this page
    Example: true