Skip to main content

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.

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());