Update Line Item - Firmly API

PUT

api

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

400 Bad Request

Invalid request format or parameters

{
  "code": 400,
  "error": "ErrorInvalidInputBody",
  "description": "Invalid request format"
}

404 Not Found

Line item does not exist in the cart

{
  "code": 404,
  "error": "ErrorLineItemNotFound",
  "description": "Line item does not exist"
}

422 Unprocessable Entity

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:

Item Location: The item remains in its current shipment
Shipment Options: Fulfillment and shipping options are preserved
Addon State: Selected addons remain unless they become invalid
Session Continuity: Cart session and authentication remain active

Get Cart - View current cart state
Add Line Item - Add new items to cart
Clear Cart - Empty the entire cart

Clear CartRemoves all line items from the cart, returning an empty cart

⌘I

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

​Authentication

​Path Parameters

​Request Body

​Response

​Update Behavior:

​Code Examples

​Example Scenarios

​Increase Quantity

​Remove Item

​Error Responses

​Update Behavior

​Implementation Notes

​Related Endpoints

Overview

Authentication

Path Parameters

Request Body

Response

Update Behavior:

Code Examples

Example Scenarios

Increase Quantity

Remove Item

Error Responses

Update Behavior

Implementation Notes

Related Endpoints