Get Cart

GET

api

domains

{domain}

cart

Get Cart

curl --request GET \
  --url https://api.firmly.work/api/v2/domains/{domain}/cart \
  --header 'Authorization: Bearer <token>'

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

fetch('https://api.firmly.work/api/v2/domains/{domain}/cart', 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/api/v2/domains/{domain}/cart",
  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/api/v2/domains/{domain}/cart"

	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/api/v2/domains/{domain}/cart")

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

{
  "cart_id": "cart_01H2XVBR8C8JS5MQSFPJ8HF9SA",
  "platform_id": "shopify",
  "shop_id": "staging.luma.gift",
  "display_name": "Luma Store",
  "cart_status": "active",
  "line_items": [
    {
      "line_item_id": "item_01H2XVBR8C8JS5MQSFPJ8HF9SB",
      "platform_line_item_id": "0",
      "sku": "MH07-XS-Gray",
      "variant_description": "Gray / XS",
      "description": "Hero Hoodie",
      "base_sku": "MH07",
      "quantity": 1,
      "price": {
        "currency": "USD",
        "value": 54.00,
        "number": 5400,
        "symbol": "$"
      },
      "line_price": {
        "currency": "USD",
        "value": 54.00,
        "number": 5400,
        "symbol": "$"
      },
      "msrp": {
        "currency": "USD",
        "value": 64.00,
        "number": 6400,
        "symbol": "$"
      },
      "image": {
        "src": "https://staging.luma.gift/images/hero-hoodie.jpg",
        "alt": "Hero Hoodie in Gray"
      },
      "requires_shipping": true
    }
  ],
  "shipments": [
    {
      "shipment_id": "ship_01H2XVBR8C8JS5MQSFPJ8HF9SD",
      "line_item_ids": ["item_01H2XVBR8C8JS5MQSFPJ8HF9SB"],
      "fulfillment_type": {
        "id": "SCHEDULED_DELIVERY",
        "name": "Scheduled Delivery",
        "description": "White glove delivery with scheduled time"
      },
      "fulfillment_type_options": [
        {
          "id": "SHIP_TO_ADDRESS",
          "name": "Ship to Address",
          "description": "Standard shipping to customer address"
        },
        {
          "id": "SCHEDULED_DELIVERY",
          "name": "Scheduled Delivery",
          "description": "White glove delivery with scheduled time"
        },
        {
          "id": "IN_STORE_PICKUP",
          "name": "In-Store Pickup",
          "description": "Pick up at store location"
        }
      ],
      "shipping_method_options": [
        {
          "id": "WHITE_GLOVE",
          "description": "White Glove Delivery Service",
          "price": {
            "currency": "USD",
            "value": 149.99,
            "number": 14999,
            "symbol": "$"
          },
          "estimated_delivery": "Scheduled delivery"
        }
      ],
      "shipping_method": {
        "id": "WHITE_GLOVE",
        "description": "White Glove Delivery Service",
        "price": {
          "currency": "USD",
          "value": 149.99,
          "number": 14999,
          "symbol": "$"
        },
        "estimated_delivery": "Scheduled delivery"
      },
      "notes": "",
      "selected_date": "2025-07-14",
    }
  ],
  "addons": {
    "offers": [
      {
        "addon_id": "shipping_protection",
        "display": {
          "name": "Shipping Protection",
          "description": "Protect your order against shipping damage"
        },
        "scope": "CART",
        "price": {
          "currency": "USD",
          "value": 12.99,
          "number": 1299,
          "symbol": "$"
        }
      }
    ],
    "selections": []
  },
  "sub_total": {
    "currency": "USD",
    "value": 54.00,
    "number": 5400,
    "symbol": "$"
  },
  "shipping_total": {
    "currency": "USD",
    "value": 149.99,
    "number": 14999,
    "symbol": "$"
  },
  "tax_total": {
    "currency": "USD",
    "value": 5.40,
    "number": 540,
    "symbol": "$"
  },
  "addon_total": {
    "currency": "USD",
    "value": 0.00,
    "number": 0,
    "symbol": "$"
  },
  "total": {
    "currency": "USD",
    "value": 209.39,
    "number": 20939,
    "symbol": "$"
  },
  "shipping_info": {
    "first_name": "John",
    "last_name": "Doe",
    "email": "john.doe@staging.luma.gift",
    "phone": "+1234567890",
    "company": "",
    "address_line_1": "123 Main Street",
    "address_line_2": "Apt 4B",
    "city": "New York",
    "state_code": "NY",
    "zip": "10001",
    "country_code": "US"
  },
  "payment_handle": "pay_01H2XVBR8C8JS5MQSFPJ8HF9SE",
  "payment_method_options": [
    {
      "type": "CreditCard",
      "wallet": "user"
    },
    {
      "type": "PayPal",
      "wallet": "paypal"
    }
  ],
  "notices": [
    {
      "code": "ITEM_NOT_SHIPPABLE",
      "severity": "error",
      "item_id": "item_01H2XVBR8C8JS5MQSFPJ8HF9SB",
      "details": {
        "description": "This item cannot be shipped to the selected address",
        "reason": "Shipping restrictions apply to this location"
      }
    }
  ],
  "schema_version": "2.0"
}

Overview

The Get Cart endpoint retrieves the complete current state of a shopping cart, including:

All line items with product details and quantities
Multiple shipments with items grouped by fulfillment requirements
Complete pricing breakdown (subtotal, shipping, tax, addons, total)
Available addon offers and current selections
Cart-level metadata and schema version

Authentication

string

required

Device authentication token to identify and map the session

Path Parameters

string

required

Domain of the merchant website (e.g., staging.luma.gift)

Response

string

Unique identifier for the shopping cart session

string

Platform identifier (e.g., “shopify”, “bigcommerce”, “magento”)

string

Shop identifier (merchant domain, e.g., “staging.luma.gift”)

string

Merchant display name

string

Current cart status (e.g., “active”)

array

Array of products currently in the cart

Show Line Item Properties

string

Unique identifier for the line item

string

Platform-specific line item identifier

string

Product SKU identifier

string

Variant-specific description

string

Product description

string

Base product SKU (parent of variants)

number

Quantity of the item in cart

object

Unit price information

string

Currency code (e.g., USD)

number

Price as decimal

number

Price in smallest currency unit

string

Currency symbol

object

Total price for this line (price × quantity)

string

Currency code (e.g., USD)

number

Price as decimal

number

Price in smallest currency unit

string

Currency symbol

object

Manufacturer’s suggested retail price

string

Currency code (e.g., USD)

number

Price as decimal

number

Price in smallest currency unit

string

Currency symbol

object

Product image information

string

Image URL

string

Alternative text

boolean

Whether this item requires physical shipping

array

Array of shipment groups, each containing line items with similar fulfillment requirements

Show Shipment Properties

string

Unique identifier for the shipment

array

Array of line item IDs included in this shipment

object

Selected fulfillment method (automatically set to default)

string

Fulfillment type identifier (e.g., SHIP_TO_ADDRESS, SCHEDULED_DELIVERY, IN_STORE_PICKUP)

string

Display name

string

Detailed description

array

Available fulfillment types for this shipment

array

Available shipping methods for the selected fulfillment type

object

Selected shipping method (defaults to cheapest available option)

string

Shipping method identifier

string

Shipping method description

object

Shipping cost

string

Delivery timeframe

string

Special instructions or notes for this shipment

string

Selected delivery date for scheduled delivery (YYYY-MM-DD format)

object

Available addon services and current selections

Show Addon Properties

array

Available addon options

string

Unique addon identifier

object

Display information

string

Addon scope (CART or ITEM)

object

Addon price

array

Currently selected addons

object

Subtotal of all line items

object

Total shipping cost across all shipments

object

Total tax amount

object

Total cost of selected addons

object

Grand total including all costs

object

Shipping address information (when address is set)

Show Shipping Info Properties

string

Recipient’s first name

string

Recipient’s last name

string

Recipient’s email address

string

Recipient’s phone number

string

Company name (optional)

string

Street address line 1

string

Street address line 2 (optional)

string

City name

string

State/province code

string

ZIP/postal code

string

Country code (e.g., US, CA)

string

Payment handle identifier (when payment is configured)

array

Available payment methods for checkout

Show Payment Method Object

string

Payment method type (e.g., “CreditCard”, “PayPal”)

string

Wallet identifier (e.g., “user”, “paypal”)

array

Cart notices providing information about cart state and issues

Show Notice Properties

string

Notice code identifier

Show Available Codes

ITEM_NOT_SHIPPABLE - Item cannot be shipped to selected address
ITEM_OUT_OF_STOCK - Item is out of stock
PROMO_EXPIRED - Promotion code has expired
PROMO_NOT_APPLICABLE - Promotion doesn’t apply to cart
SHIPPING_NOT_AVAILABLE - Shipping method unavailable
PRICE_INCREASED - Item price has increased
PRICE_DECREASED - Item price has decreased

string

Notice severity level: info, warning, or error

string

Line item ID if notice is item-specific

object

Additional notice details

Show Details Properties

string

Detailed description of the notice

Affected promo code (for promo-related notices)

object

Previous price (for price change notices)

object

New price (for price change notices)

string

Reason for the notice

string

Cart schema version (“2.0”)

Code Examples

curl --request GET \
  --url https://api.firmly.work/api/v2/domains/staging.luma.gift/cart \
  --header 'x-firmly-authorization: YOUR_TOKEN'

const response = await fetch('https://api.firmly.work/api/v2/domains/staging.luma.gift/cart', {
  method: 'GET',
  headers: {
    'x-firmly-authorization': 'YOUR_TOKEN'
  }
});

const cart = await response.json();
console.log(cart);

import requests

response = requests.get(
    'https://api.firmly.work/api/v2/domains/staging.luma.gift/cart',
    headers={
        'x-firmly-authorization': 'YOUR_TOKEN'
    }
)

cart = response.json()
print(cart)

<?php
$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.firmly.work/api/v2/domains/staging.luma.gift/cart",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => [
    "x-firmly-authorization: YOUR_TOKEN"
  ],
]);

