ShoppingCartV2 schema

The ShoppingCartV2 object is the canonical cart payload returned by most cart-mutation endpoints. It contains line items, shipments, addons, pricing, and metadata.

​​ ShoppingCartV2

The main cart object containing all cart information.

• cart_id (string, required) — Unique cart identifier (UUID).

• platform_id (string, required) — Identifier of the merchant’s underlying commerce platform. The literal value varies by merchant.

• shop_id (string, required) — Shop identifier (merchant domain).

• schema_version (string, required) — The schema version (“2.0”).

• line_items (array, required) — Array of cart items. See LineItem.

• total (Amount, required) — Final total including all costs.

• urls (object, required) — Post-order redirect URLs. The object is always present; its members are optional.

  properties

  • thank_you_page (string) — Order confirmation (“thank you”) page URL.
  • order_status_page (string) — Order status page URL.

• display_name (string) — Merchant display name.

• cart_status (string) — Current cart status. One of active, pending, submitted, item_not_shippable, checkout_blocked.

• shipments (array) — Multi-shipment array for grouped fulfillment. See Shipment.

• shipping_method_options (array) — Cart-level shipping options the buyer can choose from. Each is a ShippingMethod.

• shipping_method (object) — The selected cart-level shipping method. See ShippingMethod.

• addons (object) — Container for addon offers and selections. See Addon schemas.

  properties

  • offers (array) — Available addon services.
  • selections (array) — Currently applied addons.

• sub_total (Amount) — Subtotal before discounts, shipping, and taxes.

• cart_discount (Amount) — Total discount amount from promotions.

• shipping_total (Amount) — Total shipping costs across all shipments.

• addon_total (Amount) — Total cost of selected addons.

• tax_total (Amount) — Total tax amount.

• fees (array) — Merchant-imposed fees (e.g. recycle, regulatory), if any. See Fee.

• fee_total (Amount) — Total of all fees.

• shipping_info (ShippingInfo) — Buyer shipping address — see Common types → ShippingInfo.

• billing_info (AddressInfo) — Buyer billing address — see Common types → Address.

• coupons (array) — Applied promotional codes.

• notices (array) — Refresh-related notices about items, promotions, shipping, or prices. See CartNotice.

• payment_summary (object) — Summary of the payment method associated with the cart (for example, masked card or wallet details).

• platform_order_number (string) — Order number assigned by the merchant’s underlying commerce platform once the cart is submitted.

• custom_properties (object) — Free-form merchant- or integration-specific properties.

{
  "cart_id": "550e8400-e29b-41d4-a716-446655440000",
  "platform_id": "example_commerce",
  "shop_id": "staging.luma.gift",
  "schema_version": "2.0",
  "display_name": "Luma Gift Store",
  "cart_status": "active",
  "line_items": [],
  "shipments": [],
  "shipping_method_options": [
    {
      "id": "standard",
      "description": "Standard Shipping",
      "price": { "value": 5.99, "currency": "USD", "number": 599 },
      "estimated_delivery": "3-5 business days"
    }
  ],
  "addons": {
    "offers": [],
    "selections": []
  },
  "sub_total": { "value": 99.99, "currency": "USD", "number": 9999 },
  "cart_discount": { "value": 10.00, "currency": "USD", "number": 1000 },
  "shipping_total": { "value": 5.99, "currency": "USD", "number": 599 },
  "addon_total": { "value": 4.99, "currency": "USD", "number": 499 },
  "tax_total": { "value": 8.25, "currency": "USD", "number": 825 },
  "fees": [{ "description": "Recycle fee", "value": 2.00, "currency": "USD", "number": 200 }],
  "fee_total": { "value": 2.00, "currency": "USD", "number": 200 },
  "total": { "value": 111.22, "currency": "USD", "number": 11122 },
  "coupons": ["SAVE10"],
  "notices": [
    {
      "code": "PRICE_INCREASED",
      "severity": "warning",
      "item_id": "8f3a2b1c-1d2e-4a5b-9c8d-1a2b3c4d5e6f",
      "details": {
        "description": "Price changed since the item was added",
        "old_value": { "value": 24.99, "currency": "USD" },
        "new_value": { "value": 29.99, "currency": "USD" }
      }
    }
  ],
  "urls": {
    "thank_you_page": "https://staging.luma.gift/checkout/thank-you",
    "order_status_page": "https://staging.luma.gift/orders/status"
  }
}

​​ CartNotice

A refresh-related notice surfaced on ShoppingCartV2.notices[] when an item, promotion, shipping option, or price changes after the cart was built.

• code (string, required) — Notice code. Enum values:

  • ITEM_NOT_SHIPPABLE
  • ITEM_OUT_OF_STOCK
  • PROMO_EXPIRED
  • PROMO_NOT_APPLICABLE
  • SHIPPING_NOT_AVAILABLE
  • PRICE_INCREASED
  • PRICE_DECREASED

• severity (string, required) — Notice severity. One of warning, info, error.

• item_id (string) — Identifier of the line item the notice relates to, when applicable.

• details (object) — Additional context for the notice.

  properties

  • description (string) — Human-readable description.
  • promo_code (string) — Related promotion code, for promo notices.
  • old_value (Amount) — Previous value, for price-change notices.
  • new_value (Amount) — New value, for price-change notices.
  • reason (string) — Machine-readable reason, when provided.

​​ Related

• Schemas overview
• API Reference
• Errors & Conventions