Skip to main content
PUT
https://api.firmly.work
/
api
/
v2
/
domains
/
{domain}
/
cart
/
line-items
/
{lineItemId}
Update Line Item
curl --request PUT \
  --url https://api.firmly.work/api/v2/domains/{domain}/cart/line-items/{lineItemId} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "quantity": 123
}
'
{
  "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",
      "sku": "MH07-XS-Gray",
      "variant_id": "MH07-XS-Gray",
      "description": "Hero Hoodie - Gray XS",
      "quantity": 2,
      "price": {
        "currency": "USD",
        "value": 54.00,
        "number": 5400,
        "symbol": "$"
      },
      "line_price": {
        "currency": "USD",
        "value": 108.00,
        "number": 10800,
        "symbol": "$"
      }
    }
  ],
  "shipments": [
    {
      "shipment_id": "ship_01H2XVBR8C8JS5MQSFPJ8HF9SC",
      "line_item_ids": ["item_01H2XVBR8C8JS5MQSFPJ8HF9SB"],
      "fulfillment_type": {
        "id": "SHIP_TO_ADDRESS",
        "name": "Ship to Address",
        "description": "Standard shipping to customer address"
      },
      "shipping_method": {
        "id": "STANDARD_GROUND",
        "description": "Standard Ground Shipping",
        "price": {
          "currency": "USD",
          "value": 49.99,
          "number": 4999,
          "symbol": "$"
        },
        "estimated_delivery": "5-7 business days"
      }
    }
  ],
  "addons": {
    "offers": [
      {
        "addon_id": "bulk_discount",
        "display": {
          "name": "Bulk Purchase Discount",
          "description": "Save 5% on orders with 2+ items"
        },
        "scope": "CART",
        "price": {
          "currency": "USD",
          "value": -130.00,
          "number": -13000,
          "symbol": "$"
        }
      }
    ],
    "selections": []
  },
  "sub_total": {
    "currency": "USD",
    "value": 108.00,
    "number": 10800,
    "symbol": "$"
  },
  "shipping_total": {
    "currency": "USD",
    "value": 49.99,
    "number": 4999,
    "symbol": "$"
  },
  "tax_total": {
    "currency": "USD",
    "value": 10.80,
    "number": 1080,
    "symbol": "$"
  },
  "addon_total": {
    "currency": "USD",
    "value": 0.00,
    "number": 0,
    "symbol": "$"
  },
  "total": {
    "currency": "USD",
    "value": 168.79,
    "number": 16879,
    "symbol": "$"
  },
  "schema_version": "2.0"
}

​
Overview

The Update Line Item endpoint modifies the quantity of an existing product in the cart. Key features include:
  • Quantity Modification: Update item quantities or remove items by setting quantity to 0
  • Automatic Recalculation: All pricing and shipment information is automatically updated
  • Shipment Preservation: Items remain in their assigned shipments after quantity updates
  • Addon Adjustment: Addon offers may change based on new cart totals

​
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)
​
lineItemId
string
required
Unique identifier of the line item to update

​
Request Body

​
quantity
number
required
New quantity for the line item (minimum 0, set to 0 to remove the item)

​
Response

Returns the complete updated shopping cart. See Get Cart for full response schema.

​
Update Behavior:

  • Quantity > 0: Updates the item quantity and recalculates pricing
  • Quantity = 0: Removes the item from the cart and its shipment
  • Empty Shipments: Shipments with no remaining items are automatically removed

​
Code Examples

curl --request PUT \
  --url https://api.firmly.work/api/v2/domains/staging.luma.gift/cart/line-items/item_01H2XVBR8C8JS5MQSFPJ8HF9SB \
  --header 'Content-Type: application/json' \
  --header 'x-firmly-authorization: YOUR_TOKEN' \
  --data '{
    "quantity": 2
  }'

​
Example Scenarios

​
Increase Quantity

Update an item from quantity 1 to 2: 
// Request
{
  "quantity": 2
}

