FlintflintDocs

Checkout sessions

Checkout sessions create Flint-hosted payment pages for a single buyer. Each session is backed by an order: pass order_id to collect payment for an order you already created, quick_pay_item to have Flint create a simple one-time order for you, or plan_id to run hosted subscription signup from a subscription plan. The create response returns a tokenized buyer-facing url you redirect or link the buyer to.

Sessions are single-use. Generic sessions are short-lived (24 hours by default); invoice-owned sessions last for the life of the invoice's payment link. A session is open until the buyer completes payment, a mixed terminal attempt settles only part of the balance, you close it, it expires, or its source invalidates it. Terminal statuses are paid, partially_paid, closed, expired, and invalidated; terminal_reason explains the exact transition, including payment_succeeded and payment_partially_succeeded. Flint allows only one active session per order at a time. Creating another session for the same order returns CHECKOUT_SESSION_ALREADY_EXISTS unless you explicitly compare and replace the current session with replace_checkout_session_id. Configuration (theme, tipping, customer collection requirements, redirects, legal links, and expiration) is fixed at creation, and only metadata is mutable afterward.

Start with the Checkout sessions guide. Not sure whether you need a checkout session, a payment link, or an invoice? See Payment links vs checkout sessions vs invoices.

Endpoints

List checkout sessions#

GET/v1/checkout-sessionsRequires scope: checkouts.checkout_sessions.read or checkouts.checkout_sessions.write

Returns a paginated list of checkout sessions for the authenticated merchant.

Query parameters
page_sizeinteger

Page size, default 20, max 100.

page_tokenstring

Cursor returned by the previous list response.

statusenum

Filter by checkout session status.

openpaidpartially_paidexpiredclosedinvalidated
order_idstring

Filter by Flint order ID.

payment_link_idstring

Filter by Flint payment link ID.

customer_idstring

Filter by Flint customer ID.

originenum

Filter by checkout session origin.

virtual_terminalpayment_linkcheckoutapisubscription
querystring

Search across session metadata keys/values and payment notes.

sort_byenum

Sort field.

created_atupdated_at
sort_directionenum

Sort direction.

ascdesc
created_afterstring

RFC3339 lower bound for created_at.

created_beforestring

RFC3339 upper bound for created_at.

updated_afterstring

RFC3339 lower bound for updated_at.

updated_beforestring

RFC3339 upper bound for updated_at.

expires_afterstring

RFC3339 lower bound for expires_at.

expires_beforestring

RFC3339 upper bound for expires_at.

Response · 200
dataarray of objectrequired
metaobject
next_page_tokenstring
request_idstring

Error codes

AUTH_REQUIREDINSUFFICIENT_SCOPEINVALID_API_KEYINVALID_REQUESTRATE_LIMIT_EXCEEDED
Bash
curl https://api.withflintpay.com/v1/checkout-sessions \
  -H "Authorization: Bearer YOUR_API_KEY"
JSON
{
  "data": [
    {
      "checkout_session_id": "cs_123",
      "surface": "hosted",
      "delivery_method_ids": null,
      "theme": {
        "primary_color": "#0f766e",
        "title": "Spring Gala Checkout"
      },
      "payments": {
        "enabled_payment_options": [
          "card",
          "apple_pay",
          "google_pay"
        ],
        "payment_note": "Thank you for your purchase."
      },
      "customer_collection": {
        "require_email": true
      },
      "redirects": {
        "success_redirect_url": "https://example.com/success",
        "cancel_redirect_url": "https://example.com/canceled"
      },
      "metadata": {
        "campaign": "spring_launch"
      },
      "status": "open",
      "order_id": "ord_123",
      "merchant_id": "mer_123",
      "created_at": "2026-03-17T14:30:00Z",
      "updated_at": "2026-03-17T14:30:00Z",
      "url": "https://checkout.withflintpay.com/checkout/cs_123#checkout_token=tok_123",
      "origin": "api",
      "promotion_config": {
        "codes_enabled": true
      },
      "recovery_mode": false,
      "delivery_selection_required": false,
      "problems": null
    }
  ],
  "next_page_token": "Zm9yd2FyZC1vbmx5LW9wYXF1ZS1jdXJzb3I",
  "request_id": "bce56cba-0827-44aa-bb56-4f200ba15ee6"
}

