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

Schemas

This section is the canonical reference for every object Firmly’s API returns or accepts. Each schema is on its own page so you can link to it directly.

If you’re looking for the endpoints that return these schemas, see the API Reference. If you’re looking for how the API behaves (errors, idempotency, pagination), see Concepts and Errors & Conventions.

​​ Core objects

ShoppingCartV2 The main cart object returned by most cart-mutation endpoints. LineItem An individual item within a cart. Shipment Groups line items by fulfillment when items ship separately.

​​ Fulfillment

Fulfillment schemas FulfillmentType, ShippingMethod, and PickupLocation — how an order is delivered, shipped, or picked up in store.

​​ Add-ons

Addon schemas AddonsContainer, AddonOffer, AddonSelection — warranties, gift wrap, gift messages, protection plans.

​​ Primitive types

Common types Amount, Address, TimeSlot — primitive types referenced throughout the other schemas.

​​ Requests and errors

Request schemas Request bodies for cart, fulfillment, addon, and promotion operations. Error response The shape of error responses. For the full error code catalog and recovery patterns, see Errors & Conventions.

​​ Schema conventions

  • Field names are snake_case across the cart schemas (e.g., line_item_id, cart_status, add_to_cart_ref) — see each schema page for the exact fields
  • Money values carry a decimal amount in value (e.g. 54.00), integer cents in number (e.g. 5400), plus symbol and currency. Display uses value; do arithmetic on number — see Common types → Amount
  • Required vs optional fields are marked on each schema page
  • Field-level descriptions match what the API actually returns (validated against QA traffic)

​​ Where each schema is returned

Schema Endpoints that return it
ShoppingCartV2 Every cart-mutation endpoint, GET /cart
LineItem Nested inside ShoppingCartV2.line_items[]
Shipment Nested inside ShoppingCartV2.shipments[]
FulfillmentType Nested inside Shipment.fulfillment_type
ShippingMethod Returned on the cart in ShoppingCartV2.shipping_method_options[] and shipping_method; also per-shipment in Shipment.shipping_method_options[]
PickupLocation Returned by get-availability when BOPIS is supported
CartNotice Nested inside ShoppingCartV2.notices[]
AddonsContainer Nested inside ShoppingCartV2.addons
AddonOffer Returned by addon-related endpoints
AddonSelection Nested inside AddonsContainer.selections[]; also sent as the request body to addon selection endpoints
Amount Used throughout for all monetary values
Address Used in shipping and billing info
TimeSlot Used in scheduled-delivery contexts
Error response Returned on any non-2xx HTTP response