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