Skip to main content

​
Overview

Order mutations handle the complete order lifecycle from creation through fulfillment, including status updates, fulfillment operations, and order management.

​
Create Order (Complete Cart)

Orders are created by completing a cart. This process validates inventory, captures payment, and creates the order record. 
mutation CompleteActiveCart($cartId: ID!, $paymentSessionId: ID) {
  completeActiveCart(cartId: $cartId, paymentSessionId: $paymentSessionId)
}

​
Variables

{
  "cartId": "cl9x8z7y3000009l4h5z6b1c2",
  "paymentSessionId": "cl9x8z7y3000009l4h5z6b1c3"
}

​
Response

Returns the created order ID upon success.
The completeActiveCart mutation handles two flows:
  1. Paid orders: With paymentSessionId - captures payment and creates order
  2. Account orders: Without paymentSessionId - creates order on business account credit

​
Order Creation Process

1

Validate Cart

Ensures cart has all required data: line items, shipping address, region, and payment (if required)
2

Process Payment

Captures payment through selected provider (Stripe, PayPal, or manual) or validates account credit
3

Create Order Records

Creates order with snapshots of:
  • Line items with current product/variant data
  • Money amounts with pricing details
  • Addresses, shipping methods, and discounts
4

Update Inventory

(If inventory tracking enabled) Decrements available quantity
5

Send Confirmation

Sends order confirmation email to customer (unless noNotification flag set)
6

Create Event

Logs ORDER_PLACED event in order timeline

​
Update Order Status

Change the status of an existing order. 
mutation UpdateOrderStatus($id: ID!, $status: OrderStatusType!) {
  updateOrder(where: { id: $id }, data: { status: $status }) {
    id
    status
    updatedAt
  }
}

​
Variables

{
  "id": "cl9x8z7y3000009l4h5z6b1c2",
  "status": "completed"
}

​
Status Values

​
Status Types
Status changes automatically create STATUS_CHANGE events in the order timeline with previous and new status values.

​
Update Order

Update various order fields. 
mutation UpdateOrder($id: ID!, $data: OrderUpdateInput!) {
  updateOrder(where: { id: $id }, data: $data) {
    id
    status
    note
    updatedAt
  }
}

​
Variables

{
  "id": "cl9x8z7y3000009l4h5z6b1c2",
  "data": {
    "note": "Customer requested expedited shipping",
    "status": "requires_action"
  }
}

​
Cancel Order

Cancel an order and set the cancellation timestamp. 
mutation CancelOrder($id: ID!) {
  updateOrder(
    where: { id: $id }
    data: { 
      status: "canceled"
      canceledAt: "2024-01-15T10:30:00Z"
    }
  ) {
    id
    status
    canceledAt
  }
}

​
Create Fulfillment

Fulfill all or part of an order by creating a fulfillment record. 
mutation CreateFulfillment($data: FulfillmentCreateInput!) {
  createFulfillment(data: $data) {
    id
    createdAt
    fulfillmentItems {
      id
      quantity
      lineItem {
        id
        title
        sku
      }
    }
    shippingLabels {
      id
      trackingNumber
      trackingUrl
      carrier
      labelUrl
    }
  }
}

​
Variables - Manual Fulfillment

{
  "data": {
    "order": { "connect": { "id": "cl9x8z7y3000009l4h5z6b1c2" } },
    "fulfillmentProvider": { "connect": { "id": "cl9xabcdef000009l4xyz123" } },
    "fulfillmentItems": {
      "create": [
        {
          "lineItem": { "connect": { "id": "cl9x8z7y3000109l4h5z6b1c4" } },
          "quantity": 2
        }
      ]
    },
    "shippingLabels": {
      "create": [
        {
          "carrier": "UPS",
          "trackingNumber": "1Z999AA10123456784",
          "trackingUrl": "https://www.ups.com/track?tracknum=1Z999AA10123456784",
          "status": "purchased"
        }
      ]
    },
    "noNotification": false
  }
}
Fulfillments automatically:
  • Validate that quantities don’t exceed unfulfilled amounts
  • Create TRACKING_NUMBER_ADDED events when shipping labels are added
  • Send fulfillment emails to customers (unless noNotification: true)
  • Call order webhooks if configured

​
Create Provider Shipping Label

Purchase a shipping label through a shipping provider (Shippo, ShipEngine). 
mutation CreateProviderShippingLabel(
  $orderId: ID!
  $providerId: ID!
  $rateId: String!
  $dimensions: DimensionsInput
  $lineItems: [LineItemInput!]
) {
  createProviderShippingLabel(
    orderId: $orderId
    providerId: $providerId
    rateId: $rateId
    dimensions: $dimensions
    lineItems: $lineItems
  ) {
    id
    status
    trackingNumber
    trackingUrl
    labelUrl
    carrier
    data
  }
}

​
Variables

{
  "orderId": "cl9x8z7y3000009l4h5z6b1c2",
  "providerId": "cl9xshippo000009l4xyz123",
  "rateId": "rate_abc123def456",
  "dimensions": {
    "length": 12,
    "width": 8,
    "height": 6,
    "weight": 2.5,
    "unit": "in",
    "weightUnit": "lb"
  },
  "lineItems": [
    {
      "lineItemId": "cl9x8z7y3000109l4h5z6b1c4",
      "quantity": 1
    }
  ]
}

