Skip to main content
POST
https://api.firmly.work
/
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"
    }
  ]
}

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