Skip to main content
GET
https://api.firmly.work
/
carts
/
postal-code
Get Postal Code
curl --request GET \
  --url https://api.firmly.work/carts/postal-code \
  --header 'Authorization: Bearer <token>'
{
  "postal_code": "<string>"
}

​
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.
This is a global session preference that applies across all merchant domains.

​
Authentication

Requires Device Authentication.

​
Request

No request body or query parameters required.

​
Response

​
postal_code
string
required
The postal code preference for the user session
Based on the implementation, this endpoint always returns a postal_code field, though the value may be an empty string if not set.

​
Session Behavior

​
Postal Code Usage

  • Used for shipping availability checks
  • Enables accurate tax calculations
  • Persists across merchant domains
  • Survives page refreshes and session continuity

​
Global Preference

  • Single postal code for all active carts
  • Automatically applied to new cart sessions
  • Updates propagate to all domains

​
Errors

​
MissingAuthHeader

Status Code: 401
Description: x-firmly-authorization header is missing or invalid

​
InvalidJWTToken

Status Code: 401
Description: The JWT token is invalid

​
InvalidToken

Status Code: 401
Description: JWT token is invalid

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

​
Response Examples

​
Postal Code Set

{
  "postal_code": "90210"
}

​
No Postal Code Set

{
  "postal_code": ""
}

​
Use Cases

​
Shipping Availability

  • Check if items can be shipped to user’s location
  • Filter shipping methods by postal code
  • Display region-specific shipping options

​
Tax Calculation

  • Determine applicable tax rates
  • Calculate accurate order totals
  • Support multi-jurisdictional tax rules

​
User Experience

  • Pre-fill shipping forms
  • Remember user preferences
  • Streamline checkout process