FlintflintDocs

Delivery previews

Delivery previews evaluate a proposed cart without creating a checkout session or granting selection authority. Use them in merchant tools that need to test delivery configuration before publishing it.

A preview returns the same choice-group and merchant-diagnostic vocabulary used by checkout quotes. It does not reserve inventory, invoke caller-supplied pricing, or create a selectable quote. Callback pricing participates only when the callback has preview_enabled: true.

Treat evaluated_at and expires_at as the evidence window for the result. Re-run the preview after changing cart lines, destination data, buyer location, routing input, or delivery configuration.

Endpoints

Create delivery preview#

POST/v1/delivery-previewsRequires scope: commerce.delivery.write

Computes exact display-only fulfillment outcomes without persisting a resource, holding inventory, or granting selection authority.

Request body
buyer_locationone of
currencystringrequired

ISO 4217 currency code.

delivery_method_idsarray of stringrequired
destination_addressobject
inventory_routing_sourceobject
line_itemsarray of one ofrequired
pickup_location_idstring
pricing_contextmap of string
Response · 200
dataobjectrequired
metaobject
request_idstring

Error codes

AUTH_REQUIREDDELIVERY_DESTINATION_INVALIDDELIVERY_PREVIEW_INVALIDDELIVERY_PREVIEW_METHOD_TYPES_INCOMPATIBLEDELIVERY_PREVIEW_REQUIRES_CHECKOUTDELIVERY_PREVIEW_UNAVAILABLEDELIVERY_SERVICE_UNAVAILABLEINSUFFICIENT_SCOPEINVALID_REQUESTRATE_LIMIT_EXCEEDEDRESOURCE_NOT_FOUNDSERVICE_UNAVAILABLE
Bash
curl -X POST https://api.withflintpay.com/v1/delivery-previews \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "currency": "USD",
    "delivery_method_ids": [
      "example"
    ],
    "line_items": [
      {
        "variant_id": "example"
      }
    ]
  }'
JSON
{
  "data": {
    "choice_groups": [
      {
        "availability_status": "ready",
        "candidate_outcomes": {},
        "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"
          }
        ]
      }
    ],
    "currency": "USD",
    "delivery_method_ids": [
      "example"
    ],
    "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"
      }
    ],
    "line_items": [
      {
        "variant_id": "example"
      }
    ],
    "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"
      }
    ],
    "selection_authority": true
  },
  "request_id": "req_01K1P6G4M7H2N8Q9R3S5T6V7WX"
}
Rate this doc