Skip to content
Docs
APISign inStart free

Get a checkout session

The checkout.sessions.get operation: GET /api/v1/checkout/sessions/{id} in the REST API and the checkout_sessions_get tool in the MCP server.

GET/api/v1/checkout/sessions/{id}

Returns a checkout session of the brand in the mode of the request: its status (open, blocked, processing, complete, expired), line items, the current quote's totals and, once paid, the payment and the invoice. A session past its expiry reads as expired even before the expiry job has run.

Use it after the customer returns to your success URL (?cs_id=…): fulfil your side when the status is complete, or listen for checkout.session.completed.

At a glance

  • REST: GET /api/v1/checkout/sessions/{id}
  • MCP tool: checkout_sessions_get
  • Operation ID: checkout.sessions.get
  • Scope: Brand
  • Permission: checkout:read
  • Risk tier: read
  • Dry run: Not supported
  • Idempotency: Not needed (read only)
  • Modes: Test and live
  • Authentication: API key with the checkout:read scope
  • Since: M4

Request

Path parameters

FieldTypeDescription
idcs_… IDThe checkout session's ID (cs_…).

Query parameters

This operation takes no query parameters.

Response

200 OK with a JSON object:

FieldTypeDescription
idcs_… ID
object"checkout.session"
livemodeboolean
entityIdent_… ID
brandIdbrd_… ID
modeone of payment, subscription, topup, setup
statusone of open, processing, complete, expired, blockedopen, blocked (the sale is paused for the customer's location), processing, complete or expired.
urlstring or nullThe hosted page (with its session key); null once complete or expired.
lineItemsarray of object
lineItems[].idstringThe line's ID in the session's quotes and its invoice.
lineItems[].priceIdprice_… ID
lineItems[].productIdprod_… ID
lineItems[].priceTypeone of one_time, credit_pack, recurring
lineItems[].recurringobject or nullRecurring prices (subscription sessions): the billing interval and whether usage is metered.
lineItems[].adjustableQuantityobject or nullThe customer may change the quantity on the hosted page within these bounds.
lineItems[].discountmoney or nullSubscription sessions: what the promotion code takes off this line on the first invoice.
lineItems[].descriptionstringThe product's name when the session was created.
lineItems[].quantityinteger
lineItems[].customAmountmoney or null
lineItems[].amountmoneyBefore tax and discounts: gross for tax-inclusive prices, net for exclusive ones (a recurring price's first full period; zero for metered usage, billed later).
lineItems[].taxBehaviorone of inclusive, exclusive
currencystring
customerIdcus_… ID or null
customerEmailstring or null
successUrlstring or null
cancelUrlstring or null
localestring or null
collectBusinessDetailsone of auto, required, never
allowPromotionCodesbooleanThe hosted page offers a promotion code field.
promotionCodeIdpromo_… ID or nullThe promotion code applied to the session.
subscriptionDataobject or nullSubscription sessions: the trial and the subscription's metadata.
taxQuoteIdtq_… ID or nullThe current quote (tax.quotes.get explains it).
totalsobject or nullThe current quote's totals; null before the customer's details.
blockedReasonone of evidence_conflict, unsupported_tax_category, registration_required, rate_unavailable, jurisdiction_blocked, tax_id_unavailable or null
waitlistEntryIdwl_… ID or null
paymentIdpay_… ID or null
invoiceIdinv_… ID or null
subscriptionIdsub_… ID or nullSubscription sessions: the subscription created; setup sessions: the one the method is for.
paymentMethodIdpm_… ID or nullThe payment method saved (subscription and setup sessions).
expiresAtdate-time
completedAtdate-time or null
createdAtdate-time
metadataobject

Examples

A paid session

HTTP
GET /api/v1/checkout/sessions/cs_01m4tx5nj8emwbyf7y9vcf48aa
Authorization: Bearer or_test_…

Response (200):

JSON
{
  "id": "cs_01m4tx5nj8emwbyf7y9vcf48aa",
  "object": "checkout.session",
  "livemode": false,
  "entityId": "ent_01m4tx5nj8emwbyf7y9vcf47x2",
  "brandId": "brd_01m4tx5nj8emwbyf7y9vcf47x4",
  "mode": "payment",
  "status": "complete",
  "url": null,
  "lineItems": [
    {
      "id": "1",
      "priceId": "price_01m4tx5nj8emwbyf7y9vcf48ad",
      "productId": "prod_01m4tx5nj8emwbyf7y9vcf48ae",
      "priceType": "credit_pack",
      "recurring": null,
      "adjustableQuantity": null,
      "discount": null,
      "description": "Genno credits",
      "quantity": 1,
      "customAmount": null,
      "amount": {
        "amount": "100000000",
        "currency": "EUR"
      },
      "taxBehavior": "inclusive"
    }
  ],
  "currency": "EUR",
  "customerId": "cus_01m4tx5nj8emwbyf7y9vcf48ac",
  "customerEmail": "anna@example.com",
  "successUrl": "https://shop.example/thanks",
  "cancelUrl": "https://shop.example/cart",
  "locale": null,
  "collectBusinessDetails": "auto",
  "allowPromotionCodes": false,
  "promotionCodeId": null,
  "subscriptionData": null,
  "taxQuoteId": "tq_01m4tx5nj8emwbyf7y9vcf48ab",
  "totals": {
    "net": {
      "amount": "84033613",
      "currency": "EUR"
    },
    "tax": {
      "amount": "15966387",
      "currency": "EUR"
    },
    "gross": {
      "amount": "100000000",
      "currency": "EUR"
    }
  },
  "blockedReason": null,
  "waitlistEntryId": null,
  "paymentId": "pay_01m4tx5nj8emwbyf7y9vcf48af",
  "invoiceId": "inv_01m4tx5nj8emwbyf7y9vcf48ag",
  "subscriptionId": null,
  "paymentMethodId": null,
  "expiresAt": "2026-10-15T10:00:00.000Z",
  "completedAt": "2026-10-14T10:03:12.000Z",
  "createdAt": "2026-10-14T10:00:00.000Z",
  "metadata": {
    "order": "ord_1042"
  }
}

Errors

CodeHTTP statusWhenWhat to do
resource_not_found404No such checkout session for this brand and mode, or (on the hosted page) the session key is missing or wrong.Check the ID and that your credentials are scoped to the right organization, entity, brand and mode.

It can also return these common errors: validation_failed, api_version_unsupported, authentication_required, api_key_invalid, permission_denied, scope_required, dry_run_not_supported, rate_limited, internal_error.