Delivery checkouts

Create a delivery checkout

Requires checkouts:write. Create a checkout from cart and recipient data verified by your backend. A new reference returns 201; the same reference and initial input return the existing checkout with 200. This does not create an order or shipment.

post/api/external/v1/checkouts

Request

Base URL: http://localhost
URL: http://localhost/api/external/v1/checkouts
Auth: HTTP bearer

Headers

Idempotency-Keystring required

Request body

origin_location_idstring required

Active shipping location ID from GET /locations. Must start with one of <code>loc_</code> Must not be greater than 64 characters.

currencystring required

Currency with two decimal places. Must match the configured shipping rates; no currency conversion is performed. Three-letter uppercase ISO 4217 currency code.

localestring required

Merchant-selected display locale. Two-letter language code, optionally followed by a region or script, such as sv, sv-SE, or zh-Hant. Must not be greater than 16 characters.

external_referencestring required

Your checkout-attempt reference, unique within the store. Reusing it with different creation input returns a conflict. Must be at least 1 character. Must not be greater than 191 characters.

merchant_originstring uri required

Registered checkout-page origin, without a wildcard, path, or trailing slash. Cannot change after creation. Must not be greater than 255 characters.

Example request

{
  "origin_location_id": "loc_x7Kq9",
  "currency": "SEK",
  "locale": "sv",
  "cart": {
    "subtotal_minor": 69000,
    "discount_minor": 0,
    "weight_grams": 1200,
    "items": [
      {
        "reference": "line-1",
        "sku": "BAG-SAGE",
        "name": "Shoulder bag",
        "quantity": 1,
        "unit_price_minor": 69000,
        "requires_shipping": true,
        "weight_grams": 1200
      }
    ]
  },
  "recipient": {
    "first_name": "Alex",
    "last_name": "Andersson",
    "address1": "Drottninggatan 12",
    "postal_code": "11151",
    "city": "Stockholm",
    "country": "SE",
    "phone": "+46700000000",
    "email": "alex@example.com"
  },
  "external_reference": "cart-1042-attempt-1",
  "merchant_origin": "https://store.example"
}

Response

Existing checkout returned for identical creation input. Its current state may differ from the original response.

Example response

{
  "data": {
    "checkout_token": "chk_AaBbCcDdEeFfGgHhIiJjKkLlMmNnOoPp",
    "status": "open",
    "revision": 1,
    "currency": "SEK",
    "locale": "en",
    "ready": false,
    "expires_at": "2026-09-14T12:00:00+00:00",
    "quote": {
      "id": "quote_example",
      "expires_at": "2026-09-13T12:15:00+00:00",
      "options": [
        {
          "id": "option_example",
          "name": "Configured pickup",
          "description": null,
          "amount_minor": 4900,
          "currency": "SEK",
          "delivery_type": "pickup_point",
          "preview": false,
          "carrier": {
            "name": "Configured carrier",
            "logo_url": null
          },
          "estimated_delivery": null,
          "badges": [
            "recommended"
          ],
          "pickup_locations": [],
          "service_points": [
            {
              "id": "sp_example",
              "name": "Selected second point",
              "address": {
                "address1": "Example Street 2",
                "address2": null,
                "postal_code": "11151",
                "city": "Stockholm",
                "country": "SE"
              },
              "latitude": null,
              "longitude": null,
              "distance_meters": null,
              "opening_hours": null
            }
          ]
        }
      ]
    },
    "selection": null,
    "lock": null,
    "order": null
  }
}

Changes

No recorded changes to this operation across all 1 revision of this API.