Add Line Item - Firmly API

POST

api

domains

{domain}

cart

line-items

Add Line Item

curl --request POST \
  --url https://api.firmly.work/api/v2/domains/{domain}/cart/line-items \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "add_to_cart_ref": {},
  "quantity": 123
}
'

{
  "line_items": [
    {
      "line_item_id": "new-item-12345",
      "platform_line_item_id": "0",
      "sku": "WS12-XS-Orange",
      "variant_description": "Color: Orange, Size: XS",
      "description": "Radiant Tee",
      "base_sku": "WS12",
      "quantity": 1,
      "price": {
        "currency": "USD",
        "value": 22.00,
        "number": 2200,
        "symbol": "$"
      },
      "line_price": {
        "currency": "USD",
        "value": 22.00,
        "number": 2200,
        "symbol": "$"
      },
      "msrp": {
        "currency": "USD",
        "value": 22.00,
        "number": 2200,
        "symbol": "$"
      },
      "image": {
        "url": "https://cdn.staging.luma.gift/product/radiant-tee-orange.jpg",
        "alt": "Radiant Tee in Orange",
        "type": "default"
      },
      "requires_shipping": true
    }
  ],
  "shipments": [
    {
      "shipment_id": "auto-generated-shipment-1",
      "line_item_ids": ["new-item-12345"],
      "fulfillment_type": {
        "id": "SHIP_TO_ADDRESS",
        "name": "Ship to Address",
        "description": "Standard shipping to your address"
      },
      "fulfillment_type_options": [
        {
          "id": "SHIP_TO_ADDRESS",
          "name": "Ship to Address", 
          "description": "Standard shipping to your address"
        },
        {
          "id": "SCHEDULED_DELIVERY",
          "name": "Scheduled Delivery",
          "description": "Delivery scheduled for a specific date"
        }
      ],
      "shipping_method_options": [
        {
          "id": "STANDARD_SHIPPING",
          "description": "Standard Shipping",
          "price": {
            "currency": "USD",
            "value": 50,
            "number": 5000,
            "symbol": "$"
          },
          "estimated_delivery": "5-7 business days"
        },
        {
          "id": "PREMIUM_SHIPPING",
          "description": "Premium Delivery",
          "price": {
            "currency": "USD",
            "value": 100,
            "number": 10000,
            "symbol": "$"
          },
          "estimated_delivery": "2-3 business days"
        }
      ],
      "shipping_method": {
        "id": "STANDARD_VENDOR_SHIPPING",
        "description": "Standard Shipping (O)",
        "price": {"value": 0, "currency": "USD", "number": 0, "symbol": "$"},
        "estimated_delivery": "Varies by vendor"
      },
      "notes": ""
    }
  ],
  "sub_total": {
    "currency": "USD",
    "value": 1299.99,
    "number": 129999,
    "symbol": "$"
  },
  "shipping_total": {
    "currency": "USD",
    "value": 0,
    "number": 0,
    "symbol": "$"
  },
  "tax_total": {
    "currency": "USD",
    "value": 0,
    "number": 0,
    "symbol": "$"
  },
  "total": {
    "currency": "USD",
    "value": 1299.99,
    "number": 129999,
    "symbol": "$"
  },
  "addons": {
    "offers": [
      {
        "addon_id": "protection-new-item-12345",
        "display": {
          "name": "Product Protection Plan"
        },
        "price": {
          "currency": "USD",
          "value": 0,
          "number": 0,
          "symbol": "$"
        },
        "scope": "ITEM",
        "coverage_mode": "PER_ITEM",
        "eligible_line_item_ids": [
          "new-item-12345"
        ],
        "child_offers": [
          {
            "addon_id": "A0-FURN-2y",
            "display": {
              "name": "2 Year Protection"
            },
            "scope": "INHERIT",
            "coverage_mode": "PER_ITEM",
            "eligible_line_item_ids": [
              "new-item-12345"
            ],
            "price": {
              "currency": "USD",
              "value": 149.99,
              "number": 14999,
              "symbol": "$"
            }
          },
          {
            "addon_id": "A0-FURN-3y",
            "display": {
              "name": "3 Year Protection"
            },
            "scope": "INHERIT",
            "coverage_mode": "PER_ITEM",
            "eligible_line_item_ids": [
              "new-item-12345"
            ],
            "price": {
              "currency": "USD",
              "value": 199.99,
              "number": 19999,
              "symbol": "$"
            }
          }
        ]
      }
    ],
    "selections": []
  },
  "addon_total": {
    "currency": "USD",
    "value": 0,
    "number": 0,
    "symbol": "$"
  },
  "schema_version": "2.0"
}

