FlintflintDocs

Add shipping to a checkout

This guide adds one flat-rate shipping choice to an existing order and checkout. You need an active Location with a published address, an order whose physical line items use the General delivery profile, and an API key with delivery and checkout write scopes.

1. Create the shipping method#

Create the method as active when its Location is already ready. Omit estimate to use {"type":"none"}.

HTTP
POST /v1/delivery-methods
Authorization: Bearer flint_test_...
Idempotency-Key: create-standard-shipping
Content-Type: application/json

{
  "name": "Standard shipping",
  "type": "shipment",
  "status": "active",
  "configuration": {
    "origin": {
      "type": "fixed_location",
      "location_id": "loc_01K1P6G4M7H2N8Q9R3S5T6V7WX"
    },
    "pricing": {
      "type": "fixed",
      "fixed": {
        "currency_options": {
          "USD": {"amount": 900}
        }
      }
    }
  }
}
JSON
{
  "data": {
    "delivery_method_id": "dmet_01K1P6G4M7H2N8Q9R3S5T6V7WX",
    "type": "shipment",
    "name": "Standard shipping",
    "status": "active",
    "version": 1,
    "current_delivery_method_revision_id": "dmetr_01K1P6G4M7H2N8Q9R3S5T6V7WX",
    "configuration": {
      "origin": {"type": "fixed_location", "location_id": "loc_01K1P6G4M7H2N8Q9R3S5T6V7WX"},
      "pricing": {"type": "fixed", "fixed": {"currency_options": {"USD": {"amount": 900, "currency": "USD"}}}},
      "estimate": {"type": "none"},
      "tax_category": "shipping"
    }
  },
  "request_id": "req_01K1P6G4M7H2N8Q9R3S5T6V7WX"
}

2. Assign the method to the checkout#

Include the method when creating a checkout for the order. You can instead save it in settings.checkout.fulfillment.fulfillment_method_ids and omit delivery_method_ids on future checkout requests.

HTTP
POST /v1/checkout-sessions
Authorization: Bearer flint_test_...
Idempotency-Key: checkout-order-42
Content-Type: application/json

{
  "surface": "hosted",
  "order_id": "ord_01K1P6G4M7H2N8Q9R3S5T6V7WX",
  "delivery_method_ids": ["dmet_01K1P6G4M7H2N8Q9R3S5T6V7WX"]
}

The response includes the checkout ID, buyer secret, URL, and the immutable method assignment:

JSON
{
  "data": {
    "checkout_session_id": "cs_01K1P6G4M7H2N8Q9R3S5T6V7WX",
    "status": "open",
    "surface": "hosted",
    "order_id": "ord_01K1P6G4M7H2N8Q9R3S5T6V7WX",
    "delivery_method_ids": ["dmet_01K1P6G4M7H2N8Q9R3S5T6V7WX"],
    "url": "https://checkout.withflintpay.com/cs_01K1P6G4M7H2N8Q9R3S5T6V7WX"
  },
  "request_id": "req_01K1P6G4M7H2N8Q9R3S5T6V7WX"
}

3. Quote the buyer's address#

Buyer-side requests use the checkout ID and secret headers. Send null to assert that no selection exists yet.

HTTP
POST /v1/checkout-sessions/cs_01K1P6G4M7H2N8Q9R3S5T6V7WX/delivery-quotes
X-Checkout-Session-ID: cs_01K1P6G4M7H2N8Q9R3S5T6V7WX
X-Checkout-Session-Secret: CHECKOUT_SECRET
Idempotency-Key: quote-order-42-address-1
Content-Type: application/json

{
  "expected_delivery_selection_id": null,
  "destination_address": {
    "line1": "120 Kent Avenue",
    "city": "Brooklyn",
    "state": "NY",
    "postal_code": "11249",
    "country": "US"
  }
}
JSON
{
  "data": {
    "audience": "buyer",
    "delivery_quote_id": "dquote_01K1P6G4M7H2N8Q9R3S5T6V7WX",
    "status": "open",
    "evaluation_status": "complete",
    "choice_groups": [{
      "delivery_choice_group_id": "dcgrp_01K1P6G4M7H2N8Q9R3S5T6V7WX",
      "availability_status": "available",
      "options": [{
        "delivery_option_id": "dopt_01K1P6G4M7H2N8Q9R3S5T6V7WX",
        "type": "shipment",
        "name": "Standard shipping",
        "amount_money": {"amount": 900, "currency": "USD"}
      }]
    }],
    "buyer_reasons": [],
    "expires_at": "2026-08-03T16:00:00Z"
  },
  "request_id": "req_01K1P6G4M7H2N8Q9R3S5T6V7WX"
}

4. Select the option#

Use IDs from the quote. Do not reconstruct them from method data.

HTTP
POST /v1/checkout-sessions/cs_01K1P6G4M7H2N8Q9R3S5T6V7WX/delivery-selections
X-Checkout-Session-ID: cs_01K1P6G4M7H2N8Q9R3S5T6V7WX
X-Checkout-Session-Secret: CHECKOUT_SECRET
Idempotency-Key: select-order-42-shipping
Content-Type: application/json

{
  "delivery_quote_id": "dquote_01K1P6G4M7H2N8Q9R3S5T6V7WX",
  "expected_delivery_selection_id": null,
  "choices": [{
    "delivery_choice_group_id": "dcgrp_01K1P6G4M7H2N8Q9R3S5T6V7WX",
    "delivery_option_id": "dopt_01K1P6G4M7H2N8Q9R3S5T6V7WX"
  }]
}
JSON
{
  "data": {
    "audience": "buyer",
    "delivery_selection_id": "dsel_01K1P6G4M7H2N8Q9R3S5T6V7WX",
    "delivery_quote_id": "dquote_01K1P6G4M7H2N8Q9R3S5T6V7WX",
    "status": "selected",
    "choices": [{
      "delivery_choice_group_id": "dcgrp_01K1P6G4M7H2N8Q9R3S5T6V7WX",
      "delivery_option_id": "dopt_01K1P6G4M7H2N8Q9R3S5T6V7WX",
      "name": "Standard shipping",
      "total_money": {"amount": 900, "currency": "USD"}
    }]
  },
  "request_id": "req_01K1P6G4M7H2N8Q9R3S5T6V7WX"
}

Checkout can now collect payment. Flint commits the selection to the order atomically with successful payment processing.

Rate this doc