Session
Session Transfer
Transfers an external merchant session to Firmly’s cart system
POST
Session Transfer
Overview
This endpoint transfers an external shopping session (e.g., from a merchant’s native cart) to Firmly’s session management system. It enables seamless cart migration and session continuity across platforms.Authentication
Requires Device Authentication.Request
string
required
The merchant’s domain (e.g. staging.luma.gift)
string | object
required
Session identifier or structured handle objectCan be:
- Simple string handle
- JSON object with additional metadata
When using a JSON object handle, it should have the following structure:
array
Optional array of cookie values for session validationUsed for additional session verification
Response
Returns a ShoppingCart object representing the transferred session’s cart state.Session Transfer Behavior
Handle Processing
- Simple string handles are used directly
- JSON handles can include security tokens and metadata
- Tokens must be at least 36 characters for security
- Handle and cookies are hashed for session identification
Transfer Process
- External session is validated
- Cart contents are imported
- Firmly session is created/updated
- V2 cart format is returned
Security Considerations
- Handles are validated for minimum length
- Cookies are sorted before hashing
- Session data is encrypted in transit
- Failed transfers don’t create partial sessions
Errors
ErrorCannotTransferSession
Status Code: 422Description: Session transfer failed (invalid handle, expired session, etc.)
ErrorNoLineItem
Status Code: 422Description: Transferred session has empty cart
ErrorNotEnoughStock
Status Code: 422Description: Items in transferred cart exceed available stock
MissingAuthHeader
Status Code: 401Description: x-firmly-authorization header is missing or invalid
ErrorInvalidInputBody
Status Code: 400Description: Request body validation failed
Examples
Response Example
Use Cases
Platform Migration
- Move carts from native checkout to Firmly
- Preserve cart state during platform switches
- Enable cross-platform shopping experiences
Session Recovery
- Recover abandoned external sessions
- Merge guest and authenticated sessions
- Handle session timeouts gracefully
Multi-Channel Commerce
- Transfer mobile app carts to web
- Sync in-store kiosk sessions
- Unite omnichannel shopping experiences
Implementation Notes
Integration Requirements
- Merchant must implement session export
- Handle format must be agreed upon
- Security tokens should be implemented
- Stock validation must be real-time
Session Transfer