Set shipping address and get available rates

Supports Idempotency-Key header for safe retries.

Authorization

AuthorizationBearer <token>

Admin API key (server-to-server). Issue via the dashboard at Settings → API keys. Plain-text key is shown once — store in a secret manager. Format: Authorization: Bearer brainerce_xxxxxxxxx.

In: header

Header Parameters

Idempotency-Key?string

Client-supplied key (a UUID v4 is the recommended form, max 255 characters) that makes this mutation safe to retry.

Replay window: 24 hours. The first response for a key is cached; a retry inside the window with the same request body returns the original status and body without re-running the handler.
Reusing a key with a different body returns 409 Conflict with code: "IDEMPOTENCY_KEY_REUSED". The request fingerprint (method + path + body hash) is compared against the stored one; a mismatch is refused rather than served the old response.
Keys are scoped to the calling credential and store — two API keys may safely use the same key value.
Error responses are cached too, so a retry of a request that failed validation returns the same 400 immediately.
Sending this header on a GET returns 400 with code: "IDEMPOTENCY_KEY_NOT_SUPPORTED" — GETs are already idempotent.
Support is per-route and this parameter is the authoritative signal: a key sent to a route that does not declare it is accepted and silently ignored.

See /docs/api/idempotency.

Lengthlength <= 255

Request Body

firstNamestring

Recipient first name.

lastNamestring

Recipient last name.

company?string

Company / organization name for the address (used on invoices and customs forms).

line1string

Primary street address line (street number + street name).

line2?string

Secondary address line (apartment, suite, unit, building, floor, …).

citystring

City / locality.

region?string

State / province / region code or name. Required by some shipping carriers (e.g. USPS, UPS) for US/CA/AU addresses. Use the ISO-3166-2 subdivision code when possible (e.g. CA for California).

postalCodestring

Postal / ZIP code.

countrystring

ISO-3166-1 alpha-2 country code (uppercase, 2 letters).

phone?string

Recipient phone number in E.164 format. Used by carriers for delivery notifications.

emailstring

Shopper email address. Used for order confirmation, abandoned-checkout recovery, and matching/creating the customer record.

Formatemail

acceptsMarketing?boolean

Whether the shopper opted in to marketing communications at checkout. When true, the customer record is flagged for marketing email/SMS lists.

notes?string

Order-level note from the shopper ("Please leave at the door"). Rides along with the address step so single-page checkouts need no extra call. Copied onto the order at completion, then shown to the merchant in the dashboard and included in the confirmation email. Max 2000 chars. Send an empty string to clear a previously-set note.

Lengthlength <= 2000

analyticsClientId?string

GA4 gtag.js client_id (from gtag('get', measurementId, 'client_id', cb)), forwarded so the server-side purchase event can stitch to this browser session. Written onto the cart if not already set. Omit if unavailable, and never send a synthesized id.

Lengthlength <= 100

analyticsSessionId?string

GA4 gtag.js session_id (from gtag('get', measurementId, 'session_id', cb)), forwarded alongside analyticsClientId for the same stitch.

Lengthlength <= 100

trafficReferrerHost?string

Hostname of the external referrer that brought this shopper (last non-direct touch), auto-attached by the storefront SDK from its brainerce_attr capture. Raw host on purpose, because the platform classifies it (AI/organic/social) at read time. Omit if unknown.

Lengthlength <= 253

trafficUtmSource?string

utm_source of the last non-direct touch, auto-attached alongside trafficReferrerHost.

Lengthlength <= 150

trafficUtmMedium?string

utm_medium of the last non-direct touch.

Lengthlength <= 150

trafficUtmCampaign?string

utm_campaign of the last non-direct touch.

Lengthlength <= 150

trafficUtmTerm?string

utm_term of the last non-direct touch.

Lengthlength <= 150

trafficUtmContent?string

utm_content of the last non-direct touch.

Lengthlength <= 150

trafficGclid?string

Google Ads click id (gclid query param), auto-attached by the storefront SDK. Write-only: never returned from a public GET. Omit if the visit was not Ads-tagged.

Lengthlength <= 128

trafficGbraid?string

Google Ads app/cross-device click id (gbraid query param). Write-only: never returned from a public GET.

Lengthlength <= 128

trafficWbraid?string

Google Ads web-to-app click id (wbraid query param). Write-only: never returned from a public GET.

Lengthlength <= 128

trafficLandingPath?string

Path (never the query string) of the page that first captured this attribution snapshot.

Lengthlength <= 300

trafficCapturedAt?string

ISO 8601 timestamp of when the SDK captured this attribution snapshot client-side.

consentVersion?string

Which consent regime (e.g. Consent Mode v2) was active when the SDK captured this snapshot.

Lengthlength <= 40

analyticsConsentGranted?boolean

Consent Mode analytics_storage consent state captured client-side (client.updateConsent({analytics})), forwarded like the traffic-attribution fields above. Omit when no consent signal has been captured yet — that is NOT the same as false, and must not be inferred. Gates server-side GA4 sends only — see adsUserDataConsentGranted for the separate ad_user_data purpose.

