FlintflintDocs

Delivery quotes

Delivery quotes are persisted, time-bounded evaluations of the delivery methods assigned to a checkout. Each required choice group contains the options that can satisfy its line items.

Create a new quote whenever the cart, destination, pickup location, current selection, or required callback input changes. Send the current expected_delivery_selection_id, including null when no selection exists, so a stale browser cannot replace a newer choice.

Buyer-authenticated responses expose only buyer-actionable buyer_reasons. Merchant-authenticated responses include method-level diagnostics and dependency evidence for configuration debugging. Deterministic pricing receives a longer quote lifetime; callback, calculated, or caller-supplied pricing keeps the short expiry bound.

Endpoints

Create delivery quote#

POST/v1/checkout-sessions/{checkout_session_id}/delivery-quotesIdempotentRequires scope: commerce.delivery.write

Creates an exact checkout-bound delivery quote without holding inventory.

Path parameters
checkout_session_idstringrequired

Flint checkout session ID.

Request body
basis_delivery_quote_idstring
buyer_locationone of
destination_addressobject
expected_delivery_selection_idstringrequired

Current delivery selection ID used for compare-and-swap. Send null to assert that no selection exists.

inventory_assignmentsarray of object
method_resultsarray of object
pickup_location_idstring
tier_keyinteger

Caller-defined nonnegative lookup key used by methods whose tiered pricing basis is caller.tier_key. Merchant authentication is required.

Response · 201
dataone ofrequired
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_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/delivery-quotes \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: a-unique-key" \
  -d '{
    "expected_delivery_selection_id": "example"
  }'
JSON
{
  "data": {
    "audience": "merchant",
    "checkout_session_id": "cs_01K1P6G4M7H2N8Q9R3S5T6V7WX",
    "choice_groups": [
      {
        "availability_status": "ready",
        "delivery_choice_group_id": "dcgrp_01K1P6G4M7H2N8Q9R3S5T6V7WX",
        "evaluation_status": "complete",
        "input_requirements": [
          {
            "constraint": {
              "type": "string"
            },
            "delivery_input_requirement_id": "example",
            "field_path": "destination_address",
            "purpose": "quote"
          }
        ],
        "line_items": [
          {
            "order_line_item_id": "example",
            "quantity": 1
          }
        ],
        "options": [
          {
            "amount_money": {
              "amount": 1,
              "currency": "USD"
            },
            "delivery_method_id": "dmet_01K1P6G4M7H2N8Q9R3S5T6V7WX",
            "delivery_plan": {
              "type": "single_delivery"
            },
            "display_position": 1,
            "name": "Standard delivery",
            "recommended": true,
            "taxable": true,
            "type": "shipment",
            "window_selection": "none"
          }
        ],
        "stable_key": "example"
      }
    ],
    "delivery_quote_id": "dqt_01K1P6G4M7H2N8Q9R3S5T6V7WX",
    "delivery_quote_revision": 0,
    "eligibility_context_revision": 0,
    "evaluated_at": "2026-08-02T16:00:00Z",
    "evaluation_status": "complete",
    "expires_at": "2026-08-02T16:00:00Z",
    "input_requirements": [
      {
        "constraint": {
          "type": "string"
        },
        "delivery_input_requirement_id": "example",
        "field_path": "destination_address",
        "purpose": "quote"
      }
    ],
    "merchant_diagnostics": [
      {
        "code": "ELIGIBILITY_NO_MATCH",
        "diagnostic_id": "example",
        "occurred_at": "2026-08-02T16:00:00Z",
        "outcome": "unavailable",
        "recommended_action": "review_configuration",
        "retryable": true,
        "scope": "method",
        "summary": "example"
      }
    ],
    "order_id": "ord_01K1P6G4M7H2N8Q9R3S5T6V7WX",
    "selection_required": true,
    "status": "active"
  },
  "request_id": "req_01K1P6G4M7H2N8Q9R3S5T6V7WX"
}

Get checkout delivery quote#

GET/v1/checkout-sessions/{checkout_session_id}/delivery-quotes/{delivery_quote_id}Requires scope: commerce.delivery.read or commerce.delivery.write

Returns one quote under its checkout authority. Buyer credentials receive the buyer-safe projection.

Path parameters
checkout_session_idstringrequired

Flint checkout session ID.

delivery_quote_idstringrequired

Flint delivery quote ID.

