FlintflintDocs

Delivery selections

A delivery selection records one chosen option for every required choice group in a quote. The selected price, tax treatment, window, origin, and execution legs are immutable evidence used when Flint commits checkout to the order.

Create a selection with the quote ID and each chosen option ID. Include a window ID only when the option offers windows. Replacing or clearing a selection requires the current selection ID, which prevents an older browser tab from overwriting a newer buyer choice.

The checkout route returns the effective selection while it is provisional and after it is committed. The order route exposes the committed selection for merchant reconciliation.

Endpoints

Create delivery selection#

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

Atomically selects one option per choice group, replaces inventory holds, and recalculates checkout economics.

Path parameters
checkout_session_idstringrequired

Flint checkout session ID.

Request body
choicesarray of objectrequired
delivery_quote_idstringrequired
destination_addressobject
expected_delivery_selection_idstringrequired

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

external_reference_idstring
external_systemstring
recipientobject
Response · 201
dataone ofrequired
metaobject
request_idstring

Error codes

AUTH_REQUIREDDELIVERY_ELIGIBILITY_CONTEXT_CHANGEDDELIVERY_EXPECTED_SELECTION_REQUIREDDELIVERY_EXTERNAL_REFERENCE_REUSEDDELIVERY_OPTION_ALREADY_SELECTEDDELIVERY_OPTION_EXPIREDDELIVERY_OPTION_NOT_IN_CHOICE_GROUPDELIVERY_QUOTE_EXPIREDDELIVERY_QUOTE_INPUT_CHANGEDDELIVERY_QUOTE_REVOKEDDELIVERY_SELECTION_CHANGEDDELIVERY_SELECTION_EXPIREDDELIVERY_SELECTION_INCOMPLETEDELIVERY_SELECTION_REPLACEMENT_LIMITDELIVERY_SELECTION_UNAVAILABLEDELIVERY_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-selections \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: a-unique-key" \
  -d '{
    "choices": [
      {
        "delivery_choice_group_id": "dcgrp_01K1P6G4M7H2N8Q9R3S5T6V7WX",
        "delivery_option_id": "dopt_01K1P6G4M7H2N8Q9R3S5T6V7WX"
      }
    ],
    "delivery_quote_id": "dqt_01K1P6G4M7H2N8Q9R3S5T6V7WX",
    "expected_delivery_selection_id": "example"
  }'