​
Process Flow

1

Get Shipping Rates

First call getRatesForOrder to get available rates from the provider
2

Select Rate

Choose desired rate based on carrier, service level, and price
3

Purchase Label

Call createProviderShippingLabel with the rate ID to purchase
4

Create Fulfillment

Label purchase automatically creates a fulfillment with the shipping label
5

Send Notification

Customer receives fulfillment email with tracking information

​
Get Shipping Rates

Retrieve available shipping rates for an order. 
mutation GetRatesForOrder(
  $orderId: ID!
  $providerId: ID!
  $dimensions: DimensionsInput!
) {
  getRatesForOrder(
    orderId: $orderId
    providerId: $providerId
    dimensions: $dimensions
  )
}

​
Variables

{
  "orderId": "cl9x8z7y3000009l4h5z6b1c2",
  "providerId": "cl9xshippo000009l4xyz123",
  "dimensions": {
    "length": 12,
    "width": 8,
    "height": 6,
    "weight": 2.5,
    "unit": "in",
    "weightUnit": "lb"
  }
}

​
Response

{
  "data": {
    "getRatesForOrder": [
      {
        "rateId": "rate_abc123",
        "carrier": "USPS",
        "serviceLevelName": "Priority Mail",
        "amount": 7.50,
        "currency": "USD",
        "estimatedDays": 2,
        "zone": "4"
      },
      {
        "rateId": "rate_def456",
        "carrier": "UPS",
        "serviceLevelName": "Ground",
        "amount": 12.35,
        "currency": "USD",
        "estimatedDays": 3,
        "zone": "4"
      }
    ]
  }
}

​
Cancel Fulfillment

Cancel a fulfillment (e.g., if shipment was not actually sent). 
mutation CancelFulfillment($id: ID!) {
  updateFulfillment(
    where: { id: $id }
    data: { canceledAt: "2024-01-15T10:30:00Z" }
  ) {
    id
    canceledAt
  }
}
Canceling a fulfillment makes the line items available for fulfillment again. This does not cancel the shipping label with the carrier.

​
Cancel Shipping Label

Cancel and potentially refund a shipping label with the carrier. 
mutation CancelShippingLabel($labelId: ID!) {
  cancelShippingLabel(labelId: $labelId) {
    id
    status
    refundStatus
    refundAmount
  }
}

​
Add Order Note

Add an internal note to an order. 
mutation AddOrderNote($id: ID!, $note: String!) {
  updateOrder(
    where: { id: $id }
    data: { note: $note }
  ) {
    id
    note
    events {
      id
      type
      data
      time
    }
  }
}

​
Order Lifecycle States

Orders progress through various states during their lifecycle:

​
Order Status Flow

​
Fulfillment Status Flow

​
Fulfillment States

​
Payment Status Flow

​
Payment States

​
Payment Operations

Payment mutations are typically handled during cart completion, but can be managed separately: 
mutation CapturePayment($paymentId: ID!) {
  updatePayment(
    where: { id: $paymentId }
    data: { status: "captured", capturedAt: "2024-01-15T10:30:00Z" }
  ) {
    id
    status
    amount
    capturedAt
  }
}
Payment capture automatically:
  • Updates order payment status
  • Creates a Capture record for accounting
  • Logs a PAYMENT_CAPTURED event
  • Updates order status if needed

​
Refund Order

Issue a refund for all or part of an order. 
mutation CreateRefund($data: RefundCreateInput!) {
  createRefund(data: $data) {
    id
    amount
    reason
    note
    payment {
      id
      amountRefunded
    }
  }
}

​
Variables

{
  "data": {
    "amount": 2500,
    "reason": "customer_request",
    "note": "Customer not satisfied with product quality",
    "payment": { "connect": { "id": "cl9xpay000009l4xyz123" } },
    "order": { "connect": { "id": "cl9x8z7y3000009l4h5z6b1c2" } }
  }
}

​
Validation Rules

​
Order Validation

​
Error Handling

Common error scenarios: 
{
  "errors": [
    {
      "message": "Cart not found",
      "extensions": {
        "code": "NOT_FOUND"
      }
    }
  ]
}
​
Error Codes
  • NOT_FOUND: Order, cart, or related entity not found
  • VALIDATION_ERROR: Data validation failed
  • PAYMENT_FAILED: Payment capture unsuccessful
  • INSUFFICIENT_INVENTORY: Not enough stock available
  • INSUFFICIENT_CREDIT: Account credit limit exceeded
  • INVALID_STATE: Operation not valid for current order state

​
Best Practices

  • Always validate cart before attempting completion
  • Handle payment failures gracefully with retry logic
  • Provide clear error messages to customers
  • Log all order creation attempts for debugging
  • Validate inventory before creating fulfillments
  • Use provider shipping labels for automated tracking
  • Send fulfillment notifications to keep customers informed
  • Double-check quantities to avoid over-fulfillment
  • Only change status when business logic requires it
  • Use requires_action for orders needing attention
  • Archive old completed/canceled orders periodically
  • Monitor orders stuck in pending status
  • Review order events for troubleshooting
  • Events are automatically created for key actions
  • Use events to track fulfillment and payment timeline
  • Custom events can be added for special workflows

Build docs developers (and LLMs) love

Get started for freeTalk to us