Commerce (Orders)

The Commerce module handles the transaction layer — orders, carts, payments, discounts, and affiliates. An agent can manage the entire order lifecycle from cart to fulfillment.

Order

Orders represent purchase transactions — what was bought, by whom, payment status, and fulfillment tracking.

Field	Type	Description
id / uuid	ID!	Unique identifiers
order_number	String	Human-readable order number
status	String	Order status (draft, confirmed, etc.)
fulfillment_status	String	Fulfillment state
total_gross_amount	Float	Total including tax
total_net_amount	Float	Total excluding tax
discount_amount	Float	Discount applied
currency	String	Currency code
customer_note	String	Note from customer
people	People	Customer / contact
items	[OrderItem!]	Line items (paginated)
shipping_address	Address	Shipping address
custom_fields	[CustomField!]	Custom data
files	[Filesystem!]	Attached files

OrderItem

Field	Type	Description
id	ID!	Unique identifier
product_name	String	Product name at time of purchase
product_sku	String	SKU at time of purchase
quantity	Int	Quantity ordered
unit_price_gross_amount	Float	Unit price including tax
variant	Variant	Linked variant
quantity_fulfilled	Int	Quantity fulfilled so far

# List orders
query {
  orders(first: 20, orderBy: [{ column: CREATED_AT, order: DESC }]) {
    data {
      id order_number status fulfillment_status
      total_gross_amount currency customer_note
      people { name email }
      items(first: 50) {
        data { product_name product_sku quantity unit_price_gross_amount }
      }
      shipping_address { address city state zip country }
      created_at
    }
    paginatorInfo { total hasMorePages }
  }
}

# Create a draft order
mutation {
  createDraftOrder(input: {
    people_id: 1
    items: [{ variant_id: 1, quantity: 2 }]
    shipping_address: { address: "123 Main St", city: "New York", state: "NY", zip: "10001", country: "US" }
    customer_note: "Please gift wrap"
  }) {
    id order_number status total_gross_amount
  }
}

# Update order status
mutation {
  updateOrder(id: 1, input: { status: "confirmed", fulfillment_status: "processing" }) {
    id status fulfillment_status
  }
}

Cart

Field	Type	Description
id	ID!	Cart identifier
items	[CartItem!]	Items in the cart
discounts	[CartDiscount!]	Applied discounts
subtotal	Float	Subtotal before discounts
total	Float	Final total

# Add to cart
mutation {
  addToCart(input: { variant_id: 1, quantity: 2 }) {
    id
    items { name price quantity }
    subtotal total
  }
}

# Apply discount code
mutation {
  cartDiscountCodesUpdate(codes: ["SAVE20"]) {
    id discounts { code amount } total
  }
}

# Create order from cart
mutation {
  createOrderFromCart(input: {
    cart_id: 1
    shipping_address: { address: "123 Main St", city: "New York", state: "NY", zip: "10001", country: "US" }
  }) {
    id order_number total_gross_amount
  }
}

Payments

# Generate payment intent
mutation {
  generateOrderPaymentIntent(order_id: 1) {
    paymentIntent
    message
  }
}

# Process payment
mutation {
  processOrderPayment(input: { order_id: 1, payment_method_id: "pm_xxx" }) {
    status message
    order { id status }
  }
}

Inventory Messaging