Skip to main content
GET
/
carts
/
active
Get Active Carts
curl --request GET \
  --url https://api.firmly.work/carts/active \
  --header 'Authorization: Bearer <token>'
{
  "domains": [
    {}
  ],
  "carts": [
    {}
  ]
}

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 retrieves all active cart sessions across multiple merchant domains for the current device. It enables cross-domain cart access, allowing customers to view and manage carts from different merchants in a unified experience.
This is a global session endpoint that works across all merchant domains, not specific to a single domain.

Authentication

Requires Device Authentication.

Request

excludes
string
Comma-separated list of domain names to exclude from the resultsExample: store1.com,store2.com

Response

domains
array
List of domain names that have active carts
carts
array
Array of ShoppingCart objects for each active domainEach cart includes:
  • Full V2 cart schema
  • Domain information
  • All shipments and addons
  • Current totals

Session Behavior

Cross-Domain Management

  • Aggregates carts from all domains associated with the device session
  • Each cart maintains its own domain-specific state
  • Failed retrievals for individual domains don’t fail the entire request

Active Cart Criteria

  • Cart must have at least one line item
  • Cart session must not be expired
  • Empty carts are excluded from results

Performance Considerations

  • Carts are retrieved in parallel for efficiency
  • Large numbers of active carts may increase response time
  • Use the excludes parameter to filter unwanted domains

Errors

MissingAuthHeader

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

InvalidJWTToken

Status Code: 401
Description: The JWT token is invalid

InvalidToken

Status Code: 401
Description: JWT token is invalid

Examples

curl -X GET 'https://api.firmly.work/api/v2/carts/active' \
  -H 'x-firmly-authorization: <your-auth-token>' \
  -H 'Content-Type: application/json'

Response Example

{
  "domains": [
    "electronics-store.com",
    "fashion-boutique.com"
  ],
  "carts": [
    {
      "id": "cart_abc123",
      "domain": "staging.luma.gift",
      "schema_version": "2.0",
      "line_items": [
        {
          "id": "item_1",
          "variant_id": "MH07-XS-Gray",
          "quantity": 2,
          "unit_price": 54.00,
          "total_price": 108.00,
          "product": {
            "id": "MH07",
            "title": "Hero Hoodie",
            "handle": "hero-hoodie"
          }
        }
      ],
      "shipments": [
        {
          "id": "ship_1",
          "fulfillment_type": "SHIP_TO_ADDRESS",
          "line_items": ["item_1"],
          "subtotal": 108.00,
          "shipping_total": 9.99,
          "tax_total": 8.64,
          "total": 126.63
        }
      ],
      "addons": [],
      "subtotal": 108.00,
      "shipping_total": 9.99,
      "tax_total": 8.64,
      "addon_total": 0.00,
      "total": 126.63,
      "currency": "USD"
    },
    {
      "id": "cart_def456",
      "domain": "demo.luma.gift",
      "schema_version": "2.0",
      "line_items": [
        {
          "id": "item_2",
          "variant_id": "WS12-XS-Orange",
          "quantity": 1,
          "unit_price": 22.00,
          "total_price": 22.00,
          "product": {
            "id": "WS12",
            "title": "Radiant Tee",
            "handle": "radiant-tee"
          }
        }
      ],
      "shipments": [
        {
          "id": "ship_2",
          "fulfillment_type": "SHIP_TO_ADDRESS",
          "line_items": ["item_2"],
          "subtotal": 22.00,
          "shipping_total": 5.99,
          "tax_total": 1.76,
          "total": 29.75
        }
      ],
      "addons": [],
      "subtotal": 22.00,
      "shipping_total": 5.99,
      "tax_total": 1.76,
      "addon_total": 0.00,
      "total": 29.75,
      "currency": "USD"
    }
  ]
}

Use Cases

Multi-Store Checkout

  • Display all active carts in a unified checkout flow
  • Allow customers to manage multiple merchant carts
  • Calculate combined totals across stores

Cart Recovery

  • Retrieve abandoned carts across domains
  • Implement cross-domain cart recovery flows
  • Track shopping behavior across merchants

Analytics

  • Monitor active sessions across merchant network
  • Track cross-domain shopping patterns
  • Analyze cart abandonment by domain