Set Postal Code

POST https://api.firmly.work/api/v2/carts/postal-code

Stores a postal code on the global session for the authenticated device. The value is reused across every merchant cart on this session; it is not scoped to a specific domain. This endpoint takes no {domain} parameter.

The postal code is consumed by per-merchant endpoints that gate behavior on it (e.g. Add Line Item returns 412 PostalCodeRequired for merchants that require a postal code before adding items).

​​ Authentication

• x-firmly-authorization (string, required) — Device access token from Browser Session
• Server-to-server (S2S) auth is not accepted — this is a device-scoped session route. It requires a device JWT from Browser Session; the S2S secret is rejected. See Server-to-Server Authentication.

​​ Request Body

• postal_code (string, required) — The postal code to store. No format validation is enforced server-side — pass the value the merchant expects (US ZIP, Canadian / UK postcode, etc.).

​​ Response

• postal_code (string) — The value that was stored.

​​ Examples

curl -X POST https://api.firmly.work/api/v2/carts/postal-code \
  -H "x-firmly-authorization: YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "postal_code": "90210"
  }'

const response = await fetch('https://api.firmly.work/api/v2/carts/postal-code', {
  method: 'POST',
  headers: {
    'x-firmly-authorization': 'YOUR_TOKEN',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({ postal_code: '90210' })
});

const { postal_code } = await response.json();

import requests

response = requests.post(
    'https://api.firmly.work/api/v2/carts/postal-code',
    headers={
        'x-firmly-authorization': 'YOUR_TOKEN',
        'Content-Type': 'application/json'
    },
    json={'postal_code': '90210'}
)

data = response.json()

​​ Response Example

{
  "postal_code": "90210"
}

​​ Error Responses

Errors return a JSON body with code, error, and description. Program against the error value — descriptions are human-readable and may change.

{ "code": 400, "error": "MissingAuthHeader", "description": "x-firmly-authorization header is missing or invalid." }

{ "code": 400, "error": "InvalidToken", "description": "Jwt token is invalid." }

{ "code": 401, "error": "InvalidJWTToken", "description": "Jwt token is invalid." }

{ "code": 404, "error": "PartnerNotFound", "description": "Partner not found." }

{ "code": 400, "error": "InvalidInputBody", "description": "The body is not processable" }