$response = curl_exec($curl);
curl_close($curl);

$cart = json_decode($response, true);
print_r($cart);
?>

{
  "cart_id": "cart_01H2XVBR8C8JS5MQSFPJ8HF9SA",
  "platform_id": "shopify",
  "shop_id": "staging.luma.gift",
  "display_name": "Luma Store",
  "cart_status": "active",
  "line_items": [
    {
      "line_item_id": "item_01H2XVBR8C8JS5MQSFPJ8HF9SB",
      "platform_line_item_id": "0",
      "sku": "MH07-XS-Gray",
      "variant_description": "Gray / XS",
      "description": "Hero Hoodie",
      "base_sku": "MH07",
      "quantity": 1,
      "price": {
        "currency": "USD",
        "value": 54.00,
        "number": 5400,
        "symbol": "$"
      },
      "line_price": {
        "currency": "USD",
        "value": 54.00,
        "number": 5400,
        "symbol": "$"
      },
      "msrp": {
        "currency": "USD",
        "value": 64.00,
        "number": 6400,
        "symbol": "$"
      },
      "image": {
        "src": "https://staging.luma.gift/images/hero-hoodie.jpg",
        "alt": "Hero Hoodie in Gray"
      },
      "requires_shipping": true
    }
  ],
  "shipments": [
    {
      "shipment_id": "ship_01H2XVBR8C8JS5MQSFPJ8HF9SD",
      "line_item_ids": ["item_01H2XVBR8C8JS5MQSFPJ8HF9SB"],
      "fulfillment_type": {
        "id": "SCHEDULED_DELIVERY",
        "name": "Scheduled Delivery",
        "description": "White glove delivery with scheduled time"
      },
      "fulfillment_type_options": [
        {
          "id": "SHIP_TO_ADDRESS",
          "name": "Ship to Address",
          "description": "Standard shipping to customer address"
        },
        {
          "id": "SCHEDULED_DELIVERY",
          "name": "Scheduled Delivery",
          "description": "White glove delivery with scheduled time"
        },
        {
          "id": "IN_STORE_PICKUP",
          "name": "In-Store Pickup",
          "description": "Pick up at store location"
        }
      ],
      "shipping_method_options": [
        {
          "id": "WHITE_GLOVE",
          "description": "White Glove Delivery Service",
          "price": {
            "currency": "USD",
            "value": 149.99,
            "number": 14999,
            "symbol": "$"
          },
          "estimated_delivery": "Scheduled delivery"
        }
      ],
      "shipping_method": {
        "id": "WHITE_GLOVE",
        "description": "White Glove Delivery Service",
        "price": {
          "currency": "USD",
          "value": 149.99,
          "number": 14999,
          "symbol": "$"
        },
        "estimated_delivery": "Scheduled delivery"
      },
      "notes": "",
      "selected_date": "2025-07-14",
    }
  ],
  "addons": {
    "offers": [
      {
        "addon_id": "shipping_protection",
        "display": {
          "name": "Shipping Protection",
          "description": "Protect your order against shipping damage"
        },
        "scope": "CART",
        "price": {
          "currency": "USD",
          "value": 12.99,
          "number": 1299,
          "symbol": "$"
        }
      }
    ],
    "selections": []
  },
  "sub_total": {
    "currency": "USD",
    "value": 54.00,
    "number": 5400,
    "symbol": "$"
  },
  "shipping_total": {
    "currency": "USD",
    "value": 149.99,
    "number": 14999,
    "symbol": "$"
  },
  "tax_total": {
    "currency": "USD",
    "value": 5.40,
    "number": 540,
    "symbol": "$"
  },
  "addon_total": {
    "currency": "USD",
    "value": 0.00,
    "number": 0,
    "symbol": "$"
  },
  "total": {
    "currency": "USD",
    "value": 209.39,
    "number": 20939,
    "symbol": "$"
  },
  "shipping_info": {
    "first_name": "John",
    "last_name": "Doe",
    "email": "john.doe@staging.luma.gift",
    "phone": "+1234567890",
    "company": "",
    "address_line_1": "123 Main Street",
    "address_line_2": "Apt 4B",
    "city": "New York",
    "state_code": "NY",
    "zip": "10001",
    "country_code": "US"
  },
  "payment_handle": "pay_01H2XVBR8C8JS5MQSFPJ8HF9SE",
  "payment_method_options": [
    {
      "type": "CreditCard",
      "wallet": "user"
    },
    {
      "type": "PayPal",
      "wallet": "paypal"
    }
  ],
  "notices": [
    {
      "code": "ITEM_NOT_SHIPPABLE",
      "severity": "error",
      "item_id": "item_01H2XVBR8C8JS5MQSFPJ8HF9SB",
      "details": {
        "description": "This item cannot be shipped to the selected address",
        "reason": "Shipping restrictions apply to this location"
      }
    }
  ],
  "schema_version": "2.0"
}

