Add Item to Cart

POST

api

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'

const response = await fetch('https://api.firmly.work/api/v1/domains/staging.luma.gift/cart/line-items/WS12-XS-Orange/quantity/1', {
  method: 'POST',
  headers: {
    'x-firmly-authorization': 'YOUR_TOKEN'
  }
});

const cart = await response.json();

import requests

response = requests.post(
    'https://api.firmly.work/api/v1/domains/staging.luma.gift/cart/line-items/WS12-XS-Orange/quantity/1',
    headers={
        'x-firmly-authorization': 'YOUR_TOKEN'
    }
)

cart = response.json()

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

string

required

Device authentication token from browser session

Path Parameters

string

required

Merchant domain (e.g., staging.luma.gift)

string

required

Product SKU to add to cart (e.g., WS12-XS-Orange)

number

required

Quantity to add (minimum: 1)

Request Body

array

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

Query Parameters

string

default:"false"

Set to true to clear the cart before adding the item

string

default:"false"

Set to true for faster response with potentially cached data

Response

Returns the updated shopping cart.

Response Fields

string

Unique identifier for the cart

array

Array of items in the cart

Show Line Item Object

string

Unique identifier for the line item

string

Product SKU

string

Base product SKU (parent product)

number

Quantity of the item

string

Product description

object

Unit price

object

Total price for this line item (price × quantity)

object

Product image

boolean

Whether this item requires shipping

object

Subtotal before shipping and tax

object

Shipping cost (if shipping info has been set)

object

Tax amount

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'

const response = await fetch('https://api.firmly.work/api/v1/domains/staging.luma.gift/cart/line-items/WS12-XS-Orange/quantity/1', {
  method: 'POST',
  headers: {
    'x-firmly-authorization': 'YOUR_TOKEN'
  }
});

const cart = await response.json();

import requests

response = requests.post(
    'https://api.firmly.work/api/v1/domains/staging.luma.gift/cart/line-items/WS12-XS-Orange/quantity/1',
    headers={
        'x-firmly-authorization': 'YOUR_TOKEN'
    }
)

cart = response.json()

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

⌘I

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'

const response = await fetch('https://api.firmly.work/api/v1/domains/staging.luma.gift/cart/line-items/WS12-XS-Orange/quantity/1', {
  method: 'POST',
  headers: {
    'x-firmly-authorization': 'YOUR_TOKEN'
  }
});

const cart = await response.json();

import requests

response = requests.post(
    'https://api.firmly.work/api/v1/domains/staging.luma.gift/cart/line-items/WS12-XS-Orange/quantity/1',
    headers={
        'x-firmly-authorization': 'YOUR_TOKEN'
    }
)

cart = response.json()

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

Home

Core Concepts

Implementation Guides

Ask Agent SDK

API Reference

firmly Connect

Resources

Overview

Authentication

Path Parameters

Request Body

Query Parameters

Response

Response Fields

Error Responses

400 Bad Request

404 Not Found

409 Conflict

422 Unprocessable Entity

​Overview

​Authentication

​Path Parameters

​Request Body

​Query Parameters

​Response

​Response Fields

​Error Responses

​400 Bad Request

​404 Not Found

​409 Conflict

​422 Unprocessable Entity

Overview

Authentication

Path Parameters

Request Body

Query Parameters

Response

Response Fields

Error Responses

400 Bad Request

404 Not Found

409 Conflict

422 Unprocessable Entity