Skip to main content
POST
/
api
/
v2
/
domains
/
{domain}
/
session
/
transfer
Session Transfer
curl --request POST \
  --url https://api.firmly.work/api/v2/domains/{domain}/session/transfer \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "handle": {},
  "cookies": [
    {}
  ]
}
'

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

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.
This endpoint requires special integration setup. Contact Firmly support for implementation details.

​
Authentication

Requires Device Authentication.

​
Request

​
domain
string
required
The merchant’s domain (e.g. staging.luma.gift)
​
handle
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:
{
  "handle": "session-id",
  "token": "optional-security-token",
  "merchantData": {...},
  "version": "1.0"
}
​
cookies
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

  1. External session is validated
  2. Cart contents are imported
  3. Firmly session is created/updated
  4. 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: 422
Description: Session transfer failed (invalid handle, expired session, etc.)

​
ErrorNoLineItem

Status Code: 422
Description: Transferred session has empty cart

​
ErrorNotEnoughStock

Status Code: 422
Description: Items in transferred cart exceed available stock

​
MissingAuthHeader

Status Code: 401
Description: x-firmly-authorization header is missing or invalid

​
ErrorInvalidInputBody

Status Code: 400
Description: Request body validation failed

​
Examples

curl -X POST 'https://api.firmly.work/api/v2/domains/staging.luma.gift/session/transfer' \
  -H 'x-firmly-authorization: <your-auth-token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "handle": "external-session-12345"
  }'

​
Response Example

{
  "id": "firmly_cart_123",
  "domain": "staging.luma.gift",
  "schema_version": "2.0",
  "line_items": [
    {
      "id": "item_1",
      "variant_id": "WS12-XS-Orange",
      "quantity": 1,
      "unit_price": 49.99,
      "total_price": 49.99,
      "product": {
        "id": "WS12",
        "title": "Radiant Tee",
        "handle": "radiant-tee"
      }
    }
  ],
  "shipments": [
    {
      "id": "ship_1",
      "fulfillment_type": "SHIP_TO_ADDRESS",
      "line_items": ["item_1"],
      "subtotal": 49.99,
      "shipping_total": 5.99,
      "tax_total": 4.48,
      "total": 60.46
    }
  ],
  "addons": [],
  "subtotal": 49.99,
  "shipping_total": 5.99,
  "tax_total": 4.48,
  "addon_total": 0.00,
  "total": 60.46,
  "currency": "USD",
  "metadata": {
    "transferred_at": "2024-01-15T10:30:00Z",
    "source": "external_session"
  }
}

​
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

  1. Merchant must implement session export
  2. Handle format must be agreed upon
  3. Security tokens should be implemented
  4. Stock validation must be real-time