Get Postal Code

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

​​ Overview

This endpoint retrieves the postal code preference for the current session. The postal code is used to determine shipping availability and calculate accurate shipping rates for items in the cart.

​​ 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

No request body or query parameters required.

​​ Response

• postal_code (string, required) — The postal code preference for the user session

​​ Session Behavior

The postal code is a single global preference stored per device session:

• Used for shipping availability checks and to let the merchant’s platform calculate accurate tax
• Applies across all merchant domains and is automatically applied to new cart sessions
• Persists across page refreshes for the lifetime of the session

​​ Examples

curl -X GET 'https://api.firmly.work/api/v2/carts/postal-code' \
  -H 'x-firmly-authorization: <your-auth-token>' \
  -H 'Content-Type: application/json'

const response = await fetch('https://api.firmly.work/api/v2/carts/postal-code', {
  headers: {
    'x-firmly-authorization': '<your-auth-token>',
    'Content-Type': 'application/json'
  }
});

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

if (postal_code) {
  console.log('User postal code:', postal_code);
} else {
  console.log('No postal code set');
}

import requests

response = requests.get(
    'https://api.firmly.work/api/v2/carts/postal-code',
    headers={
        'x-firmly-authorization': '<your-auth-token>',
        'Content-Type': 'application/json'
    }
)

data = response.json()
postal_code = data.get('postal_code')

if postal_code:
    print(f'User postal code: {postal_code}')
else:
    print('No postal code set')

​​ Response Examples

​​ Postal Code Set

{
  "postal_code": "90210"
}

​​ No Postal Code Set

{
  "postal_code": ""
}

​​ Use Cases

• Shipping availability — check whether items can ship to the buyer’s location and filter shipping methods by postal code
• Tax calculation — the postal code lets the merchant’s platform calculate tax for the destination (applicable rates, order totals, and any multi-jurisdictional rules all come from the merchant; Firmly relays the result)
• User experience — pre-fill shipping forms and remember the buyer’s preference across the session

​​ Related Endpoints

• Set Postal Code — Update the postal code preference

​​ 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." }