> ## 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.

# Session Transfer

> Transfers an external merchant session to Firmly's cart system

## 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.

<Warning>
  This endpoint requires special integration setup. Contact Firmly support for implementation details.
</Warning>

## Authentication

Requires [Device Authentication](/api-reference/authentication/browser-session).

## Request

<ParamField path="domain" type="string" required>
  The merchant's domain (e.g. staging.luma.gift)
</ParamField>

<ParamField body="handle" type="string | object" required>
  Session identifier or structured handle object

  Can be:

  * Simple string handle
  * JSON object with additional metadata
</ParamField>

<Note>
  When using a JSON object handle, it should have the following structure:

  ```json theme={null}
  {
    "handle": "session-id",
    "token": "optional-security-token",
    "merchantData": {...},
    "version": "1.0"
  }
  ```
</Note>

<ParamField body="cookies" type="array">
  Optional array of cookie values for session validation

  Used for additional session verification
</ParamField>

## Response

Returns a [ShoppingCart](/api-reference/cart-management/get-cart) 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

<CodeGroup>
  ```bash Simple Handle theme={null}
  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"
    }'
  ```

  ```bash Handle with Metadata theme={null}
  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": {
        "handle": "external-session-12345",
        "token": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0",
        "version": "2.0",
        "merchantData": {
          "source": "mobile-app",
          "campaign": "summer-sale"
        }
      },
      "cookies": ["session_cookie_1", "tracking_cookie_2"]
    }'
  ```

  ```javascript JavaScript theme={null}
  // Simple transfer
  const response = await fetch('https://api.firmly.work/api/v2/domains/staging.luma.gift/session/transfer', {
    method: 'POST',
    headers: {
      'x-firmly-authorization': '<your-auth-token>',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      handle: 'external-session-12345'
    })
  });

  const cart = await response.json();

  // Transfer with metadata
  const responseWithMeta = await fetch('https://api.firmly.work/api/v2/domains/staging.luma.gift/session/transfer', {
    method: 'POST',
    headers: {
      'x-firmly-authorization': '<your-auth-token>',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      handle: {
        handle: 'external-session-12345',
        token: 'a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0',
        version: '2.0',
        merchantData: {
          source: 'mobile-app'
        }
      }
    })
  });
  ```

  ```python Python theme={null}
  import requests
  import json

  # Simple transfer
  response = requests.post(
      'https://api.firmly.work/api/v2/domains/staging.luma.gift/session/transfer',
      headers={
          'x-firmly-authorization': '<your-auth-token>',
          'Content-Type': 'application/json'
      },
      json={
          'handle': 'external-session-12345'
      }
  )

  cart = response.json()

  # Transfer with metadata
  response_with_meta = requests.post(
      'https://api.firmly.work/api/v2/domains/staging.luma.gift/session/transfer',
      headers={
          'x-firmly-authorization': '<your-auth-token>',
          'Content-Type': 'application/json'
      },
      json={
          'handle': {
              'handle': 'external-session-12345',
              'token': 'a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0',
              'version': '2.0',
              'merchantData': {
                  'source': 'mobile-app'
              }
          }
      }
  )
  ```
</CodeGroup>

## Response Example

```json theme={null}
{
  "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