Request schemas

Schemas for the request bodies sent to Firmly’s mutation endpoints. For the response shape, see the response schemas — all cart-mutation endpoints return a cart object.

​​ Cart Operations

​​ AddLineItemRequest

• add_to_cart_ref (object, required) — Product reference

  properties

  • variant_id (string, required) — Product variant ID
  • product_id (string) — Product ID
  • variant_handles (array) — Variant handle identifiers

• quantity (integer, required) — Quantity to add (minimum: 1)

​​ UpdateLineItemRequest

• quantity (integer, required) — New quantity (0 to remove)

​​ Fulfillment

​​ SetFulfillmentTypeRequest

• shipment_id (string, required) — Target shipment ID

• fulfillment_type (string, required) — New fulfillment type enum

• location_id (string) — Required for PICKUP_IN_STORE

​​ SetShippingMethodRequest

• shipment_id (string, required) — Target shipment ID

• shipping_method_id (string, required) — Selected method ID

​​ Addons

​​ SetAddonSelectionsRequest

• selections (array, required) — Array of addon selections
  properties

  • addon_id (string, required) — Addon to select
  • selected_line_item_ids (array) — Items to apply to
  • selected_child_ids (array) — Child addon selections

​​ Promotions

​​ AddPromoCodesRequest

• promo_codes (array, required) — Array of 1–10 promotional codes to apply

​​ Related

• Schemas overview
• API Reference
• Errors & Conventions