Get Active Carts

GET

carts

active

Get Active Carts

curl --request GET \
  --url https://api.firmly.work/carts/active \
  --header 'Authorization: Bearer <token>'

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.firmly.work/carts/active', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.firmly.work/carts/active",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.firmly.work/carts/active"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.firmly.work/carts/active")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

{
  "domains": [
    {}
  ],
  "carts": [
    {}
  ]
}

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

string

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

Response

array

List of domain names that have active 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'

curl -X GET 'https://api.firmly.work/api/v2/carts/active?excludes=store1.com,store2.com' \
  -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": [
    "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

⌘I

Get Active Carts

curl --request GET \
  --url https://api.firmly.work/carts/active \
  --header 'Authorization: Bearer <token>'

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.firmly.work/carts/active', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.firmly.work/carts/active",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.firmly.work/carts/active"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.firmly.work/carts/active")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

{
  "domains": [
    {}
  ],
  "carts": [
    {}
  ]
}

Home

Core Concepts

Implementation Guides

Ask Agent SDK

API Reference

firmly Connect

Resources

Overview

Authentication

Request

Response

Session Behavior

Cross-Domain Management

Active Cart Criteria

Performance Considerations

Errors

MissingAuthHeader

InvalidJWTToken

InvalidToken

Examples

Response Example

Use Cases

Multi-Store Checkout

Cart Recovery

Analytics

​Overview

​Authentication

​Request

​Response

​Session Behavior

​Cross-Domain Management

​Active Cart Criteria

​Performance Considerations

​Errors

​MissingAuthHeader

​InvalidJWTToken

​InvalidToken

​Examples

​Response Example

​Use Cases

​Multi-Store Checkout

​Cart Recovery

​Analytics

Overview

Authentication

Request

Response

Session Behavior

Cross-Domain Management

Active Cart Criteria

Performance Considerations

Errors

MissingAuthHeader

InvalidJWTToken

InvalidToken

Examples

Response Example

Use Cases

Multi-Store Checkout

Cart Recovery

Analytics