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

# Get Postal Code

> Retrieves the postal code preference for the current session

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

<Note>
  This is a global session preference that applies across all merchant domains.
</Note>

## Authentication

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

## Request

No request body or query parameters required.

## Response

<ResponseField name="postal_code" type="string" required>
  The postal code preference for the user session
</ResponseField>

<Note>
  Based on the implementation, this endpoint always returns a postal\_code field, though the value may be an empty string if not set.
</Note>

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

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET 'https://api.firmly.work/api/v2/carts/postal-code' \
    -H 'x-firmly-authorization: <your-auth-token>' \
    -H 'Content-Type: application/json'
  ```

  ```javascript JavaScript theme={null}
  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');
  }
  ```

  ```python Python theme={null}
  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')
  ```
</CodeGroup>

## Response Examples

### Postal Code Set

```json theme={null}
{
  "postal_code": "90210"
}
```

### No Postal Code Set

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

## Related Endpoints

* [Set Postal Code](/api-reference/session/set-postal-code) - Update the postal code preference