Docs
Firmly Agentic Commerce
Docs
Set theme to dark (⇧+D)
  1. Docs
  2. API Reference
  3. Session
  4. Get Active Carts

Get Active Carts

GET https://api.firmly.work/api/v2/carts/active

​​ Overview

This endpoint retrieves all active cart sessions across multiple merchant domains for the current device. It enables cross-domain cart access, allowing buyers to view and manage carts from different merchants in a unified experience.

​​ Authentication

​​ Query Parameters

  • excludes (string) — Comma-separated list of domain names to exclude from the results Example: store1.example,store2.example

​​ Response

  • domains (array) — List of domain names with an active cart on this device session (minus any passed in excludes). A domain stays in this list even if its cart could not be fetched on this call, so domains may contain more entries than carts.

  • carts (array) — Array of ShoppingCart objects for each domain whose cart was successfully fetched. May be shorter than domains when a domain’s cart fetch failed — match entries by shop_id, not by array position. Each cart carries the full V2 cart schema: domain information, all shipments and addons, and 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. A domain whose cart cannot be fetched still appears in the domains array — only its cart is left out of the carts array. This most commonly happens when a merchant adapter is temporarily unreachable (its per-domain Get Cart would return 503 StoreUnavailable); the failure is logged server-side and skipped rather than surfaced as an error entry. As a result, carts may be shorter than domains — match carts to domains by shop_id rather than by array position, and retry any missing domain via Get Cart if needed.

​​ 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

​​ Examples 


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


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


const response = await fetch('https://api.firmly.work/api/v2/carts/active', {
  headers: {
    'x-firmly-authorization': '<your-auth-token>',
    'Content-Type': 'application/json'
  }

});



const { domains, carts } = await response.json();


import requests


response = requests.get(
    'https://api.firmly.work/api/v2/carts/active',
    headers={
        'x-firmly-authorization': '<your-auth-token>',
        'Content-Type': 'application/json'
    }

)


data = response.json()
domains = data['domains']
carts = data['carts']

​​ Response Example 


