Skip to main content
POST
/
carts
/
postal-code
Set Postal Code
curl --request POST \
  --url https://api.firmly.work/carts/postal-code \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "postal_code": "<string>"
}
'
{
  "postal_code": "<string>"
}

Documentation Index

Fetch the complete documentation index at: https://developers.firmly.ai/llms.txt

Use this file to discover all available pages before exploring further.

​
Overview

This endpoint updates the postal code preference for the current session. The postal code is used to determine shipping availability and calculate accurate shipping rates for items across all merchant carts.
Setting a postal code updates the preference globally across all merchant domains in the current session.

​
Authentication

Requires Device Authentication.

​
Request

​
postal_code
string
required
The postal code to store as the preferenceExamples:
  • US: “90210”, “10001”
  • Canada: “K1A 0B1”
  • UK: “SW1A 1AA”

​
Response

​
postal_code
string
The postal code that was successfully stored

​
Session Behavior

​
Update Effects

  • Immediately available across all domains
  • Triggers shipping recalculation on active carts
  • Persists for the session duration
  • Overwrites any previous postal code

​
Validation

  • Basic format validation may be applied
  • Invalid formats return validation errors
  • Merchant-specific postal code rules may apply

​
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

​
ValidationError

Status Code: 400
Description: Request body validation failed (missing or invalid postal code)

​
Examples

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

​
Response Example

{
  "postal_code": "90210"
}

​
Use Cases

​
Early Shipping Estimation

  • Set postal code before adding items to cart
  • Show shipping costs during browsing
  • Filter products by shipping availability

​
Multi-Domain Shopping

  • Single postal code entry for all stores
  • Consistent shipping calculations
  • Simplified checkout experience

​
Location-Based Features

  • Display local inventory
  • Show region-specific promotions
  • Calculate accurate delivery times

​
Best Practices

​
When to Set

  1. During initial site visit (if user provides)
  2. When user enters shipping calculator
  3. At start of checkout process
  4. When shipping location changes

​
Validation Tips

  • Validate format before submission
  • Handle international postal codes
  • Provide clear error messages
  • Consider postal code lookup services