Error Responses

400 Bad Request

Invalid request format or missing required headers

{
  "code": 400,
  "error": "MissingAuthHeader",
  "description": "x-firmly-authorization header is required"
}

401 Unauthorized

Invalid or expired authentication token

{
  "code": 401,
  "error": "InvalidJWTToken",
  "description": "The JWT token is invalid"
}

404 Not Found

Cart does not exist for the given domain

{
  "code": 404,
  "error": "ErrorCartNotFound",
  "description": "Cart not found"
}

422 Unprocessable Entity

Store service unavailable or other processing error

{
  "code": 422,
  "error": "ErrorStoreUnavailable",
  "description": "Store service unavailable"
}

Add Line Item - Add items to cart
Update Line Item - Modify cart items
Clear Cart - Empty the cart

⌘I

Get Cart

curl --request GET \
  --url https://api.firmly.work/api/v2/domains/{domain}/cart \
  --header 'Authorization: Bearer <token>'

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

fetch('https://api.firmly.work/api/v2/domains/{domain}/cart', 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/api/v2/domains/{domain}/cart",
  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/api/v2/domains/{domain}/cart"

	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/api/v2/domains/{domain}/cart")

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

{
  "cart_id": "cart_01H2XVBR8C8JS5MQSFPJ8HF9SA",
  "platform_id": "shopify",
  "shop_id": "staging.luma.gift",
  "display_name": "Luma Store",
  "cart_status": "active",
  "line_items": [
    {
      "line_item_id": "item_01H2XVBR8C8JS5MQSFPJ8HF9SB",
      "platform_line_item_id": "0",
      "sku": "MH07-XS-Gray",
      "variant_description": "Gray / XS",
      "description": "Hero Hoodie",
      "base_sku": "MH07",
      "quantity": 1,
      "price": {
        "currency": "USD",
        "value": 54.00,
        "number": 5400,
        "symbol": "$"
      },
      "line_price": {
        "currency": "USD",
        "value": 54.00,
        "number": 5400,
        "symbol": "$"
      },
      "msrp": {
        "currency": "USD",
        "value": 64.00,
        "number": 6400,
        "symbol": "$"
      },
      "image": {
        "src": "https://staging.luma.gift/images/hero-hoodie.jpg",
        "alt": "Hero Hoodie in Gray"
      },
      "requires_shipping": true
    }
  ],
  "shipments": [
    {
      "shipment_id": "ship_01H2XVBR8C8JS5MQSFPJ8HF9SD",
      "line_item_ids": ["item_01H2XVBR8C8JS5MQSFPJ8HF9SB"],
      "fulfillment_type": {
        "id": "SCHEDULED_DELIVERY",
        "name": "Scheduled Delivery",
        "description": "White glove delivery with scheduled time"
      },
      "fulfillment_type_options": [
        {
          "id": "SHIP_TO_ADDRESS",
          "name": "Ship to Address",
          "description": "Standard shipping to customer address"
        },
        {
          "id": "SCHEDULED_DELIVERY",
          "name": "Scheduled Delivery",
          "description": "White glove delivery with scheduled time"
        },
        {
          "id": "IN_STORE_PICKUP",
          "name": "In-Store Pickup",
          "description": "Pick up at store location"
        }
      ],
      "shipping_method_options": [
        {
          "id": "WHITE_GLOVE",
          "description": "White Glove Delivery Service",
          "price": {
            "currency": "USD",
            "value": 149.99,
            "number": 14999,
            "symbol": "$"
          },
          "estimated_delivery": "Scheduled delivery"
        }
      ],
      "shipping_method": {
        "id": "WHITE_GLOVE",
        "description": "White Glove Delivery Service",
        "price": {
          "currency": "USD",
          "value": 149.99,
          "number": 14999,
          "symbol": "$"
        },
        "estimated_delivery": "Scheduled delivery"
      },
      "notes": "",
      "selected_date": "2025-07-14",
    }
  ],
  "addons": {
    "offers": [
      {
        "addon_id": "shipping_protection",
        "display": {
          "name": "Shipping Protection",
          "description": "Protect your order against shipping damage"
        },
        "scope": "CART",
        "price": {
          "currency": "USD",
          "value": 12.99,
          "number": 1299,
          "symbol": "$"
        }
      }
    ],
    "selections": []
  },
  "sub_total": {
    "currency": "USD",
    "value": 54.00,
    "number": 5400,
    "symbol": "$"
  },
  "shipping_total": {
    "currency": "USD",
    "value": 149.99,
    "number": 14999,
    "symbol": "$"
  },
  "tax_total": {
    "currency": "USD",
    "value": 5.40,
    "number": 540,
    "symbol": "$"
  },
  "addon_total": {
    "currency": "USD",
    "value": 0.00,
    "number": 0,
    "symbol": "$"
  },
  "total": {
    "currency": "USD",
    "value": 209.39,
    "number": 20939,
    "symbol": "$"
  },
  "shipping_info": {
    "first_name": "John",
    "last_name": "Doe",
    "email": "john.doe@staging.luma.gift",
    "phone": "+1234567890",
    "company": "",
    "address_line_1": "123 Main Street",
    "address_line_2": "Apt 4B",
    "city": "New York",
    "state_code": "NY",
    "zip": "10001",
    "country_code": "US"
  },
  "payment_handle": "pay_01H2XVBR8C8JS5MQSFPJ8HF9SE",
  "payment_method_options": [
    {
      "type": "CreditCard",
      "wallet": "user"
    },
    {
      "type": "PayPal",
      "wallet": "paypal"
    }
  ],
  "notices": [
    {
      "code": "ITEM_NOT_SHIPPABLE",
      "severity": "error",
      "item_id": "item_01H2XVBR8C8JS5MQSFPJ8HF9SB",
      "details": {
        "description": "This item cannot be shipped to the selected address",
        "reason": "Shipping restrictions apply to this location"
      }
    }
  ],
  "schema_version": "2.0"
}

Home

Core Concepts

Implementation Guides

Ask Agent SDK

API Reference

firmly Connect

Resources

Overview

Authentication

Path Parameters

Response

Code Examples

Error Responses

​Overview

​Authentication

​Path Parameters

​Response

​Code Examples

​Error Responses

​Related Endpoints

Overview

Authentication

Path Parameters

Response

Code Examples

Error Responses

Related Endpoints