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

> Session management endpoints for multi-domain cart tracking and postal code preferences

The Session API provides endpoints for managing shopping sessions across multiple merchant domains and storing postal code preferences for shipping calculations.

## Available Endpoints

### Active Cart Management

<CardGroup cols={2}>
  <Card title="Get Active Domains" href="/api-reference/session/get-active-domains" icon="list">
    Retrieve a list of domains where the user has active carts
  </Card>

  <Card title="Get Active Carts" href="/api-reference/session/get-active-carts" icon="shopping-cart">
    Retrieve all active shopping carts across multiple domains
  </Card>
</CardGroup>

### Postal Code Management

<CardGroup cols={2}>
  <Card title="Get Postal Code" href="/api-reference/session/get-postal-code" icon="map">
    Retrieve the stored postal code preference
  </Card>

  <Card title="Set Postal Code" href="/api-reference/session/set-postal-code" icon="arrow-right">
    Update the postal code preference for shipping calculations
  </Card>
</CardGroup>

### Session Transfer

<Card title="Session Transfer" href="/api-reference/session/session-transfer" icon="arrow-right">
  Transfer an external merchant session to Firmly's cart system
</Card>

## Core Concepts

### Multi-Domain Cart Tracking

The session endpoints enable tracking of shopping carts across multiple merchant domains:

* **Active Domains**: Quickly check which merchants have active carts
* **Active Carts**: Retrieve full cart data for all active sessions
* **Exclude Filtering**: Filter out specific domains when retrieving active carts

### Postal Code Preference

A single postal code preference is stored per device session and used for:

* Shipping cost calculations
* Tax rate determination
* Delivery availability checks

<Note>
  The postal code is a global preference that applies to all merchant carts in the session. It can be null if not set.
</Note>

### Session Transfer

The session transfer endpoint enables migrating existing merchant sessions to Firmly's cart system. This is useful for:

* Transitioning from native checkout to Firmly
* Preserving cart contents during platform migration
* Maintaining shopping continuity

<Warning>
  Session transfer requires special integration setup with each merchant. Contact Firmly support for implementation details.
</Warning>

## Authentication

All session endpoints require device authentication using the `x-firmly-authorization` header. See the [Authentication Guide](/api-reference/authentication/browser-session) for details on obtaining access tokens.

## Use Cases

### Multi-Merchant Shopping

Track and manage carts across multiple stores:

```javascript theme={null}
// Get all active domains
const { domains } = await fetch('/api/v2/carts/active-domains', {
  headers: { 'x-firmly-authorization': token }
}).then(r => r.json());

// Get full cart data for active sessions
const { carts } = await fetch('/api/v2/carts/active', {
  headers: { 'x-firmly-authorization': token }
}).then(r => r.json());
```

### Shipping Calculations

Set postal code for accurate shipping quotes:

```javascript theme={null}
// Set postal code preference
await fetch('/api/v2/carts/postal-code', {
  method: 'POST',
  headers: { 
    'x-firmly-authorization': token,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({ postal_code: '90210' })
});
```

### Cart Recovery

Transfer external sessions to Firmly:

```javascript theme={null}
// Transfer merchant session
const cart = await fetch('/api/v2/domains/staging.luma.gift/session/transfer', {
  method: 'POST',
  headers: { 
    'x-firmly-authorization': token,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    handle: 'merchant-session-id',
    cookies: ['session_cookie_value']
  })
}).then(r => r.json());
```