Skip to main content
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

Get Active Domains

Retrieve a list of domains where the user has active carts

Get Active Carts

Retrieve all active shopping carts across multiple domains

​
Postal Code Management

Get Postal Code

Retrieve the stored postal code preference

Set Postal Code

Update the postal code preference for shipping calculations

​
Session Transfer

Session Transfer

Transfer an external merchant session to Firmly’s cart system

​
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
The postal code is a global preference that applies to all merchant carts in the session. It can be null if not set.

​
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
Session transfer requires special integration setup with each merchant. Contact Firmly support for implementation details.

​
Authentication

All session endpoints require device authentication using the x-firmly-authorization header. See the Authentication Guide for details on obtaining access tokens.

​
Use Cases

​
Multi-Merchant Shopping

Track and manage carts across multiple stores: 
// 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: 
// 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: 
// 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());