Create checkout session#

POST/v1/checkout-sessionsIdempotentRequires scope: checkouts.checkout_sessions.write

Creates a hosted or embedded checkout session for an order, quick-pay charge, or subscription plan signup. Creation never implicitly replaces an open order session. To replace one, send order_id with replace_checkout_session_id set to the expected current session; the compare-and-swap replacement and collection-lock transfer commit atomically.

Request body
option 1object
option 2object
option 3object
option 4object
Response · 201
dataobjectrequired

Checkout-session access returned for hosted or embedded checkout creation.

metaobject
request_idstring

Error codes

AUTH_REQUIREDEMBEDDED_PAYMENT_RETURN_URL_REQUIREDINSUFFICIENT_SCOPEINVALID_API_KEYINVALID_REQUESTRATE_LIMIT_EXCEEDED
Bash
curl -X POST https://api.withflintpay.com/v1/checkout-sessions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: a-unique-key" \
  -d '{
    "quick_pay_item": {
      "name": "Service Fee",
      "amount_money": {
        "amount": 2500,
        "currency": "USD"
      }
    },
    "theme": {
      "primary_color": "#0f766e",
      "title": "Spring Gala Checkout"
    },
    "payments": {
      "enabled_payment_options": [
        "card",
        "apple_pay",
        "google_pay"
      ],
      "payment_note": "Thank you for your purchase."
    },
    "customer_collection": {
      "require_email": true
    },
    "redirects": {
      "success_redirect_url": "https://example.com/success",
      "cancel_redirect_url": "https://example.com/canceled"
    },
    "metadata": {
      "campaign": "spring_launch"
    },
    "promotion_config": {
      "codes_enabled": true
    },
    "surface": ""
  }'
JSON
{
  "data": {
    "checkout_session": {
      "checkout_session_id": "cs_123",
      "surface": "hosted",
      "delivery_method_ids": null,
      "theme": {
        "primary_color": "#0f766e",
        "title": "Spring Gala Checkout"
      },
      "payments": {
        "enabled_payment_options": [
          "card",
          "apple_pay",
          "google_pay"
        ],
        "payment_note": "Thank you for your purchase."
      },
      "customer_collection": {
        "require_email": true
      },
      "redirects": {
        "success_redirect_url": "https://example.com/success",
        "cancel_redirect_url": "https://example.com/canceled"
      },
      "metadata": {
        "campaign": "spring_launch"
      },
      "status": "open",
      "order_id": "ord_123",
      "merchant_id": "mer_123",
      "created_at": "2026-03-17T14:30:00Z",
      "updated_at": "2026-03-17T14:30:00Z",
      "url": "https://checkout.withflintpay.com/checkout/cs_123#checkout_token=tok_123",
      "origin": "api",
      "promotion_config": {
        "codes_enabled": true
      },
      "recovery_mode": false,
      "delivery_selection_required": false,
      "problems": null
    },
    "hosted_checkout": {
      "url": "https://checkout.withflintpay.com/checkout/cs_123#checkout_token=tok_123",
      "checkout_auth_token": "ckat_v1.example_session_credential"
    },
    "checkout_access": {
      "checkout_auth_token": "ckat_v1.example_session_credential",
      "hosted_url": "https://checkout.withflintpay.com/checkout/cs_123#checkout_token=tok_123"
    }
  },
  "request_id": "bce56cba-0827-44aa-bb56-4f200ba15ee6"
}

Get checkout session#

GET/v1/checkout-sessions/{checkout_session_id}Requires scope: checkouts.checkout_sessions.read or checkouts.checkout_sessions.write

Returns a single checkout session by ID.

Path parameters
checkout_session_idstringrequired

Flint checkout session ID.