{
  "domains": ["staging.luma.gift", "demo.luma.gift"],
  "carts": [
    {
      "cart_id": "a5600193-2c13-3356-d063-711da63b7cd7",
      "platform_id": "example_commerce",
      "shop_id": "staging.luma.gift",
      "cart_status": "active",
      "line_items": [
        {
          "line_item_id": "bd3710bc-97ef-408d-7382-43b7e5de712f",
          "sku": "MH07-XS-Gray",
          "base_sku": "MH07",
          "description": "Hero Hoodie",
          "quantity": 2,
          "price": { "currency": "USD", "value": 54.00, "number": 5400, "symbol": "$" },
          "msrp": { "currency": "USD", "value": 64.00, "number": 6400, "symbol": "$" },
          "line_price": { "currency": "USD", "value": 108.00, "number": 10800, "symbol": "$" },
          "image": { "url": "https://cdn.staging.luma.gift/hero-hoodie.jpg", "alt": "Hero Hoodie", "type": "default" },
          "requires_shipping": true
        }
      ],
      "shipments": [
        {
          "shipment_id": "c2a3f9e8-ba80-8ea1-8762-e498097c8e35",
          "line_item_ids": ["bd3710bc-97ef-408d-7382-43b7e5de712f"],
          "fulfillment_type": { "id": "SHIP_TO_ADDRESS", "name": "Ship to Address", "description": "Standard shipping to your address" },
          "shipping_method": {
            "id": "STANDARD_GROUND",
            "description": "Standard Ground",
            "price": { "currency": "USD", "value": 9.99, "number": 999, "symbol": "$" },
            "estimated_delivery": "5-7 business days"
          }
        }
      ],
      "sub_total": { "currency": "USD", "value": 108.00, "number": 10800, "symbol": "$" },
      "shipping_total": { "currency": "USD", "value": 9.99, "number": 999, "symbol": "$" },
      "tax_total": { "currency": "USD", "value": 8.64, "number": 864, "symbol": "$" },
      "fees": [{ "description": "Recycle fee", "currency": "USD", "value": 2.00, "number": 200, "symbol": "$" }],
      "fee_total": { "currency": "USD", "value": 2.00, "number": 200, "symbol": "$" },
      "addon_total": { "currency": "USD", "value": 0, "number": 0, "symbol": "$" },
      "total": { "currency": "USD", "value": 128.63, "number": 12863, "symbol": "$" },
      "addons": { "offers": [], "selections": [] },
      "schema_version": "2.0"
    },
    {
      "cart_id": "8e24c496-0edc-b6a4-72bb-a83a9b3c4ac3",
      "platform_id": "example_commerce",
      "shop_id": "demo.luma.gift",
      "cart_status": "active",
      "line_items": [
        {
          "line_item_id": "393005f1-18bb-ae90-7530-4b01fa6c6435",
          "sku": "WS12-XS-Orange",
          "base_sku": "WS12",
          "description": "Radiant Tee",
          "quantity": 1,
          "price": { "currency": "USD", "value": 22.00, "number": 2200, "symbol": "$" },
          "msrp": { "currency": "USD", "value": 26.00, "number": 2600, "symbol": "$" },
          "line_price": { "currency": "USD", "value": 22.00, "number": 2200, "symbol": "$" },
          "image": { "url": "https://cdn.demo.luma.gift/radiant-tee.jpg", "alt": "Radiant Tee", "type": "default" },
          "requires_shipping": true
        }
      ],
      "shipments": [
        {
          "shipment_id": "51991844-d23c-f52c-e447-8cb2156782f3",
          "line_item_ids": ["393005f1-18bb-ae90-7530-4b01fa6c6435"],
          "fulfillment_type": { "id": "SHIP_TO_ADDRESS", "name": "Ship to Address", "description": "Standard shipping to your address" },
          "shipping_method": {
            "id": "STANDARD_GROUND",
            "description": "Standard Ground",
            "price": { "currency": "USD", "value": 5.99, "number": 599, "symbol": "$" },
            "estimated_delivery": "5-7 business days"
          }
        }
      ],
      "sub_total": { "currency": "USD", "value": 22.00, "number": 2200, "symbol": "$" },
      "shipping_total": { "currency": "USD", "value": 5.99, "number": 599, "symbol": "$" },
      "tax_total": { "currency": "USD", "value": 1.76, "number": 176, "symbol": "$" },
      "fees": [{ "description": "Recycle fee", "currency": "USD", "value": 2.00, "number": 200, "symbol": "$" }],
      "fee_total": { "currency": "USD", "value": 2.00, "number": 200, "symbol": "$" },
      "addon_total": { "currency": "USD", "value": 0, "number": 0, "symbol": "$" },
      "total": { "currency": "USD", "value": 31.75, "number": 3175, "symbol": "$" },
      "addons": { "offers": [], "selections": [] },
      "schema_version": "2.0"
    }
  ]

}

​​ Use Cases

​​ Cart Switching

  • Show the buyer their active carts and let them resume any one
  • Each cart is scoped to its merchant and checks out independently

​​ 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

​​ Error Responses

Errors return a JSON body with code, error, and description. Program against the error value — descriptions are human-readable and may change.

400 — MissingAuthHeader

The x-firmly-authorization header is missing or empty.


{ "code": 400, "error": "MissingAuthHeader", "description": "x-firmly-authorization header is missing or invalid." }
400 — InvalidToken

The authorization token is not a valid JWT structure.


{ "code": 400, "error": "InvalidToken", "description": "Jwt token is invalid." }
401 — InvalidJWTToken

The device JWT signature does not verify, or required claims are missing.


{ "code": 401, "error": "InvalidJWTToken", "description": "Jwt token is invalid." }
404 — PartnerNotFound

The appid claim on the device JWT does not map to a known partner / tenant.


{ "code": 404, "error": "PartnerNotFound", "description": "Partner not found." }