> ## 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.

# Set Postal Code

> Updates the postal code preference for the current session

## 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.

<Note>
  Setting a postal code updates the preference globally across all merchant domains in the current session.
</Note>

## Authentication

Requires [Device Authentication](/api-reference/authentication/browser-session).

## Request

<ParamField body="postal_code" type="string" required>
  The postal code to store as the preference

  Examples:

  * US: "90210", "10001"
  * Canada: "K1A 0B1"
  * UK: "SW1A 1AA"
</ParamField>

## Response

<ResponseField name="postal_code" type="string">
  The postal code that was successfully stored
</ResponseField>

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

<CodeGroup>
  ```bash cURL theme={null}
  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"
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://api.firmly.work/api/v2/carts/postal-code', {
    method: 'POST',
    headers: {
      'x-firmly-authorization': '<your-auth-token>',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      postal_code: '90210'
    })
  });

  const { postal_code } = await response.json();
  console.log('Postal code set:', postal_code);
  ```

  ```python Python theme={null}
  import requests

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

  data = response.json()
  print(f"Postal code set: {data['postal_code']}")
  ```
</CodeGroup>

## Response Example

```json theme={null}
{
  "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

## Related Endpoints

* [Get Postal Code](/api-reference/session/get-postal-code) - Retrieve the current postal code preference