Skip to main content
POST
/
api
/
v1
/
domains
/
{domain}
/
cart
/
line-items
/
{sku}
/
quantity
/
{quantity}
curl --request POST \
  --url https://api.firmly.work/api/v1/domains/staging.luma.gift/cart/line-items/WS12-XS-Orange/quantity/1 \
  --header 'x-firmly-authorization: YOUR_TOKEN'

{
  "cart_id": "1e43868c-d4a5-418c-bd6b-5fff043550d2",
  "platform_id": "example",
  "shop_id": "staging.luma.gift",
  "display_name": "Luma Store",
  "line_items": [
    {
      "line_item_id": "1ee530e1-063d-4e07-afb2-e7e65245977e",
      "platform_line_item_id": "4df9941b-bd06-4495-8759-61c6145dc408",
      "sku": "WS12-XS-Orange",
      "base_sku": "WS12",
      "quantity": 1,
      "description": "Radiant Tee - Orange XS",
      "price": {
        "currency": "USD",
        "value": 22.00,
        "symbol": "$",
        "number": 2200
      },
      "line_price": {
        "currency": "USD",
        "value": 22.00,
        "symbol": "$",
        "number": 2200
      },
      "msrp": {
        "currency": "USD",
        "value": 22.00,
        "symbol": "$",
        "number": 2200
      },
      "image": {
        "url": "https://cdn.staging.luma.gift/products/radiant-tee/orange.jpg"
      },
      "requires_shipping": true
    }
  ],
  "sub_total": {
    "currency": "USD",
    "value": 869.99,
    "symbol": "$",
    "number": 86999
  },
  "shipping_total": {
    "currency": "USD",
    "value": 0,
    "symbol": "$",
    "number": 0
  },
  "tax": {
    "currency": "USD",
    "value": 2.20,
    "symbol": "$",
    "number": 220
  },
  "total": {
    "currency": "USD",
    "value": 24.20,
    "symbol": "$",
    "number": 2420
  },
  "payment_method_options": [
    {
      "type": "CreditCard",
      "wallet": "user"
    }
  ]
}

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

Adds a product to the cart using its SKU. To find available products and their SKUs, use the Catalog API.

​
Authentication

​
x-firmly-authorization
string
required
Device authentication token from browser session

​
Path Parameters

​
domain
string
required
Merchant domain (e.g., staging.luma.gift)
​
sku
string
required
Product SKU to add to cart (e.g., WS12-XS-Orange)
​
quantity
number
required
Quantity to add (minimum: 1)

​
Request Body

​
variant_handles
array
List of variant handles required by some merchants to fully identify the product

​
Query Parameters

​
flush_cart
string
default:"false"
Set to true to clear the cart before adding the item
​
fast_mode
string
default:"false"
Set to true for faster response with potentially cached data

​
Response

Returns the updated shopping cart.

​
Response Fields

​
cart_id
string
Unique identifier for the cart
​
line_items
array
Array of items in the cart
​
sub_total
object
Subtotal before shipping and tax
​
shipping_total
object
Shipping cost (if shipping info has been set)
​
tax
object
Tax amount
​
total
object
Grand total including all costs
curl --request POST \
  --url https://api.firmly.work/api/v1/domains/staging.luma.gift/cart/line-items/WS12-XS-Orange/quantity/1 \
  --header 'x-firmly-authorization: YOUR_TOKEN'

{
  "cart_id": "1e43868c-d4a5-418c-bd6b-5fff043550d2",
  "platform_id": "example",
  "shop_id": "staging.luma.gift",
  "display_name": "Luma Store",
  "line_items": [
    {
      "line_item_id": "1ee530e1-063d-4e07-afb2-e7e65245977e",
      "platform_line_item_id": "4df9941b-bd06-4495-8759-61c6145dc408",
      "sku": "WS12-XS-Orange",
      "base_sku": "WS12",
      "quantity": 1,
      "description": "Radiant Tee - Orange XS",
      "price": {
        "currency": "USD",
        "value": 22.00,
        "symbol": "$",
        "number": 2200
      },
      "line_price": {
        "currency": "USD",
        "value": 22.00,
        "symbol": "$",
        "number": 2200
      },
      "msrp": {
        "currency": "USD",
        "value": 22.00,
        "symbol": "$",
        "number": 2200
      },
      "image": {
        "url": "https://cdn.staging.luma.gift/products/radiant-tee/orange.jpg"
      },
      "requires_shipping": true
    }
  ],
  "sub_total": {
    "currency": "USD",
    "value": 869.99,
    "symbol": "$",
    "number": 86999
  },
  "shipping_total": {
    "currency": "USD",
    "value": 0,
    "symbol": "$",
    "number": 0
  },
  "tax": {
    "currency": "USD",
    "value": 2.20,
    "symbol": "$",
    "number": 220
  },
  "total": {
    "currency": "USD",
    "value": 24.20,
    "symbol": "$",
    "number": 2420
  },
  "payment_method_options": [
    {
      "type": "CreditCard",
      "wallet": "user"
    }
  ]
}

​
Error Responses

​
400 Bad Request

Missing or invalid authentication header

​
404 Not Found

Product not found with the given SKU

​
409 Conflict

Not enough stock available for the requested quantity

​
422 Unprocessable Entity

Invalid request body format