Response · 200
dataone ofrequired
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_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 https://api.withflintpay.com/v1/checkout-sessions/cs_123/delivery-quotes/dqt_01K1P6G4M7H2N8Q9R3S5T6V7WX \
  -H "Authorization: Bearer YOUR_API_KEY"
JSON
{
  "data": {
    "audience": "merchant",
    "checkout_session_id": "cs_01K1P6G4M7H2N8Q9R3S5T6V7WX",
    "choice_groups": [
      {
        "availability_status": "ready",
        "delivery_choice_group_id": "dcgrp_01K1P6G4M7H2N8Q9R3S5T6V7WX",
        "evaluation_status": "complete",
        "input_requirements": [
          {
            "constraint": {
              "type": "string"
            },
            "delivery_input_requirement_id": "example",
            "field_path": "destination_address",
            "purpose": "quote"
          }
        ],
        "line_items": [
          {
            "order_line_item_id": "example",
            "quantity": 1
          }
        ],
        "options": [
          {
            "amount_money": {
              "amount": 1,
              "currency": "USD"
            },
            "delivery_method_id": "dmet_01K1P6G4M7H2N8Q9R3S5T6V7WX",
            "delivery_plan": {
              "type": "single_delivery"
            },
            "display_position": 1,
            "name": "Standard delivery",
            "recommended": true,
            "taxable": true,
            "type": "shipment",
            "window_selection": "none"
          }
        ],
        "stable_key": "example"
      }
    ],
    "delivery_quote_id": "dqt_01K1P6G4M7H2N8Q9R3S5T6V7WX",
    "delivery_quote_revision": 0,
    "eligibility_context_revision": 0,
    "evaluated_at": "2026-08-02T16:00:00Z",
    "evaluation_status": "complete",
    "expires_at": "2026-08-02T16:00:00Z",
    "input_requirements": [
      {
        "constraint": {
          "type": "string"
        },
        "delivery_input_requirement_id": "example",
        "field_path": "destination_address",
        "purpose": "quote"
      }
    ],
    "merchant_diagnostics": [
      {
        "code": "ELIGIBILITY_NO_MATCH",
        "diagnostic_id": "example",
        "occurred_at": "2026-08-02T16:00:00Z",
        "outcome": "unavailable",
        "recommended_action": "review_configuration",
        "retryable": true,
        "scope": "method",
        "summary": "example"
      }
    ],
    "order_id": "ord_01K1P6G4M7H2N8Q9R3S5T6V7WX",
    "selection_required": true,
    "status": "active"
  },
  "request_id": "req_01K1P6G4M7H2N8Q9R3S5T6V7WX"
}

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

List delivery quotes#

GET/v1/delivery-quotesRequires scope: commerce.delivery.read or commerce.delivery.write

Returns persisted delivery quote diagnostics in stable creation order.

Query parameters
checkout_session_idstring

Filter by checkout session.

order_idstring

Filter by order.

statusenum

Filter by lifecycle status.

activeconsumedstaleexpiredrevoked
evaluation_statusenum

Filter by evaluation status.

completeincompletedegraded
created_afterstring

Inclusive RFC 3339 creation lower bound.

created_beforestring

Inclusive RFC 3339 creation upper bound.

page_sizeinteger

Number of quotes to return.

page_tokenstring

Opaque cursor from the previous page.

Response · 200
dataarray of objectrequired
metaobject
next_page_tokenstring
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_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_EXCEEDEDSERVICE_UNAVAILABLE
Bash
curl https://api.withflintpay.com/v1/delivery-quotes \
  -H "Authorization: Bearer YOUR_API_KEY"
