Skip to main content

​
Overview

The Orders API provides powerful GraphQL queries to retrieve order data with extensive filtering, sorting, and relationship expansion capabilities.

​
Get Multiple Orders

Query a list of orders with optional filtering and pagination. 
query GetOrders(
  $where: OrderWhereInput
  $take: Int
  $skip: Int
  $orderBy: [OrderOrderByInput!]
) {
  orders(where: $where, take: $take, skip: $skip, orderBy: $orderBy) {
    id
    displayId
    status
    email
    total
    subtotal
    createdAt
    user {
      id
      name
      email
    }
    lineItems {
      id
      title
      quantity
      sku
      thumbnail
      formattedUnitPrice
      formattedTotal
    }
  }
  ordersCount(where: $where)
}

​
Variables

{
  "where": {
    "status": { "equals": "pending" }
  },
  "take": 10,
  "skip": 0,
  "orderBy": [{ "createdAt": "desc" }]
}

​
Response Fields

​
orders
Order[]
Array of order objects matching the query criteria
​
ordersCount
integer
Total count of orders matching the query (for pagination)

​
Get Single Order

Retrieve detailed information for a specific order. 
query GetOrder($id: ID!) {
  order(where: { id: $id }) {
    id
    displayId
    status
    email
    total
    subtotal
    shipping
    tax
    discount
    createdAt
    updatedAt
    canceledAt
    fulfillmentStatus
    paymentDetails
    totalPaid
    formattedTotalPaid
    
    user {
      id
      name
      email
      phone
    }
    
    shippingAddress {
      firstName
      lastName
      company
      address1
      address2
      city
      province
      postalCode
      phone
      country {
        name
        iso2
      }
    }
    
    billingAddress {
      firstName
      lastName
      company
      address1
      address2
      city
      province
      postalCode
      phone
      country {
        name
        iso2
      }
    }
    
    lineItems {
      id
      title
      quantity
      sku
      thumbnail
      variantTitle
      formattedUnitPrice
      formattedTotal
      productData
      variantData
    }
    
    fulfillments {
      id
      createdAt
      canceledAt
      fulfillmentItems {
        id
        quantity
        lineItem {
          id
          title
          sku
        }
      }
      shippingLabels {
        id
        trackingNumber
        trackingUrl
        carrier
        labelUrl
      }
    }
    
    unfulfilled
    fulfillmentDetails
    
    payments {
      id
      amount
      status
      createdAt
      capturedAt
    }
    
    events {
      id
      type
      data
      time
      user {
        name
        email
      }
    }
  }
}

​
Variables

{
  "id": "cl9x8z7y3000009l4h5z6b1c2"
}

​
Filter by Status

Retrieve orders with a specific status. 
query GetPendingOrders {
  orders(
    where: { status: { equals: "pending" } }
    orderBy: [{ createdAt: "desc" }]
  ) {
    id
    displayId
    email
    total
    createdAt
  }
}

​
Filter by Customer

Get all orders for a specific customer. 
query GetCustomerOrders($customerId: ID!) {
  orders(
    where: { 
      user: { id: { equals: $customerId } }
    }
    orderBy: [{ createdAt: "desc" }]
  ) {
    id
    displayId
    status
    total
    createdAt
    lineItems {
      title
      quantity
      thumbnail
    }
  }
}

​
Variables

{
  "customerId": "cl9x8z7y3000009l4h5z6b1c2"
}

​
Search Orders

Search orders by display ID, email, or customer name. 
query SearchOrders($search: String!) {
  orders(
    where: {
      OR: [
        { displayId: { contains: $search } }
        { email: { contains: $search, mode: insensitive } }
        { user: { name: { contains: $search, mode: insensitive } } }
      ]
    }
  ) {
    id
    displayId
    email
    status
    total
    user {
      name
    }
  }
}

​
Variables

{
  "search": "[email protected]"
}

​
Get Order Counts by Status

Retrieve count of orders grouped by status. 
query GetOrderStatusCounts {
  pending: ordersCount(where: { status: { equals: "pending" } })
  completed: ordersCount(where: { status: { equals: "completed" } })
  canceled: ordersCount(where: { status: { equals: "canceled" } })
  requires_action: ordersCount(where: { status: { equals: "requires_action" } })
  archived: ordersCount(where: { status: { equals: "archived" } })
  all: ordersCount
}

​
Customer Order Lookup

Special query for customers to access their orders using a secret key (for guest orders). 
query GetCustomerOrder($orderId: ID!, $secretKey: String) {
  getCustomerOrder(orderId: $orderId, secretKey: $secretKey) {
    id
    displayId
    status
    total
    subtotal
    shipping
    tax
    createdAt
    email
    
    lineItems {
      id
      title
      quantity
      thumbnail
      variantTitle
      formattedUnitPrice
      formattedTotal
    }
    
    shippingAddress {
      firstName
      lastName
      address1
      city
      province
      postalCode
      country { name }
    }
    
    fulfillments {
      id
      createdAt
      shippingLabels {
        trackingNumber
        trackingUrl
        carrier
      }
    }
    
    fulfillmentStatus
  }
}
The getCustomerOrder query allows authenticated users to access their orders, or guest users to access orders using the secret key provided at checkout.

​
Virtual Fields

Orders include several computed virtual fields that provide calculated values:
​
Virtual Fields

​
Order Line Items

​
Line Item Fields

​
Order Events

Orders maintain a complete audit trail of all actions and status changes.
​
Event Types
  • ORDER_PLACED: Order created from cart
  • STATUS_CHANGE: Order status updated
  • PAYMENT_CAPTURED: Payment successfully captured
  • PAYMENT_STATUS_CHANGE: Payment status updated
  • FULFILLMENT_STATUS_CHANGE: Fulfillment status changed
  • TRACKING_NUMBER_ADDED: Shipping label created
  • RETURN_REQUESTED: Customer initiated return
  • REFUND_PROCESSED: Refund issued
  • NOTE_ADDED: Admin added note
  • EMAIL_SENT: Email notification sent

​
Filtering Options

The OrderWhereInput supports extensive filtering: 
{
  status?: { equals?: string, in?: string[] }
  email?: { contains?: string, mode?: "insensitive" }
  displayId?: { equals?: number, gte?: number, lte?: number }
  user?: { id?: { equals?: string } }
  region?: { id?: { equals?: string } }
  createdAt?: { gte?: string, lte?: string }
  canceledAt?: { not?: null, equals?: null }
  OR?: OrderWhereInput[]
  AND?: OrderWhereInput[]
}

​
Sorting Options

Orders can be sorted by:
  • createdAt - Order creation date
  • updatedAt - Last modification date
  • displayId - Order number
  • status - Order status
  • canceledAt - Cancellation date
{
  "orderBy": [
    { "createdAt": "desc" },
    { "displayId": "desc" }
  ]
}

Build docs developers (and LLMs) love

Get started for freeTalk to us