JSON
{
  "data": {
    "audience": "merchant",
    "checkout_session": {
      "checkout_session_id": "cs_01K1P6G4M7H2N8Q9R3S5T6V7WX",
      "delivery_method_ids": [
        "example"
      ],
      "delivery_selection_required": true,
      "problems": [
        {
          "blocks_completion": true,
          "code": "delivery_selection_stale",
          "severity": "error"
        }
      ],
      "recovery_mode": true,
      "status": "open",
      "surface": "hosted"
    },
    "delivery_selection": {
      "amount_money": {
        "amount": 1,
        "currency": "USD"
      },
      "calculation_expires_at": "2026-08-02T16:00:00Z",
      "checkout_session_id": "cs_01K1P6G4M7H2N8Q9R3S5T6V7WX",
      "choices": [
        {
          "amount_money": {
            "amount": 1,
            "currency": "USD"
          },
          "delivery_choice_group_id": "dcgrp_01K1P6G4M7H2N8Q9R3S5T6V7WX",
          "delivery_method_id": "dmet_01K1P6G4M7H2N8Q9R3S5T6V7WX",
          "delivery_option_id": "dopt_01K1P6G4M7H2N8Q9R3S5T6V7WX",
          "delivery_plan": {
            "type": "single_delivery"
          },
          "discount_money": {
            "amount": 1,
            "currency": "USD"
          },
          "name": "Standard delivery",
          "stable_key": "example",
          "tax_money": {
            "amount": 1,
            "currency": "USD"
          },
          "total_money": {
            "amount": 1,
            "currency": "USD"
          },
          "type": "shipment"
        }
      ],
      "created_at": "2026-08-02T16:00:00Z",
      "delivery_quote_id": "dqt_01K1P6G4M7H2N8Q9R3S5T6V7WX",
      "delivery_quote_revision": 0,
      "delivery_selection_id": "dsel_01K1P6G4M7H2N8Q9R3S5T6V7WX",
      "eligibility_context_revision": 0,
      "expires_at": "2026-08-02T16:00:00Z",
      "lifecycle_updated_at": "2026-08-02T16:00:00Z",
      "limiting_deadline_reason": "selection_guarantee_expiry",
      "order_id": "ord_01K1P6G4M7H2N8Q9R3S5T6V7WX",
      "status": "selected"
    },
    "order": {
      "inventory_demand_revision": 0,
      "line_items": [
        {
          "base_subtotal_money": {
            "amount": 1,
            "currency": "USD"
          },
          "discount_money": {
            "amount": 1,
            "currency": "USD"
          },
          "modifier_total_money": {
            "amount": 1,
            "currency": "USD"
          },
          "name": "Standard delivery",
          "order_line_item_id": "example",
          "quantity": 1,
          "refunded_money": {
            "amount": 1,
            "currency": "USD"
          },
          "refunded_quantity": 1,
          "subtotal_money": {
            "amount": 1,
            "currency": "USD"
          },
          "tax_money": {
            "amount": 1,
            "currency": "USD"
          },
          "total_money": {
            "amount": 1,
            "currency": "USD"
          },
          "unit_price_money": {
            "amount": 1,
            "currency": "USD"
          }
        }
      ],
      "order_id": "ord_01K1P6G4M7H2N8Q9R3S5T6V7WX",
      "payment_status": "unpaid",
      "pricing_amounts": {
        "charge_money": {
          "amount": 1,
          "currency": "USD"
        },
        "discount_money": {
          "amount": 1,
          "currency": "USD"
        },
        "requested_tip_money": {
          "amount": 1,
          "currency": "USD"
        },
        "subtotal_money": {
          "amount": 1,
          "currency": "USD"
        },
        "tax_money": {
          "amount": 1,
          "currency": "USD"
        },
        "total_money": {
          "amount": 1,
          "currency": "USD"
        }
      },
      "refund_status": "none",
      "settlement_amounts": {
        "balance_money": {
          "amount": 1,
          "currency": "USD"
        },
        "credit_money": {
          "amount": 1,
          "currency": "USD"
        },
        "net_collected_money": {
          "amount": 1,
          "currency": "USD"
        },
        "outstanding_money": {
          "amount": 1,
          "currency": "USD"
        },
        "paid_money": {
          "amount": 1,
          "currency": "USD"
        },
        "refunded_money": {
          "amount": 1,
          "currency": "USD"
        },
        "settled_tip_money": {
          "amount": 1,
          "currency": "USD"
        }
      },
      "status": "open",
      "tax": {
        "enabled": true,
        "mode": "automatic",
        "status": "not_required",
        "taxability_reason": "standard_rated"
      }
    }
  },
  "request_id": "req_01K1P6G4M7H2N8Q9R3S5T6V7WX"
}

Get historical delivery selection#

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

Returns one checkout selection with immutable economics, lifecycle events, and retention-aware private data.

Path parameters
checkout_session_idstringrequired

Flint checkout session ID.

delivery_selection_idstringrequired

Flint delivery selection ID.

Response · 200
dataobjectrequired
metaobject
request_idstring

Error codes

AUTH_REQUIREDDELIVERY_ELIGIBILITY_CONTEXT_CHANGEDDELIVERY_EXPECTED_SELECTION_REQUIREDDELIVERY_EXTERNAL_REFERENCE_REUSEDDELIVERY_OPTION_ALREADY_SELECTEDDELIVERY_OPTION_EXPIREDDELIVERY_OPTION_NOT_IN_CHOICE_GROUPDELIVERY_QUOTE_EXPIREDDELIVERY_QUOTE_INPUT_CHANGEDDELIVERY_QUOTE_REVOKEDDELIVERY_SELECTION_CHANGEDDELIVERY_SELECTION_EXPIREDDELIVERY_SELECTION_INCOMPLETEDELIVERY_SELECTION_REPLACEMENT_LIMITDELIVERY_SELECTION_UNAVAILABLEDELIVERY_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-selections/dsel_01K1P6G4M7H2N8Q9R3S5T6V7WX \
  -H "Authorization: Bearer YOUR_API_KEY"