Overview

The Add Line Item endpoint adds a new product to the shopping cart with these features:

Automatic Shipment Assignment: Items are automatically grouped into shipments based on their fulfillment requirements
Catalog Integration: Uses add_to_cart_ref object directly from catalog API responses
Variant Support: Handles configurable products with variant handles
Cart Creation: Automatically creates a new cart if one doesn’t exist
Optional Cart Clearing: Can clear existing cart before adding new item

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)

Query Parameters

flush_cart

boolean

default:"false"

When true, clears the cart before adding the new item

Request Body

add_to_cart_ref

object

required

Product reference from catalog API containing variant informationProperties:

variant_id (string, required): Product variant identifier
product_id (string, optional): Parent product identifier
variant_handles (array, optional): Array of variant configuration handles (e.g., ["color:blue", "size:large"])

quantity

number

required

Quantity to add (minimum 1)

Response

Returns the complete shopping cart including the newly added item. See Get Cart for full response schema

Key Response Features:

shipments

array

Shows automatic shipment assignment for the new item

addons.offers

array

Available addon services for the updated cart

schema_version

string

Indicates the cart schema version

Code Examples

curl --request POST \
  --url https://api.firmly.work/api/v2/domains/staging.luma.gift/cart/line-items \
  --header 'Content-Type: application/json' \
  --header 'x-firmly-authorization: YOUR_TOKEN' \
  --data '{
    "add_to_cart_ref": {
      "variant_id": "WS12-XS-Orange"
    },
    "quantity": 1
  }'

Advanced Examples

With Variant Handles

For configurable products with multiple options:

{
  "add_to_cart_ref": {
    "variant_id": "MH07-XS-Gray",
    "variant_handles": ["color:gray", "size:xs"]
  },
  "quantity": 1
}

Clear Cart First

To replace cart contents with a new item:

curl --request POST \
  --url 'https://api.firmly.work/api/v2/domains/staging.luma.gift/cart/line-items?flush_cart=true' \
  --header 'Content-Type: application/json' \
  --header 'x-firmly-authorization: YOUR_TOKEN' \
  --data '{
    "add_to_cart_ref": {
      "variant_id": "WT09-XS-White"
    },
    "quantity": 2
  }'

Catalog Integration

The add_to_cart_ref object should be passed directly from catalog API responses:

{
  "products": [
    {
      "product_id": "WS12",
      "variants": [
        {
          "add_to_cart_ref": {
            "variant_id": "WS12-XS-Orange",
            "variant_handles": ["color:orange", "size:xs"]
          }
        }
      ]
    }
  ]
}