adsUserDataConsentGranted?boolean

Consent Mode ad_user_data/ad_personalization consent state captured client-side (client.updateConsent({ads})), forwarded independently from analyticsConsentGranted above. Omit when no consent signal has been captured yet — that is NOT the same as false, and must not be inferred. This is the legal basis Google Ads Enhanced Conversions requires before hashed email/phone can be uploaded; never gate that upload on analyticsConsentGranted instead.

placeId?string

The placeId of the autocomplete suggestion the shopper picked (from checkout/address-autocomplete). Send it whenever the address came from the autocomplete: the server re-resolves it to exact rooftop coordinates and matches polygon ("draw on map") shipping zones against those, instead of re-geocoding the typed address lines. Without it, matching falls back to geocoding the text, which is materially less accurate (a same-named street in another city can outrank the right one). Note there is deliberately NO lat/lng field here: zone matching decides which shipping rate is offered and charged, so coordinates are never taken from the caller.

Lengthlength <= 512

placeSessionToken?string

The same sessionToken used for the checkout/address-autocomplete calls that produced placeId. Optional: the resolved place is cached server-side for 24h by placeId, so the normal flow (autocomplete → address-details → this call) hits that cache and needs no token. Pass it when you have it so that a cache miss still bills within the original autocomplete session instead of opening a new one.

Lengthlength <= 200

curl -X PATCH "https://api.brainerce.com/api/v1/checkout/string/shipping-address" \
  -H "Idempotency-Key: string" \
  -H "Content-Type: application/json" \
  -d '{
    "firstName": "Jane",
    "lastName": "Doe",
    "line1": "123 Main Street",
    "city": "San Francisco",
    "postalCode": "94105",
    "country": "US",
    "email": "[email protected]"
  }'

curl -X PATCH "https://api.brainerce.com/api/v1/checkout/string/shipping-address" \  -H "Idempotency-Key: string" \  -H "Content-Type: application/json" \  -d '{    "firstName": "Jane",    "lastName": "Doe",    "line1": "123 Main Street",    "city": "San Francisco",    "postalCode": "94105",    "country": "US",    "email": "[email protected]"  }'