Query parameters
expandarray of enum

Supported expansions: customer, invoice, order, payment_intents, payment_link. Expansion requires checkouts.checkout_sessions.read plus the read scope for each expanded resource. Limits: at most 10 unique expand paths per request; path depth at most 2. To-many expansions are capped at 20 related objects per path. Send repeated expand parameters as the canonical form, for example expand=customer&expand=invoice. Comma-separated values, expand[]=customer, and numeric expand[0]=customer are accepted for common client compatibility.

customerinvoiceorderpayment_intentspayment_link
Response · 200
dataobjectrequired
metaobject
request_idstring

Error codes

AUTH_REQUIREDDANGLING_EXPANSION_REFERENCEEXPANSION_DEPENDENCY_UNAVAILABLEEXPANSION_RESOLUTION_FAILEDINSUFFICIENT_SCOPEINTERNAL_ERRORINVALID_API_KEYINVALID_REQUESTRATE_LIMIT_EXCEEDEDRESOURCE_NOT_FOUNDSERVICE_UNAVAILABLE
Bash
curl https://api.withflintpay.com/v1/checkout-sessions/cs_123 \
  -H "Authorization: Bearer YOUR_API_KEY"

Update checkout session#

PATCH/v1/checkout-sessions/{checkout_session_id}IdempotentRequires scope: checkouts.checkout_sessions.write

Updates mutable checkout session fields. Currently only metadata is mutable.

Path parameters
checkout_session_idstringrequired

Flint checkout session ID.

Request body
metadatamap of string
Response · 200
dataobjectrequired
metaobject
request_idstring

Error codes

AUTH_REQUIREDINSUFFICIENT_SCOPEINVALID_API_KEYINVALID_REQUESTRATE_LIMIT_EXCEEDEDRESOURCE_NOT_FOUND
Bash
curl -X PATCH https://api.withflintpay.com/v1/checkout-sessions/cs_123 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: a-unique-key" \
  -d '{
    "metadata": {
      "campaign": "spring_launch",
      "channel": "email"
    }
  }'
JSON
{
  "data": {
    "checkout_session_id": "cs_123",
    "surface": "hosted",
    "delivery_method_ids": null,
    "theme": {
      "primary_color": "#0f766e",
      "title": "Spring Gala Checkout"
    },
    "payments": {
      "enabled_payment_options": [
        "card",
        "apple_pay",
        "google_pay"
      ],
      "payment_note": "Thank you for your purchase."
    },
    "customer_collection": {
      "require_email": true
    },
    "redirects": {
      "success_redirect_url": "https://example.com/success",
      "cancel_redirect_url": "https://example.com/canceled"
    },
    "metadata": {
      "campaign": "spring_launch"
    },
    "status": "open",
    "order_id": "ord_123",
    "merchant_id": "mer_123",
    "created_at": "2026-03-17T14:30:00Z",
    "updated_at": "2026-03-17T14:30:00Z",
    "url": "https://checkout.withflintpay.com/checkout/cs_123#checkout_token=tok_123",
    "origin": "api",
    "promotion_config": {
      "codes_enabled": true
    },
    "recovery_mode": false,
    "delivery_selection_required": false,
    "problems": null
  },
  "request_id": "bce56cba-0827-44aa-bb56-4f200ba15ee6"
}

Close checkout session#

POST/v1/checkout-sessions/{checkout_session_id}/closeIdempotentRequires scope: checkouts.checkout_sessions.write

Closes an open checkout session before it naturally expires.

Path parameters
checkout_session_idstringrequired

Flint checkout session ID.

Request body
reasonstring
Response · 200
dataobjectrequired
metaobject
request_idstring

Error codes

AUTH_REQUIREDINSUFFICIENT_SCOPEINVALID_API_KEYINVALID_REQUESTRATE_LIMIT_EXCEEDEDRESOURCE_NOT_FOUND
Bash
curl -X POST https://api.withflintpay.com/v1/checkout-sessions/cs_123/close \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: a-unique-key" \
  -d '{
    "reason": "Merchant closed stale session"
  }'