{
  "line_items": [
    {
      "line_item_id": "new-item-12345",
      "platform_line_item_id": "0",
      "sku": "WS12-XS-Orange",
      "variant_description": "Color: Orange, Size: XS",
      "description": "Radiant Tee",
      "base_sku": "WS12",
      "quantity": 1,
      "price": {
        "currency": "USD",
        "value": 22.00,
        "number": 2200,
        "symbol": "$"
      },
      "line_price": {
        "currency": "USD",
        "value": 22.00,
        "number": 2200,
        "symbol": "$"
      },
      "msrp": {
        "currency": "USD",
        "value": 22.00,
        "number": 2200,
        "symbol": "$"
      },
      "image": {
        "url": "https://cdn.staging.luma.gift/product/radiant-tee-orange.jpg",
        "alt": "Radiant Tee in Orange",
        "type": "default"
      },
      "requires_shipping": true
    }
  ],
  "shipments": [
    {
      "shipment_id": "auto-generated-shipment-1",
      "line_item_ids": ["new-item-12345"],
      "fulfillment_type": {
        "id": "SHIP_TO_ADDRESS",
        "name": "Ship to Address",
        "description": "Standard shipping to your address"
      },
      "fulfillment_type_options": [
        {
          "id": "SHIP_TO_ADDRESS",
          "name": "Ship to Address", 
          "description": "Standard shipping to your address"
        },
        {
          "id": "SCHEDULED_DELIVERY",
          "name": "Scheduled Delivery",
          "description": "Delivery scheduled for a specific date"
        }
      ],
      "shipping_method_options": [
        {
          "id": "STANDARD_SHIPPING",
          "description": "Standard Shipping",
          "price": {
            "currency": "USD",
            "value": 50,
            "number": 5000,
            "symbol": "$"
          },
          "estimated_delivery": "5-7 business days"
        },
        {
          "id": "PREMIUM_SHIPPING",
          "description": "Premium Delivery",
          "price": {
            "currency": "USD",
            "value": 100,
            "number": 10000,
            "symbol": "$"
          },
          "estimated_delivery": "2-3 business days"
        }
      ],
      "shipping_method": {
        "id": "STANDARD_VENDOR_SHIPPING",
        "description": "Standard Shipping (O)",
        "price": {"value": 0, "currency": "USD", "number": 0, "symbol": "$"},
        "estimated_delivery": "Varies by vendor"
      },
      "notes": ""
    }
  ],
  "sub_total": {
    "currency": "USD",
    "value": 1299.99,
    "number": 129999,
    "symbol": "$"
  },
  "shipping_total": {
    "currency": "USD",
    "value": 0,
    "number": 0,
    "symbol": "$"
  },
  "tax_total": {
    "currency": "USD",
    "value": 0,
    "number": 0,
    "symbol": "$"
  },
  "total": {
    "currency": "USD",
    "value": 1299.99,
    "number": 129999,
    "symbol": "$"
  },
  "addons": {
    "offers": [
      {
        "addon_id": "protection-new-item-12345",
        "display": {
          "name": "Product Protection Plan"
        },
        "price": {
          "currency": "USD",
          "value": 0,
          "number": 0,
          "symbol": "$"
        },
        "scope": "ITEM",
        "coverage_mode": "PER_ITEM",
        "eligible_line_item_ids": [
          "new-item-12345"
        ],
        "child_offers": [
          {
            "addon_id": "A0-FURN-2y",
            "display": {
              "name": "2 Year Protection"
            },
            "scope": "INHERIT",
            "coverage_mode": "PER_ITEM",
            "eligible_line_item_ids": [
              "new-item-12345"
            ],
            "price": {
              "currency": "USD",
              "value": 149.99,
              "number": 14999,
              "symbol": "$"
            }
          },
          {
            "addon_id": "A0-FURN-3y",
            "display": {
              "name": "3 Year Protection"
            },
            "scope": "INHERIT",
            "coverage_mode": "PER_ITEM",
            "eligible_line_item_ids": [
              "new-item-12345"
            ],
            "price": {
              "currency": "USD",
              "value": 199.99,
              "number": 19999,
              "symbol": "$"
            }
          }
        ]
      }
    ],
    "selections": []
  },
  "addon_total": {
    "currency": "USD",
    "value": 0,
    "number": 0,
    "symbol": "$"
  },
  "schema_version": "2.0"
}

Error Responses

400 Bad Request

Invalid request format or missing required parameters

{
  "code": 400,
  "error": "ErrorInvalidInputBody",
  "description": "Request body validation failed"
}

404 Not Found

Product variant not found in catalog

{
  "code": 404,
  "error": "ErrorProductNotFound",
  "description": "Product variant was not found"
}

409 Conflict

Product is not supported for cart operations

{
  "code": 400,
  "error": "ErrorProductNotSupported",
  "description": "Product is not supported for this operation"
}

422 Unprocessable Entity

Various processing errors

{
  "code": 400,
  "error": "ErrorNotEnoughStock",
  "description": "Insufficient stock for requested quantity"
}

Automatic Shipment Assignment

When adding items to the cart, the system automatically:

Groups compatible items: Items with similar fulfillment requirements are grouped together
Creates new shipments: Items with different requirements get separate shipments
Inherits options: New shipments inherit available fulfillment and shipping options

Example: Mixed Cart

Adding a large sofa (requires scheduled delivery) to a cart with small accessories (standard shipping) creates separate shipments:

{
  "shipments": [
    {
      "shipment_id": "furniture-shipment",
      "line_item_ids": ["hoodie-item"],
      "fulfillment_type": {"id": "SCHEDULED_DELIVERY"}
    },
    {
      "shipment_id": "accessories-shipment", 
      "line_item_ids": ["tee-item", "tank-item"],
      "fulfillment_type": {"id": "SHIP_TO_ADDRESS"}
    }
  ]
}

Get Cart - View current cart state
Update Line Item - Modify cart items
Clear Cart - Empty the cart

Update Line ItemUpdates the quantity of an existing line item in the shopping cart

⌘I

Add Line Item

curl --request POST \
  --url https://api.firmly.work/api/v2/domains/{domain}/cart/line-items \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "add_to_cart_ref": {},
  "quantity": 123
}
'