// Response shows updated quantity and recalculated totals
{
  "line_items": [
    {
      "line_item_id": "item_01H2XVBR8C8JS5MQSFPJ8HF9SB",
      "quantity": 2,
      "price": {
        "value": 54.00
      },
      "line_price": {
        "value": 108.00
      }
    }
  ],
  "sub_total": {
    "value": 108.00
  }
}

​
Remove Item

Set quantity to 0 to remove an item: 
// Request
{
  "quantity": 0
}

// Response shows item removed from cart and shipments
{
  "line_items": [],
  "shipments": [],
  "sub_total": {
    "value": 0
  }
}

{
  "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",
      "sku": "MH07-XS-Gray",
      "variant_id": "MH07-XS-Gray",
      "description": "Hero Hoodie - Gray XS",
      "quantity": 2,
      "price": {
        "currency": "USD",
        "value": 54.00,
        "number": 5400,
        "symbol": "$"
      },
      "line_price": {
        "currency": "USD",
        "value": 108.00,
        "number": 10800,
        "symbol": "$"
      }
    }
  ],
  "shipments": [
    {
      "shipment_id": "ship_01H2XVBR8C8JS5MQSFPJ8HF9SC",
      "line_item_ids": ["item_01H2XVBR8C8JS5MQSFPJ8HF9SB"],
      "fulfillment_type": {
        "id": "SHIP_TO_ADDRESS",
        "name": "Ship to Address",
        "description": "Standard shipping to customer address"
      },
      "shipping_method": {
        "id": "STANDARD_GROUND",
        "description": "Standard Ground Shipping",
        "price": {
          "currency": "USD",
          "value": 49.99,
          "number": 4999,
          "symbol": "$"
        },
        "estimated_delivery": "5-7 business days"
      }
    }
  ],
  "addons": {
    "offers": [
      {
        "addon_id": "bulk_discount",
        "display": {
          "name": "Bulk Purchase Discount",
          "description": "Save 5% on orders with 2+ items"
        },
        "scope": "CART",
        "price": {
          "currency": "USD",
          "value": -130.00,
          "number": -13000,
          "symbol": "$"
        }
      }
    ],
    "selections": []
  },
  "sub_total": {
    "currency": "USD",
    "value": 108.00,
    "number": 10800,
    "symbol": "$"
  },
  "shipping_total": {
    "currency": "USD",
    "value": 49.99,
    "number": 4999,
    "symbol": "$"
  },
  "tax_total": {
    "currency": "USD",
    "value": 10.80,
    "number": 1080,
    "symbol": "$"
  },
  "addon_total": {
    "currency": "USD",
    "value": 0.00,
    "number": 0,
    "symbol": "$"
  },
  "total": {
    "currency": "USD",
    "value": 168.79,
    "number": 16879,
    "symbol": "$"
  },
  "schema_version": "2.0"
}

​
Error Responses

Invalid request format or parameters
{
  "code": 400,
  "error": "ErrorInvalidInputBody",
  "description": "Invalid request format"
}
Line item does not exist in the cart
{
  "code": 404,
  "error": "ErrorLineItemNotFound",
  "description": "Line item does not exist"
}
Invalid quantity or processing error
{
  "code": 422,
  "error": "ErrorInvalidQuantity",
  "description": "Quantity must be non-negative"
}

​
Update Behavior

The Update Line Item endpoint maintains cart integrity:
  • Shipment Assignment: Items remain in their assigned shipments after updates
  • Empty Shipment Cleanup: Shipments with no items are automatically removed
  • Addon Recalculation: Available addons may change based on new cart value
  • Price Updates: All totals are recalculated including shipping and tax

​
Implementation Notes

The update operation preserves the cart structure:
  1. Item Location: The item remains in its current shipment
  2. Shipment Options: Fulfillment and shipping options are preserved
  3. Addon State: Selected addons remain unless they become invalid
  4. Session Continuity: Cart session and authentication remain active