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 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 and short-lived. A session is open until the buyer completes payment, you close it, or it expires; Flint allows only one active session per order at a time. 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-sessions

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.

openpaidexpiredclosedinvalidated
order_idstring

Filter by Flint order ID.

payment_link_idstring

Filter by Flint payment link ID.

customer_idstring

Filter by Flint customer ID.

sourceenum

Filter by checkout session source.

virtual_terminalpayment_linkcheckoutapiin_personsubscription
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
Bash
curl https://api.withflintpay.com/v1/checkout-sessions \
  -H "Authorization: Bearer YOUR_API_KEY"
JSON
{
  "data": [
    {
      "checkout_session_id": "cs_123",
      "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",
      "source": "api",
      "coupon": {
        "enabled": true
      }
    }
  ],
  "next_page_token": "Zm9yd2FyZC1vbmx5LW9wYXF1ZS1jdXJzb3I",
  "request_id": "bce56cba-0827-44aa-bb56-4f200ba15ee6"
}

Create checkout session#

POST/v1/checkout-sessionsIdempotent

Creates a hosted checkout session for an order, quick-pay charge, or subscription plan signup.

Request body
option 1object
option 2object
option 3object
Response · 201
dataobjectrequired
metaobject
request_idstring
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"
    },
    "coupon": {
      "enabled": true
    }
  }'
JSON
{
  "data": {
    "checkout_session_id": "cs_123",
    "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",
    "source": "api",
    "coupon": {
      "enabled": true
    }
  },
  "request_id": "bce56cba-0827-44aa-bb56-4f200ba15ee6"
}

Get checkout session#

GET/v1/checkout-sessions/{checkout_session_id}

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
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}Idempotent

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
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",
    "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",
    "source": "api",
    "coupon": {
      "enabled": true
    }
  },
  "request_id": "bce56cba-0827-44aa-bb56-4f200ba15ee6"
}

Close checkout session#

POST/v1/checkout-sessions/{checkout_session_id}/closeIdempotent

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
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",
    "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",
    "source": "api",
    "coupon": {
      "enabled": true
    }
  },
  "request_id": "bce56cba-0827-44aa-bb56-4f200ba15ee6"
}

List checkout fulfillment options#

GET/v1/checkout-sessions/{checkout_session_id}/fulfillment-options

Returns the shipment, pickup, and delivery options available for an open checkout session.

Path parameters
checkout_session_idstringrequired

Flint checkout session ID.

Query parameters
page_sizeinteger

Page size, default 20, max 100.

page_tokenstring

Cursor returned by the previous list response.

Response · 200
dataarray of objectrequired
metaobject
next_page_tokenstring
request_idstring
Bash
curl https://api.withflintpay.com/v1/checkout-sessions/cs_123/fulfillment-options \
  -H "Authorization: Bearer YOUR_API_KEY"
JSON
{
  "data": [
    {
      "fulfillment_option_id": "fopt_01HZYV7Q9Y0Y4H8Q3H9F6R7T8J",
      "name": "Standard shipping",
      "selected_by_default": false,
      "type": "shipment"
    }
  ],
  "next_page_token": "Zm9yd2FyZC1vbmx5LW9wYXF1ZS1jdXJzb3I",
  "request_id": "bce56cba-0827-44aa-bb56-4f200ba15ee6"
}

Get checkout fulfillment selection#

GET/v1/checkout-sessions/{checkout_session_id}/fulfillment-selection

Returns the currently selected fulfillment option snapshot for a checkout session, if one exists.

Path parameters
checkout_session_idstringrequired

Flint checkout session ID.

Response · 200
dataobject
metaobject
request_idstring
Bash
curl https://api.withflintpay.com/v1/checkout-sessions/cs_123/fulfillment-selection \
  -H "Authorization: Bearer YOUR_API_KEY"
JSON
{
  "data": {
    "fulfillment_option_id": "fopt_01HZYV7Q9Y0Y4H8Q3H9F6R7T8J",
    "fulfillment_selection_id": "fsel_01HZYV7Q9Y0Y4H8Q3H9F6R7T8J",
    "line_items": [
      {
        "order_line_item_id": "li_01HZYV7Q9Y0Y4H8Q3H9F6R7T8J",
        "quantity": 1
      }
    ],
    "name": "Standard shipping",
    "type": "shipment"
  },
  "request_id": "bce56cba-0827-44aa-bb56-4f200ba15ee6"
}

Set checkout fulfillment selection#

POST/v1/checkout-sessions/{checkout_session_id}/fulfillment-selectionIdempotent

Selects a fulfillment option for a checkout session and applies the linked fulfillment fee to the order total.

Path parameters
checkout_session_idstringrequired

Flint checkout session ID.

Request body
fulfillment_option_idstringrequired
recipientobject
Response · 200
dataobject
metaobject
request_idstring
Bash
curl -X POST https://api.withflintpay.com/v1/checkout-sessions/cs_123/fulfillment-selection \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: a-unique-key" \
  -d '{
    "fulfillment_option_id": "fopt_01HZYV7Q9Y0Y4H8Q3H9F6R7T8J"
  }'
JSON
{
  "data": {
    "fulfillment_option_id": "fopt_01HZYV7Q9Y0Y4H8Q3H9F6R7T8J",
    "fulfillment_selection_id": "fsel_01HZYV7Q9Y0Y4H8Q3H9F6R7T8J",
    "line_items": [
      {
        "order_line_item_id": "li_01HZYV7Q9Y0Y4H8Q3H9F6R7T8J",
        "quantity": 1
      }
    ],
    "name": "Standard shipping",
    "type": "shipment"
  },
  "request_id": "bce56cba-0827-44aa-bb56-4f200ba15ee6"
}
Rate this doc