{
  "line_items": [
    {
      "line_item_id": "new-item-12345",
      "platform_line_item_id": "0",
      "sku": "WS12-XS-Orange",
      "variant_description": "Color: Orange, Size: XS",
      "description": "Radiant Tee",
      "base_sku": "WS12",
      "quantity": 1,
      "price": {
        "currency": "USD",
        "value": 22.00,
        "number": 2200,
        "symbol": "$"
      },
      "line_price": {
        "currency": "USD",
        "value": 22.00,
        "number": 2200,
        "symbol": "$"
      },
      "msrp": {
        "currency": "USD",
        "value": 22.00,
        "number": 2200,
        "symbol": "$"
      },
      "image": {
        "url": "https://cdn.staging.luma.gift/product/radiant-tee-orange.jpg",
        "alt": "Radiant Tee in Orange",
        "type": "default"
      },
      "requires_shipping": true
    }
  ],
  "shipments": [
    {
      "shipment_id": "auto-generated-shipment-1",
      "line_item_ids": ["new-item-12345"],
      "fulfillment_type": {
        "id": "SHIP_TO_ADDRESS",
        "name": "Ship to Address",
        "description": "Standard shipping to your address"
      },
      "fulfillment_type_options": [
        {
          "id": "SHIP_TO_ADDRESS",
          "name": "Ship to Address", 
          "description": "Standard shipping to your address"
        },
        {
          "id": "SCHEDULED_DELIVERY",
          "name": "Scheduled Delivery",
          "description": "Delivery scheduled for a specific date"
        }
      ],
      "shipping_method_options": [
        {
          "id": "STANDARD_SHIPPING",
          "description": "Standard Shipping",
          "price": {
            "currency": "USD",
            "value": 50,
            "number": 5000,
            "symbol": "$"
          },
          "estimated_delivery": "5-7 business days"
        },
        {
          "id": "PREMIUM_SHIPPING",
          "description": "Premium Delivery",
          "price": {
            "currency": "USD",
            "value": 100,
            "number": 10000,
            "symbol": "$"
          },
          "estimated_delivery": "2-3 business days"
        }
      ],
      "shipping_method": {
        "id": "STANDARD_VENDOR_SHIPPING",
        "description": "Standard Shipping (O)",
        "price": {"value": 0, "currency": "USD", "number": 0, "symbol": "$"},
        "estimated_delivery": "Varies by vendor"
      },
      "notes": ""
    }
  ],
  "sub_total": {
    "currency": "USD",
    "value": 1299.99,
    "number": 129999,
    "symbol": "$"
  },
  "shipping_total": {
    "currency": "USD",
    "value": 0,
    "number": 0,
    "symbol": "$"
  },
  "tax_total": {
    "currency": "USD",
    "value": 0,
    "number": 0,
    "symbol": "$"
  },
  "total": {
    "currency": "USD",
    "value": 1299.99,
    "number": 129999,
    "symbol": "$"
  },
  "addons": {
    "offers": [
      {
        "addon_id": "protection-new-item-12345",
        "display": {
          "name": "Product Protection Plan"
        },
        "price": {
          "currency": "USD",
          "value": 0,
          "number": 0,
          "symbol": "$"
        },
        "scope": "ITEM",
        "coverage_mode": "PER_ITEM",
        "eligible_line_item_ids": [
          "new-item-12345"
        ],
        "child_offers": [
          {
            "addon_id": "A0-FURN-2y",
            "display": {
              "name": "2 Year Protection"
            },
            "scope": "INHERIT",
            "coverage_mode": "PER_ITEM",
            "eligible_line_item_ids": [
              "new-item-12345"
            ],
            "price": {
              "currency": "USD",
              "value": 149.99,
              "number": 14999,
              "symbol": "$"
            }
          },
          {
            "addon_id": "A0-FURN-3y",
            "display": {
              "name": "3 Year Protection"
            },
            "scope": "INHERIT",
            "coverage_mode": "PER_ITEM",
            "eligible_line_item_ids": [
              "new-item-12345"
            ],
            "price": {
              "currency": "USD",
              "value": 199.99,
              "number": 19999,
              "symbol": "$"
            }
          }
        ]
      }
    ],
    "selections": []
  },
  "addon_total": {
    "currency": "USD",
    "value": 0,
    "number": 0,
    "symbol": "$"
  },
  "schema_version": "2.0"
}

​Overview

​Authentication

​Path Parameters

​Query Parameters

​Request Body

​Response

​Key Response Features:

​Code Examples

​Advanced Examples

​With Variant Handles

​Clear Cart First

​Catalog Integration

​Error Responses

​Automatic Shipment Assignment

​Example: Mixed Cart

​Related Endpoints

Overview

Authentication

Path Parameters

Query Parameters

Request Body

Response

Key Response Features:

Code Examples

Advanced Examples

With Variant Handles

Clear Cart First

Catalog Integration

Error Responses

Automatic Shipment Assignment

Example: Mixed Cart

Related Endpoints