Docs
Firmly Agentic Commerce
Docs
Set theme to dark (⇧+D)
  1. Docs
  2. Resources
  3. Schemas
  4. LineItem schema

LineItem schema

Each item in a cart is represented as a LineItem. Line items have a stable line_item_id (a UUID) that you use for subsequent update or remove calls.

​​ LineItem

Individual product item in the cart.

  • line_item_id (string, required) — Unique item identifier within the cart (UUID). Use this value for subsequent update and remove calls.

  • sku (string, required) — Stock keeping unit for the selected variant.

  • quantity (integer, required) — Item quantity.

  • price (Amount, required) — Unit price of the item. See Common types → Amount.

  • msrp (Amount, required) — Manufacturer’s suggested retail price (unit).

  • line_price (Amount, required) — Extended price for the line (unit price times quantity).

  • image (ImageObject, required) — Primary product image for the line.

    properties
    • url (string, required) — Image URL (absolute http(s) URL).
    • alt (string) — Alternative text.
    • type (string) — Image size hint. One of preview, small, medium, large, default, video. Defaults to default.
    • aspect_ratio (number) — Width-to-height ratio.
    • width (integer) — Intrinsic width in pixels.
    • height (integer) — Intrinsic height in pixels.
    • position (integer) — Ordering position when multiple images exist.
    • srcset (array) — Additional image renditions (each the same shape as the base image).

  • base_sku (string) — SKU of the parent product the variant belongs to.

  • description (string) — Human-readable product description.

  • variant_description (string) — Human-readable variant description (for example, “XS / Orange”).

  • variant_handles (array) — Selected variant option handles.

  • universal_product_id (string) — Universal product identifier (for example, a GTIN/UPC), when the merchant provides one.

  • discount (Amount) — Discount applied to the unit price.

  • line_discount (Amount) — Discount applied to the line (unit times quantity).

  • discounts (array) — Named discounts applied to the line.

    properties
    • code (string, required) — Discount code.
    • description (string, required) — Human-readable discount description.

  • line_item_tax (Amount) — Tax attributed to the line.

  • requires_shipping (boolean) — Whether the item requires shipping. Defaults to true.

  • requires_scheduled_delivery (boolean) — Whether the item requires a scheduled-delivery selection.

  • taxable (boolean) — Whether the item is taxable.

  • fixed_quantity (boolean) — When true, the quantity cannot be changed.

  • parent_line_item_id (string) — Line item ID (UUID) of the parent line, for nested/bundled items.

  • platform_line_item_id (string) — Identifier for the line item in the merchant’s underlying commerce platform.

  • extended_attributes (object) — Additional merchant-specific attributes for the line.

  • properties (object) — Free-form line-level properties (for example, personalization inputs).

  • messages (array) — Display messages attached to the line.

    properties
    • text (string, required) — Message text.
    • type (string) — Message category. One of promotion, stock, badge, banner, shipping, urgency, info.


{
  "line_item_id": "8f3a2b1c-1d2e-4a5b-9c8d-1a2b3c4d5e6f",
  "sku": "WS12-XS-Orange",
  "base_sku": "WS12",
  "description": "Radiant Tee",
  "variant_description": "XS / Orange",
  "quantity": 2,
  "price": {
    "value": 29.99,
    "currency": "USD",
    "number": 2999,
    "symbol": "$"
  },
  "msrp": {
    "value": 34.00,
    "currency": "USD",
    "number": 3400
  },
  "line_price": {
    "value": 59.98,
    "currency": "USD",
    "number": 5998
  },
  "line_discount": {
    "value": 8.02,
    "currency": "USD",
    "number": 802
  },
  "image": {
    "url": "https://staging.luma.gift/products/radiant-tee.jpg",
    "alt": "Radiant Tee",
    "type": "default"
  },
  "requires_shipping": true,
  "platform_line_item_id": "1452"

}