JSON
{
  "data": {
    "checkout_session_id": "cs_123",
    "surface": "hosted",
    "delivery_method_ids": null,
    "theme": {
      "primary_color": "#0f766e",
      "title": "Spring Gala Checkout"
    },
    "payments": {
      "enabled_payment_options": [
        "card",
        "apple_pay",
        "google_pay"
      ],
      "payment_note": "Thank you for your purchase."
    },
    "customer_collection": {
      "require_email": true
    },
    "redirects": {
      "success_redirect_url": "https://example.com/success",
      "cancel_redirect_url": "https://example.com/canceled"
    },
    "metadata": {
      "campaign": "spring_launch"
    },
    "status": "open",
    "order_id": "ord_123",
    "merchant_id": "mer_123",
    "created_at": "2026-03-17T14:30:00Z",
    "updated_at": "2026-03-17T14:30:00Z",
    "url": "https://checkout.withflintpay.com/checkout/cs_123#checkout_token=tok_123",
    "origin": "api",
    "promotion_config": {
      "codes_enabled": true
    },
    "recovery_mode": false,
    "delivery_selection_required": false,
    "problems": null
  },
  "request_id": "bce56cba-0827-44aa-bb56-4f200ba15ee6"
}

Query checkout pickup availability#

POST/v1/checkout-sessions/{checkout_session_id}/query-pickup-availabilityRequires scope: commerce.delivery.read or commerce.delivery.write

Computes a bounded, non-holding pickup-location projection from current checkout authority and one inventory snapshot. Merchant-authenticated requests include configured Location diagnostics; checkout credentials receive only buyer-safe results.

Path parameters
checkout_session_idstringrequired

Flint checkout session ID.

Request body
buyer_locationone of
expected_delivery_selection_idstring
maximum_distanceobject
Response · 200
dataobjectrequired
metaobject
request_idstring

Error codes

AUTH_REQUIREDDELIVERY_CALCULATION_EXPIREDDELIVERY_CALLER_RATES_UNAVAILABLE_TO_BUYERDELIVERY_COMMERCE_TREATMENT_UNSUPPORTEDDELIVERY_DESTINATION_INVALIDDELIVERY_ELIGIBILITY_CONTEXT_CHANGEDDELIVERY_FIELD_NOT_SUPPORTEDDELIVERY_FIELD_REQUIREDDELIVERY_GROUPING_UNSUPPORTEDDELIVERY_MERCHANT_INPUT_REQUIREDDELIVERY_METHOD_SERVICE_UNAVAILABLEDELIVERY_PICKUP_AVAILABILITY_CHANGEDDELIVERY_PICKUP_AVAILABILITY_INVALIDDELIVERY_PICKUP_AVAILABILITY_UNAVAILABLEDELIVERY_PICKUP_LOCATION_UNAVAILABLEDELIVERY_QUOTE_BASIS_INVALIDDELIVERY_QUOTE_EXPIREDDELIVERY_QUOTE_INCOMPLETEDELIVERY_QUOTE_INPUT_CHANGEDDELIVERY_QUOTE_INVALIDDELIVERY_QUOTE_REVOKEDDELIVERY_QUOTE_STALEDELIVERY_QUOTE_UNAVAILABLEDELIVERY_REQUEST_INVALIDDELIVERY_SERVICE_UNAVAILABLEDELIVERY_WINDOW_EXPIREDDELIVERY_WINDOW_INVALIDINSUFFICIENT_SCOPEINVALID_REQUESTRATE_LIMIT_EXCEEDEDRESOURCE_NOT_FOUNDSERVICE_UNAVAILABLE
Bash
curl -X POST https://api.withflintpay.com/v1/checkout-sessions/cs_123/query-pickup-availability \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "buyer_location": {
      "type": "address"
    },
    "expected_delivery_selection_id": "",
    "maximum_distance": {
      "unit": "meters",
      "value": 0
    }
  }'
Rate this doc