JSON
{
  "data": {
    "amount_money": {
      "amount": 1,
      "currency": "USD"
    },
    "calculation_expires_at": "2026-08-02T16:00:00Z",
    "checkout_session_id": "cs_01K1P6G4M7H2N8Q9R3S5T6V7WX",
    "choices": [
      {
        "amount_money": {
          "amount": 1,
          "currency": "USD"
        },
        "delivery_choice_group_id": "dcgrp_01K1P6G4M7H2N8Q9R3S5T6V7WX",
        "delivery_method_id": "dmet_01K1P6G4M7H2N8Q9R3S5T6V7WX",
        "delivery_option_id": "dopt_01K1P6G4M7H2N8Q9R3S5T6V7WX",
        "delivery_plan": {
          "type": "single_delivery"
        },
        "discount_money": {
          "amount": 1,
          "currency": "USD"
        },
        "name": "Standard delivery",
        "stable_key": "example",
        "tax_money": {
          "amount": 1,
          "currency": "USD"
        },
        "total_money": {
          "amount": 1,
          "currency": "USD"
        },
        "type": "shipment"
      }
    ],
    "created_at": "2026-08-02T16:00:00Z",
    "delivery_quote_id": "dqt_01K1P6G4M7H2N8Q9R3S5T6V7WX",
    "delivery_quote_revision": 0,
    "delivery_selection_id": "dsel_01K1P6G4M7H2N8Q9R3S5T6V7WX",
    "eligibility_context_revision": 0,
    "expires_at": "2026-08-02T16:00:00Z",
    "lifecycle_updated_at": "2026-08-02T16:00:00Z",
    "limiting_deadline_reason": "selection_guarantee_expiry",
    "order_id": "ord_01K1P6G4M7H2N8Q9R3S5T6V7WX",
    "status": "selected"
  },
  "request_id": "req_01K1P6G4M7H2N8Q9R3S5T6V7WX"
}

Get current delivery selection#

GET/v1/checkout-sessions/{checkout_session_id}/delivery-selections/currentRequires scope: commerce.delivery.read or commerce.delivery.write

Returns the provisional selection or the order-level committed selection effective for this checkout.

Path parameters
checkout_session_idstringrequired

Flint checkout session ID.

Response · 200
dataone ofrequired
metaobject
request_idstring

Error codes

AUTH_REQUIREDDELIVERY_ELIGIBILITY_CONTEXT_CHANGEDDELIVERY_EXPECTED_SELECTION_REQUIREDDELIVERY_EXTERNAL_REFERENCE_REUSEDDELIVERY_OPTION_ALREADY_SELECTEDDELIVERY_OPTION_EXPIREDDELIVERY_OPTION_NOT_IN_CHOICE_GROUPDELIVERY_QUOTE_EXPIREDDELIVERY_QUOTE_INPUT_CHANGEDDELIVERY_QUOTE_REVOKEDDELIVERY_SELECTION_CHANGEDDELIVERY_SELECTION_EXPIREDDELIVERY_SELECTION_INCOMPLETEDELIVERY_SELECTION_REPLACEMENT_LIMITDELIVERY_SELECTION_UNAVAILABLEDELIVERY_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-selections/current \
  -H "Authorization: Bearer YOUR_API_KEY"
JSON
{
  "data": {
    "audience": "merchant",
    "mutable": true,
    "source": "none"
  },
  "request_id": "req_01K1P6G4M7H2N8Q9R3S5T6V7WX"
}

Delete current delivery selection#

DELETE/v1/checkout-sessions/{checkout_session_id}/delivery-selections/currentIdempotentRequires scope: commerce.delivery.write

Atomically clears a provisional selection, releases inventory, removes its charges, and recalculates order economics.

Path parameters
checkout_session_idstringrequired

Flint checkout session ID.

Query parameters
expected_delivery_selection_idstringrequired

Current delivery selection ID used as a compare-and-swap fence.

Response · 200
dataone ofrequired
metaobject
request_idstring

Error codes

AUTH_REQUIREDDELIVERY_ELIGIBILITY_CONTEXT_CHANGEDDELIVERY_EXPECTED_SELECTION_REQUIREDDELIVERY_EXTERNAL_REFERENCE_REUSEDDELIVERY_OPTION_ALREADY_SELECTEDDELIVERY_OPTION_EXPIREDDELIVERY_OPTION_NOT_IN_CHOICE_GROUPDELIVERY_QUOTE_EXPIREDDELIVERY_QUOTE_INPUT_CHANGEDDELIVERY_QUOTE_REVOKEDDELIVERY_SELECTION_CHANGEDDELIVERY_SELECTION_EXPIREDDELIVERY_SELECTION_INCOMPLETEDELIVERY_SELECTION_REPLACEMENT_LIMITDELIVERY_SELECTION_UNAVAILABLEDELIVERY_SERVICE_UNAVAILABLEDELIVERY_WINDOW_EXPIREDDELIVERY_WINDOW_INVALIDINSUFFICIENT_SCOPEINVALID_REQUESTRATE_LIMIT_EXCEEDEDRESOURCE_NOT_FOUNDSERVICE_UNAVAILABLE
Bash
curl -X DELETE https://api.withflintpay.com/v1/checkout-sessions/cs_123/delivery-selections/current \
  -H "Authorization: Bearer YOUR_API_KEY"
