Session
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
- Merchant tax-rate determination
- Delivery availability checks
How session transfer works
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
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 stores via Get Active Domains and Get Active Carts.
- Shipping calculations — stage a postal code via Set Postal Code for accurate shipping quotes before the buyer enters a full address.
- Cart recovery — import an in-flight merchant session via Session Transfer to preserve cart contents across platforms.