{
  "checkout": {
    "id": "clx1a2b3c4d5e6f7g8h9",
    "status": "PENDING",
    "email": "[email protected]",
    "customerId": "clx1a2b3c4d5e6f7g8h9",
    "deliveryType": "shipping",
    "pickupLocation": {
      "id": "clx1a2b3c4d5e6f7g8h9",
      "name": "Main store",
      "rateName": "Store pickup",
      "address": {
        "line1": "Herzl 12",
        "line2": "Apt 4",
        "city": "Tel Aviv",
        "region": "Center District",
        "postalCode": "6578301",
        "country": "IL"
      },
      "phone": "+972501234567",
      "hours": "Sun-Thu 09:00-18:00",
      "instructions": "Bring your order number",
      "price": "0.00",
      "currency": "USD"
    },
    "shippingAddress": {
      "firstName": "Dana",
      "lastName": "Cohen",
      "company": "Acme Ltd",
      "line1": "Herzl 12",
      "line2": "Apt 4",
      "city": "Tel Aviv",
      "region": "Center District",
      "postalCode": "6578301",
      "country": "IL",
      "phone": "+972501234567"
    },
    "billingAddress": {
      "firstName": "Dana",
      "lastName": "Cohen",
      "company": "Acme Ltd",
      "line1": "Herzl 12",
      "line2": "Apt 4",
      "city": "Tel Aviv",
      "region": "Center District",
      "postalCode": "6578301",
      "country": "IL",
      "phone": "+972501234567"
    },
    "shippingRateId": "clx1a2b3c4d5e6f7g8h9",
    "shippingMethod": {
      "id": "clx1a2b3c4d5e6f7g8h9",
      "name": "Standard shipping",
      "description": "Delivery in 3 to 5 business days",
      "price": "15.00",
      "currency": "USD",
      "estimatedDays": 4,
      "source": "manual",
      "carrier": "ups",
      "service": "ground",
      "speedTier": "cheapest",
      "requiresPickupPoint": true
    },
    "currency": "USD",
    "subtotal": "59.80",
    "discountAmount": "5.00",
    "ruleDiscountAmount": "5.00",
    "appliedRules": [
      {
        "id": "clx1a2b3c4d5e6f7g8h9",
        "name": "Summer sale",
        "type": "ORDER_DISCOUNT",
        "discountAmount": "10.00"
      }
    ],
    "shippingAmount": "15.00",
    "taxAmount": "11.46",
    "taxBreakdown": {
      "subtotal": 50.9,
      "shippingNet": 12.71,
      "totalTax": 11.46,
      "total": 75.1,
      "breakdown": [
        {
          "name": "VAT",
          "rate": 18,
          "amount": 9.17
        }
      ],
      "currency": "USD"
    },
    "total": "81.26",
    "surchargeAmount": "0.00",
    "appliedSurcharges": [
      {
        "key": "handling",
        "name": "Handling fee",
        "value": "string",
        "amount": "5.00"
      }
    ],
    "customFieldValues": {},
    "couponCode": "WELCOME10",
    "tenders": [
      {
        "tenderId": "clx1a2b3c4d5e6f7g8h9",
        "amountApplied": "50.00"
      }
    ],
    "providerAmountDue": "81.26",
    "notes": "Leave at the door",
    "lineItems": [
      {
        "id": "clx1a2b3c4d5e6f7g8h9",
        "productId": "clx1a2b3c4d5e6f7g8h9",
        "variantId": "clx1a2b3c4d5e6f7g8h9",
        "quantity": 2,
        "unitPrice": "29.90",
        "discountAmount": "0.00",
        "product": {
          "id": "clx1a2b3c4d5e6f7g8h9",
          "name": "Classic T-Shirt",
          "sku": "TSHIRT-BLK-M",
          "images": [
            {}
          ],
          "isDownloadable": true
        },
        "variant": {
          "id": "clx1a2b3c4d5e6f7g8h9",
          "name": "Black / M",
          "sku": "TSHIRT-BLK-M"
        },
        "notes": "Gift wrap please",
        "metadata": {},
        "customizations": {}
      }
    ],
    "itemCount": 2,
    "availableShippingRates": [
      {
        "id": "clx1a2b3c4d5e6f7g8h9",
        "name": "Standard shipping",
        "description": "Delivery in 3 to 5 business days",
        "price": "15.00",
        "currency": "USD",
        "estimatedDays": 4,
        "source": "manual",
        "carrier": "ups",
        "service": "ground",
        "speedTier": "cheapest",
        "requiresPickupPoint": true
      }
    ],
    "expiresAt": "2019-08-24T14:15:22Z",
    "recoveryEmailSentAt": "2019-08-24T14:15:22Z",
    "createdAt": "2019-08-24T14:15:22Z",
    "updatedAt": "2019-08-24T14:15:22Z",
    "reservation": {
      "hasReservation": true,
      "expiresAt": "2019-08-24T14:15:22Z",
      "remainingSeconds": 540,
      "strategy": "ON_PAYMENT",
      "countdownMessage": "Your items are reserved for 9 minutes"
    },
    "presentment": {
      "currency": "USD",
      "subtotal": "59.80",
      "discountAmount": "0.00",
      "shippingAmount": "15.00",
      "taxAmount": "11.46",
      "surchargeAmount": "0.00",
      "total": "86.26",
      "fxChargingRate": "3.65",
      "fxBufferPercent": "2.00"
    },
    "pickupPoint": {
      "id": "pp_48213",
      "name": "Kiosk Herzl",
      "kind": "store",
      "address": {
        "street1": "Herzl 12",
        "city": "Tel Aviv",
        "zip": "6578301",
        "country": "IL"
      },
      "latitude": 32.0668,
      "longitude": 34.7647,
      "hours": "Sun-Thu 08:00-20:00",
      "note": "Next to the pharmacy",
      "distanceKm": 0.8
    },
    "totalAmount": "81.26"
  },
  "rates": [
    {
      "id": "clx1a2b3c4d5e6f7g8h9",
      "name": "Standard shipping",
      "description": "Delivery in 3 to 5 business days",
      "price": "15.00",
      "currency": "USD",
      "estimatedDays": 4,
      "source": "manual",
      "carrier": "ups",
      "service": "ground",
      "speedTier": "cheapest",
      "requiresPickupPoint": true
    }
  ]
}

{
  "statusCode": 400,
  "code": "VALIDATION_FAILED",
  "message": "name should not be empty, price must be a positive number",
  "timestamp": "2026-08-23T10:15:00.000Z",
  "path": "/api/v1/checkout/{checkoutId}/shipping-address"
}

{
  "statusCode": 401,
  "code": "UNAUTHORIZED",
  "message": "Invalid or expired credential",
  "timestamp": "2026-08-23T10:15:00.000Z",
  "path": "/api/v1/checkout/{checkoutId}/shipping-address"
}

{
  "statusCode": 403,
  "code": "INSUFFICIENT_SCOPE",
  "message": "API key does not have the required scope: products:write",
  "timestamp": "2026-08-23T10:15:00.000Z",
  "path": "/api/v1/checkout/{checkoutId}/shipping-address"
}

{
  "statusCode": 404,
  "code": "RESOURCE_NOT_FOUND",
  "message": "Resource not found",
  "timestamp": "2026-08-23T10:15:00.000Z",
  "path": "/api/v1/checkout/{checkoutId}/shipping-address"
}

{
  "statusCode": 429,
  "code": "RATE_LIMITED",
  "message": "Too many requests",
  "details": {
    "retryAfterSeconds": 12
  },
  "timestamp": "2026-08-23T10:15:00.000Z",
  "path": "/api/v1/store"
}

Set shipping address and get available rates

Authorization

Path Parameters

Header Parameters

Request Body

Example default

Example default

Example default

Example default

Example default