JSON
{
  "data": {
    "audience": "merchant",
    "checkout_session": {
      "checkout_session_id": "cs_01K1P6G4M7H2N8Q9R3S5T6V7WX",
      "delivery_method_ids": [
        "example"
      ],
      "delivery_selection_required": true,
      "problems": [
        {
          "blocks_completion": true,
          "code": "delivery_selection_stale",
          "severity": "error"
        }
      ],
      "recovery_mode": true,
      "status": "open",
      "surface": "hosted"
    },
    "delivery_selection": {
      "amount_money": {
        "amount": 1,
        "currency": "USD"
      },
      "calculation_expires_at": "2026-08-02T16:00:00Z",
      "checkout_session_id": "cs_01K1P6G4M7H2N8Q9R3S5T6V7WX",
      "choices": [
        {
          "amount_money": {
            "amount": 1,
            "currency": "USD"
          },
          "delivery_choice_group_id": "dcgrp_01K1P6G4M7H2N8Q9R3S5T6V7WX",
          "delivery_method_id": "dmet_01K1P6G4M7H2N8Q9R3S5T6V7WX",
          "delivery_option_id": "dopt_01K1P6G4M7H2N8Q9R3S5T6V7WX",
          "delivery_plan": {
            "type": "single_delivery"
          },
          "discount_money": {
            "amount": 1,
            "currency": "USD"
          },
          "name": "Standard delivery",
          "stable_key": "example",
          "tax_money": {
            "amount": 1,
            "currency": "USD"
          },
          "total_money": {
            "amount": 1,
            "currency": "USD"
          },
          "type": "shipment"
        }
      ],
      "created_at": "2026-08-02T16:00:00Z",
      "delivery_quote_id": "dqt_01K1P6G4M7H2N8Q9R3S5T6V7WX",
      "delivery_quote_revision": 0,
      "delivery_selection_id": "dsel_01K1P6G4M7H2N8Q9R3S5T6V7WX",
      "eligibility_context_revision": 0,
      "expires_at": "2026-08-02T16:00:00Z",
      "lifecycle_updated_at": "2026-08-02T16:00:00Z",
      "limiting_deadline_reason": "selection_guarantee_expiry",
      "order_id": "ord_01K1P6G4M7H2N8Q9R3S5T6V7WX",
      "status": "selected"
    },
    "order": {
      "inventory_demand_revision": 0,
      "line_items": [
        {
          "base_subtotal_money": {
            "amount": 1,
            "currency": "USD"
          },
          "discount_money": {
            "amount": 1,
            "currency": "USD"
          },
          "modifier_total_money": {
            "amount": 1,
            "currency": "USD"
          },
          "name": "Standard delivery",
          "order_line_item_id": "example",
          "quantity": 1,
          "refunded_money": {
            "amount": 1,
            "currency": "USD"
          },
          "refunded_quantity": 1,
          "subtotal_money": {
            "amount": 1,
            "currency": "USD"
          },
          "tax_money": {
            "amount": 1,
            "currency": "USD"
          },
          "total_money": {
            "amount": 1,
            "currency": "USD"
          },
          "unit_price_money": {
            "amount": 1,
            "currency": "USD"
          }
        }
      ],
      "order_id": "ord_01K1P6G4M7H2N8Q9R3S5T6V7WX",
      "payment_status": "unpaid",
      "pricing_amounts": {
        "charge_money": {
          "amount": 1,
          "currency": "USD"
        },
        "discount_money": {
          "amount": 1,
          "currency": "USD"
        },
        "requested_tip_money": {
          "amount": 1,
          "currency": "USD"
        },
        "subtotal_money": {
          "amount": 1,
          "currency": "USD"
        },
        "tax_money": {
          "amount": 1,
          "currency": "USD"
        },
        "total_money": {
          "amount": 1,
          "currency": "USD"
        }
      },
      "refund_status": "none",
      "settlement_amounts": {
        "balance_money": {
          "amount": 1,
          "currency": "USD"
        },
        "credit_money": {
          "amount": 1,
          "currency": "USD"
        },
        "net_collected_money": {
          "amount": 1,
          "currency": "USD"
        },
        "outstanding_money": {
          "amount": 1,
          "currency": "USD"
        },
        "paid_money": {
          "amount": 1,
          "currency": "USD"
        },
        "refunded_money": {
          "amount": 1,
          "currency": "USD"
        },
        "settled_tip_money": {
          "amount": 1,
          "currency": "USD"
        }
      },
      "status": "open",
      "tax": {
        "enabled": true,
        "mode": "automatic",
        "status": "not_required",
        "taxability_reason": "standard_rated"
      }
    }
  },
  "request_id": "req_01K1P6G4M7H2N8Q9R3S5T6V7WX"
}