JSON
{
  "data": [
    {
      "audience": "merchant",
      "checkout_session_id": "cs_01K1P6G4M7H2N8Q9R3S5T6V7WX",
      "choice_groups": [
        {
          "availability_status": "ready",
          "delivery_choice_group_id": "dcgrp_01K1P6G4M7H2N8Q9R3S5T6V7WX",
          "evaluation_status": "complete",
          "input_requirements": [
            {
              "constraint": {
                "type": "string"
              },
              "delivery_input_requirement_id": "example",
              "field_path": "destination_address",
              "purpose": "quote"
            }
          ],
          "line_items": [
            {
              "order_line_item_id": "example",
              "quantity": 1
            }
          ],
          "options": [
            {
              "amount_money": {
                "amount": 1,
                "currency": "USD"
              },
              "delivery_method_id": "dmet_01K1P6G4M7H2N8Q9R3S5T6V7WX",
              "delivery_plan": {
                "type": "single_delivery"
              },
              "display_position": 1,
              "name": "Standard delivery",
              "recommended": true,
              "taxable": true,
              "type": "shipment",
              "window_selection": "none"
            }
          ],
          "stable_key": "example"
        }
      ],
      "delivery_quote_id": "dqt_01K1P6G4M7H2N8Q9R3S5T6V7WX",
      "delivery_quote_revision": 0,
      "eligibility_context_revision": 0,
      "evaluated_at": "2026-08-02T16:00:00Z",
      "evaluation_status": "complete",
      "expires_at": "2026-08-02T16:00:00Z",
      "input_requirements": [
        {
          "constraint": {
            "type": "string"
          },
          "delivery_input_requirement_id": "example",
          "field_path": "destination_address",
          "purpose": "quote"
        }
      ],
      "merchant_diagnostics": [
        {
          "code": "ELIGIBILITY_NO_MATCH",
          "diagnostic_id": "example",
          "occurred_at": "2026-08-02T16:00:00Z",
          "outcome": "unavailable",
          "recommended_action": "review_configuration",
          "retryable": true,
          "scope": "method",
          "summary": "example"
        }
      ],
      "order_id": "ord_01K1P6G4M7H2N8Q9R3S5T6V7WX",
      "selection_required": true,
      "status": "active"
    }
  ],
  "next_page_token": "page_2",
  "request_id": "req_01K1P6G4M7H2N8Q9R3S5T6V7WX"
}

Get delivery quote#

GET/v1/delivery-quotes/{delivery_quote_id}Requires scope: commerce.delivery.read or commerce.delivery.write

Returns one persisted delivery quote and its current derived lifecycle.

Path parameters
delivery_quote_idstringrequired

Flint delivery quote ID.

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_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 https://api.withflintpay.com/v1/delivery-quotes/dqt_01K1P6G4M7H2N8Q9R3S5T6V7WX \
  -H "Authorization: Bearer YOUR_API_KEY"
JSON
{
  "data": {
    "audience": "merchant",
    "checkout_session_id": "cs_01K1P6G4M7H2N8Q9R3S5T6V7WX",
    "choice_groups": [
      {
        "availability_status": "ready",
        "delivery_choice_group_id": "dcgrp_01K1P6G4M7H2N8Q9R3S5T6V7WX",
        "evaluation_status": "complete",
        "input_requirements": [
          {
            "constraint": {
              "type": "string"
            },
            "delivery_input_requirement_id": "example",
            "field_path": "destination_address",
            "purpose": "quote"
          }
        ],
        "line_items": [
          {
            "order_line_item_id": "example",
            "quantity": 1
          }
        ],
        "options": [
          {
            "amount_money": {
              "amount": 1,
              "currency": "USD"
            },
            "delivery_method_id": "dmet_01K1P6G4M7H2N8Q9R3S5T6V7WX",
            "delivery_plan": {
              "type": "single_delivery"
            },
            "display_position": 1,
            "name": "Standard delivery",
            "recommended": true,
            "taxable": true,
            "type": "shipment",
            "window_selection": "none"
          }
        ],
        "stable_key": "example"
      }
    ],
    "delivery_quote_id": "dqt_01K1P6G4M7H2N8Q9R3S5T6V7WX",
    "delivery_quote_revision": 0,
    "eligibility_context_revision": 0,
    "evaluated_at": "2026-08-02T16:00:00Z",
    "evaluation_status": "complete",
    "expires_at": "2026-08-02T16:00:00Z",
    "input_requirements": [
      {
        "constraint": {
          "type": "string"
        },
        "delivery_input_requirement_id": "example",
        "field_path": "destination_address",
        "purpose": "quote"
      }
    ],
    "merchant_diagnostics": [
      {
        "code": "ELIGIBILITY_NO_MATCH",
        "diagnostic_id": "example",
        "occurred_at": "2026-08-02T16:00:00Z",
        "outcome": "unavailable",
        "recommended_action": "review_configuration",
        "retryable": true,
        "scope": "method",
        "summary": "example"
      }
    ],
    "order_id": "ord_01K1P6G4M7H2N8Q9R3S5T6V7WX",
    "selection_required": true,
    "status": "active"
  },
  "request_id": "req_01K1P6G4M7H2N8Q9R3S5T6V7WX"
}
Rate this doc