Get Cart - Firmly API

GET

api

domains

{domain}

cart

Get Cart

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

{
  "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

x-firmly-authorization

string

required

Device authentication token to identify and map the session

Path Parameters

domain

string

required

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

Response

cart_id

string

Unique identifier for the shopping cart session

platform_id

string

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

shop_id

string

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

display_name

string

Merchant display name

cart_status

string

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

line_items

array

Array of products currently in the cart

Show Line Item Properties

line_item_id

string

Unique identifier for the line item

platform_line_item_id

string

Platform-specific line item identifier

sku

string

Product SKU identifier

variant_description

string

Variant-specific description

description

string

Product description

base_sku

string

Base product SKU (parent of variants)

quantity

number

Quantity of the item in cart

price

object

Unit price information

currency

string

Currency code (e.g., USD)

value

number

Price as decimal

number

Price in smallest currency unit

symbol

string

Currency symbol

line_price

object

Total price for this line (price × quantity)

currency

string

Currency code (e.g., USD)

value

number

Price as decimal

number

Price in smallest currency unit

symbol

string

Currency symbol

msrp

object

Manufacturer’s suggested retail price

currency

string

Currency code (e.g., USD)

value

number

Price as decimal

number

Price in smallest currency unit

symbol

string

Currency symbol

image

object

Product image information

src

string

Image URL

alt

string

Alternative text

requires_shipping

boolean

Whether this item requires physical shipping

shipments

array

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

Show Shipment Properties

shipment_id

string

Unique identifier for the shipment

line_item_ids

array

Array of line item IDs included in this shipment

fulfillment_type

object

Selected fulfillment method (automatically set to default)

string

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

name

string

Display name

description

string

Detailed description

fulfillment_type_options

array

Available fulfillment types for this shipment

shipping_method_options

array

Available shipping methods for the selected fulfillment type

shipping_method

object

Selected shipping method (defaults to cheapest available option)

string

Shipping method identifier

description

string

Shipping method description

price

object

Shipping cost

estimated_delivery

string

Delivery timeframe

notes

string

Special instructions or notes for this shipment

selected_date

string

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

addons

object

Available addon services and current selections

Show Addon Properties

offers

array

Available addon options

addon_id

string

Unique addon identifier

display

object

Display information

scope

string

Addon scope (CART or ITEM)

price

object

Addon price

selections

array

Currently selected addons

sub_total

object

Subtotal of all line items

shipping_total

object

Total shipping cost across all shipments

tax_total

object

Total tax amount

addon_total

object

Total cost of selected addons

total

object

Grand total including all costs

shipping_info

object

Shipping address information (when address is set)

Show Shipping Info Properties

first_name

string

Recipient’s first name

last_name

string

Recipient’s last name

string

Recipient’s email address

phone

string

Recipient’s phone number

company

string

Company name (optional)

address_line_1

string

Street address line 1

address_line_2

string

Street address line 2 (optional)

city

string

City name

state_code

string

State/province code

zip

string

ZIP/postal code

country_code

string

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

payment_handle

string

Payment handle identifier (when payment is configured)

payment_method_options

array

Available payment methods for checkout

Show Payment Method Object

type

string

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

wallet

string

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

notices

array

Cart notices providing information about cart state and issues

Show Notice Properties

code

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

severity

string

Notice severity level: info, warning, or error

item_id

string

Line item ID if notice is item-specific

details

object

Additional notice details

Show Details Properties

description

string

Detailed description of the notice

Affected promo code (for promo-related notices)

old_value

object

Previous price (for price change notices)

new_value

object

New price (for price change notices)

reason

string

Reason for the notice

schema_version

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'

{
  "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

Add Line ItemAdds a product variant to the cart with automatic shipment grouping based on fulfillment requirements

⌘I

Get Cart

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

{
  "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

​Authentication

​Path Parameters

​Response

​Code Examples

​Error Responses

​Related Endpoints

Overview

Authentication

Path Parameters

Response

Code Examples

Error Responses

Related Endpoints