Get current order delivery selection#

GET/v1/orders/{order_id}/delivery-selections/currentRequires scope: commerce.orders.read or commerce.orders.write

Returns the delivery selection committed to an order.

Path parameters
order_idstringrequired

Flint order ID.

Response · 200
dataobjectrequired
metaobject
request_idstring

Error codes

AUTH_REQUIREDDELIVERY_ELIGIBILITY_CONTEXT_CHANGEDDELIVERY_EXPECTED_SELECTION_REQUIREDDELIVERY_EXTERNAL_REFERENCE_REUSEDDELIVERY_OPTION_ALREADY_SELECTEDDELIVERY_OPTION_EXPIREDDELIVERY_OPTION_NOT_IN_CHOICE_GROUPDELIVERY_QUOTE_EXPIREDDELIVERY_QUOTE_INPUT_CHANGEDDELIVERY_QUOTE_REVOKEDDELIVERY_SELECTION_CHANGEDDELIVERY_SELECTION_EXPIREDDELIVERY_SELECTION_INCOMPLETEDELIVERY_SELECTION_REPLACEMENT_LIMITDELIVERY_SELECTION_UNAVAILABLEDELIVERY_SERVICE_UNAVAILABLEDELIVERY_WINDOW_EXPIREDDELIVERY_WINDOW_INVALIDINSUFFICIENT_SCOPEINVALID_REQUESTRATE_LIMIT_EXCEEDEDRESOURCE_NOT_FOUNDSERVICE_UNAVAILABLE
Bash
curl https://api.withflintpay.com/v1/orders/ord_123/delivery-selections/current \
  -H "Authorization: Bearer YOUR_API_KEY"
JSON
{
  "data": {
    "amount_money": {
      "amount": 1,
      "currency": "USD"
    },
    "calculation_expires_at": "2026-08-02T16:00:00Z",
    "checkout_session_id": "cs_01K1P6G4M7H2N8Q9R3S5T6V7WX",
    "choices": [
      {
        "amount_money": {
          "amount": 1,
          "currency": "USD"
        },
        "delivery_choice_group_id": "dcgrp_01K1P6G4M7H2N8Q9R3S5T6V7WX",
        "delivery_method_id": "dmet_01K1P6G4M7H2N8Q9R3S5T6V7WX",
        "delivery_option_id": "dopt_01K1P6G4M7H2N8Q9R3S5T6V7WX",
        "delivery_plan": {
          "type": "single_delivery"
        },
        "discount_money": {
          "amount": 1,
          "currency": "USD"
        },
        "name": "Standard delivery",
        "stable_key": "example",
        "tax_money": {
          "amount": 1,
          "currency": "USD"
        },
        "total_money": {
          "amount": 1,
          "currency": "USD"
        },
        "type": "shipment"
      }
    ],
    "created_at": "2026-08-02T16:00:00Z",
    "delivery_quote_id": "dqt_01K1P6G4M7H2N8Q9R3S5T6V7WX",
    "delivery_quote_revision": 0,
    "delivery_selection_id": "dsel_01K1P6G4M7H2N8Q9R3S5T6V7WX",
    "eligibility_context_revision": 0,
    "expires_at": "2026-08-02T16:00:00Z",
    "lifecycle_updated_at": "2026-08-02T16:00:00Z",
    "limiting_deadline_reason": "selection_guarantee_expiry",
    "order_id": "ord_01K1P6G4M7H2N8Q9R3S5T6V7WX",
    "status": "selected"
  },
  "request_id": "req_01K1P6G4M7H2N8Q9R3S5T6V7WX"
}
Rate this doc