Skip to main content

Order history

Fetch and display orders for a customer or contact in your portal. The orders query returns orders for the authenticated user automatically based on the access token. You do not need to pass a user ID. For B2B portals, use the companyIds filter to show all orders placed by colleagues within the same company.

For order status transitions and the overall lifecycle, see Understanding the order lifecycle. For shipment details, see Shipment tracking.

Listing orders​

Use the orders query with the fields you need for a list view. The query returns a paginated response with order summaries.

Query​

query Orders($input: OrderSearchArguments) {
  orders(input: $input) {
    items {
      id
      uuid
      status
      type
      createdAt
      currency
      reference
      companyId
      total {
        gross
        net
        tax
      }
    }
    itemsFound
    offset
    page
    pages
    start
    end
  }
}

Variables​

{
  "input": {
    "page": 1,
    "offset": 10
  }
}

Response​

{
  "data": {
    "orders": {
      "items": [
        {
          "id": 277,
          "uuid": "019cb812-4a03-7128-a1f7-6e2d3b8c9f01",
          "status": "NEW",
          "type": "dropshipment",
          "createdAt": "2026-02-22T21:23:00.402Z",
          "currency": "EUR",
          "reference": null,
          "companyId": null,
          "total": {
            "gross": 695.08,
            "net": 841.05,
            "tax": 145.97
          }
        },
        {
          "id": 244,
          "uuid": "019c7543-8693-7954-bdc5-76acae4f8c92",
          "status": "CONFIRMED",
          "type": "dropshipment",
          "createdAt": "2026-02-19T09:38:05.649Z",
          "currency": "EUR",
          "reference": null,
          "companyId": 4,
          "total": {
            "gross": 3528.88,
            "net": 4269.94,
            "tax": 741.06
          }
        },
        {
          "id": 126,
          "uuid": "019b9e01-c2d4-7e12-b5a3-1f8d4c6e2a09",
          "status": "QUOTATION",
          "type": "quotation",
          "createdAt": "2026-02-04T09:12:02.172Z",
          "currency": "EUR",
          "reference": null,
          "companyId": 5,
          "total": {
            "gross": 1667.00,
            "net": 2017.07,
            "tax": 350.07
          }
        }
      ],
      "itemsFound": 236,
      "offset": 10,
      "page": 1,
      "pages": 24,
      "start": 1,
      "end": 10
    }
  }
}

The total.gross field is the order total excluding tax. The total.net field is the order total including tax.

The date field on orders is deprecated. Use createdAt instead.

Pagination fields​

FieldTypeDescription
itemsFoundInt!Total number of orders matching the filters
offsetInt!Number of items per page
pageInt!Current page number
pagesInt!Total number of pages
startInt!Start position of the current page
endInt!End position of the current page

Pagination​

Control the page size with offset and navigate pages with page. The default offset is 12.

Query​

query OrdersPaginated($input: OrderSearchArguments) {
  orders(input: $input) {
    items {
      id
      status
      createdAt
      total {
        gross
        net
      }
    }
    itemsFound
    page
    pages
  }
}

Variables​

{
  "input": {
    "page": 2,
    "offset": 5
  }
}

Response​

{
  "data": {
    "orders": {
      "items": [
        {
          "id": 242,
          "status": "CONFIRMED",
          "createdAt": "2026-02-09T12:40:24.081Z",
          "total": {
            "gross": 583.67,
            "net": 706.24
          }
        },
        {
          "id": 243,
          "status": "NEW",
          "createdAt": "2026-02-09T14:21:37.188Z",
          "total": {
            "gross": 412.30,
            "net": 498.88
          }
        }
      ],
      "itemsFound": 236,
      "page": 2,
      "pages": 48
    }
  }
}

Sorting orders​

Use the sortInputs field to control the order of results. Each sort input takes a field and an order (ASC or DESC).

Query​

query OrdersSorted($input: OrderSearchArguments) {
  orders(input: $input) {
    items {
      id
      status
      createdAt
      total {
        gross
      }
    }
    itemsFound
  }
}

Variables​

{
  "input": {
    "sortInputs": [{ "field": "CREATED_AT", "order": "DESC" }],
    "page": 1,
    "offset": 3
  }
}

Response​

{
  "data": {
    "orders": {
      "items": [
        {
          "id": 277,
          "status": "NEW",
          "createdAt": "2026-02-22T21:23:00.402Z",
          "total": {
            "gross": 695.08
          }
        },
        {
          "id": 244,
          "status": "CONFIRMED",
          "createdAt": "2026-02-19T09:38:05.649Z",
          "total": {
            "gross": 3528.88
          }
        },
        {
          "id": 243,
          "status": "NEW",
          "createdAt": "2026-02-09T14:21:37.188Z",
          "total": {
            "gross": 412.30
          }
        }
      ],
      "itemsFound": 236
    }
  }
}

Sort fields​

FieldDescription
IDSort by order ID
CREATED_ATSort by creation date
LAST_MODIFIED_ATSort by last modification date
STATUSSort by status alphabetically
COMPANYSort by company name
TOTAL_GROSSSort by order total (excluding tax)
VALID_UNTILSort by validity expiration date

Filtering orders​

The OrderSearchArguments input supports multiple filters. You can combine them in a single query.

By status​

Pass one or more status codes to filter orders by their current status. Status codes are strings like NEW, CONFIRMED, QUOTATION and ARCHIVED. For all available statuses and their meaning, see Understanding the order lifecycle.

Query​

query OrdersByStatus($input: OrderSearchArguments) {
  orders(input: $input) {
    items {
      id
      status
      type
      createdAt
      total {
        gross
        net
      }
    }
    itemsFound
  }
}

Variables​

{
  "input": {
    "status": ["CONFIRMED"],
    "sortInputs": [{ "field": "CREATED_AT", "order": "DESC" }],
    "page": 1,
    "offset": 3
  }
}

Response​

{
  "data": {
    "orders": {
      "items": [
        {
          "id": 244,
          "status": "CONFIRMED",
          "type": "dropshipment",
          "createdAt": "2026-02-19T09:38:05.649Z",
          "total": {
            "gross": 3528.88,
            "net": 4269.94
          }
        },
        {
          "id": 242,
          "status": "CONFIRMED",
          "type": "dropshipment",
          "createdAt": "2026-02-09T12:40:24.081Z",
          "total": {
            "gross": 583.67,
            "net": 706.24
          }
        }
      ],
      "itemsFound": 66
    }
  }
}

By date range​

Use the createdAt field with greaterThan and lessThan to filter by date range. Both values are date strings.

Variables​

{
  "input": {
    "createdAt": {
      "greaterThan": "2026-02-01",
      "lessThan": "2026-02-28"
    }
  }
}

You can also use lastModifiedAt with the same greaterThan and lessThan structure to filter by when orders were last updated.

By company (B2B)​

For B2B portals where contacts can view orders placed by anyone in their company, filter by companyIds. In B2B, orders belong to the company, not the individual. A procurement manager needs to see all orders placed by any contact in the company to track spending across departments and follow up on deliveries. The companyIds filter enables this company-wide view. Without it, a contact only sees their own orders.

Variables​

{
  "input": {
    "companyIds": [4],
    "page": 1,
    "offset": 3
  }
}

Response​

{
  "data": {
    "orders": {
      "items": [
        {
          "id": 244,
          "status": "CONFIRMED",
          "createdAt": "2026-02-19T09:38:05.649Z",
          "companyId": 4
        },
        {
          "id": 243,
          "status": "NEW",
          "createdAt": "2026-02-09T14:21:37.188Z",
          "companyId": 4
        }
      ],
      "itemsFound": 117
    }
  }
}

By order type​

Filter by type to separate regular orders from quotations or other order types.

TypeDescription
dropshipmentStandard order
purchasePurchase order
quotationQuotation or price request
stockStock order

Variables​

{
  "input": {
    "type": ["quotation"]
  }
}

By price range​

Use the price field to filter orders by their total. The price input supports greaterThan, lessThan and equal.

Variables​

{
  "input": {
    "price": {
      "greaterThan": 500,
      "lessThan": 5000
    }
  }
}

By channel​

The orders query returns orders from all channels by default. In multi-channel setups where the same user may have orders across different storefronts, pass channelId as an input parameter to filter orders to a specific channel.

Searching orders​

Use term with termFields to search across order data. The term performs a text search and termFields specifies which fields to match against. If termFields is omitted, the search runs across multiple fields.

Query​

query SearchOrders($input: OrderSearchArguments) {
  orders(input: $input) {
    items {
      id
      status
      createdAt
      items {
        name
        sku
        quantity
      }
    }
    itemsFound
  }
}

Variables​

{
  "input": {
    "term": "EcoSpot",
    "termFields": ["ITEM_NAME"]
  }
}

Response​

{
  "data": {
    "orders": {
      "items": [
        {
          "id": 244,
          "status": "CONFIRMED",
          "createdAt": "2026-02-19T09:38:05.649Z",
          "items": [
            {
              "name": "EcoSpot Recessed Downlight",
              "sku": "EL-ESD1",
              "quantity": 10
            },
            {
              "name": "Eclipse Elite LED Desk Lamp",
              "sku": "LL-EEDL01",
              "quantity": 5
            }
          ]
        },
        {
          "id": 243,
          "status": "NEW",
          "createdAt": "2026-02-09T14:21:37.188Z",
          "items": [
            {
              "name": "Hidden Glow Wall Washer",
              "sku": "GT-HGW1",
              "quantity": 1
            },
            {
              "name": "EcoSpot Recessed Downlight",
              "sku": "EL-ESD1",
              "quantity": 1
            }
          ]
        }
      ],
      "itemsFound": 21
    }
  }
}

Search fields​

The most commonly used search fields for a customer portal:

FieldDescription
IDOrder ID
REFERENCECustomer reference number
ITEM_NAMEProduct name on the order line
ITEM_SKUProduct SKU on the order line
RECIPIENT_FIRST_NAMEFirst name on the delivery address
RECIPIENT_LAST_NAMELast name on the delivery address
RECIPIENT_COMPANYCompany name on the delivery address
REMARKSOrder remarks

Other available fields include INVOICE_ADDRESS_COMPANY, INVOICE_ADDRESS_FIRST_NAME, INVOICE_ADDRESS_LAST_NAME, RECIPIENT_EMAIL, ITEM_EAN_CODE, ITEM_MANUFACTURER, ITEM_SUPPLIER, ACCOUNTING_ID and DEBTOR_ID.

Fetching a single order​

By order ID​

Use the order query to fetch full details for a single order. This includes items, addresses, totals, shipping and payment data.

Query​

query OrderDetail($orderId: Int!) {
  order(orderId: $orderId) {
    id
    uuid
    status
    type
    createdAt
    lastModifiedAt
    email
    reference
    remarks
    currency
    language
    companyId
    total {
      gross
      net
      tax
      discountType
      discountValue
      taxPercentages {
        percentage
        total
      }
    }
    items {
      id
      class
      productId
      sku
      name
      quantity
      price
      priceNet
      priceTotal
      priceTotalNet
      tax
      taxPercentage
      discount
      originalPrice
      notes
      product {
        productId
        names {
          value
          language
        }
        sku
        slugs {
          value
          language
        }
      }
    }
    deliveryAddress: addresses(type: delivery) {
      firstName
      middleName
      lastName
      company
      street
      number
      numberExtension
      postalCode
      city
      region
      country
      phone
      email
    }
    invoiceAddress: addresses(type: invoice) {
      firstName
      middleName
      lastName
      company
      street
      number
      numberExtension
      postalCode
      city
      region
      country
      phone
      email
    }
    postageData {
      method
      gross
      net
      tax
      taxPercentage
      carrier
      partialDeliveryAllowed
      requestDate
    }
    paymentData {
      method
      status
      gross
      net
      tax
      taxPercentage
    }
  }
}

Variables​

{
  "orderId": 244
}

Response​

{
  "data": {
    "order": {
      "id": 244,
      "uuid": "019c7543-8693-7954-bdc5-76acae4f8c92",
      "status": "CONFIRMED",
      "type": "dropshipment",
      "createdAt": "2026-02-19T09:38:05.649Z",
      "lastModifiedAt": "2026-02-19T09:53:41.263Z",
      "email": "lisa@brouwerindustrie.nl",
      "reference": null,
      "remarks": null,
      "currency": "EUR",
      "language": "NL",
      "companyId": 4,
      "total": {
        "gross": 3528.88,
        "net": 4269.94,
        "tax": 741.06,
        "discountType": "N",
        "discountValue": 0,
        "taxPercentages": [
          {
            "percentage": 21,
            "total": 741.06
          }
        ]
      },
      "items": [
        {
          "id": 26987,
          "class": "product",
          "productId": 44,
          "sku": "EL-ESD1",
          "name": "EcoSpot Recessed Downlight",
          "quantity": 10,
          "price": 309.14,
          "priceNet": 374.06,
          "priceTotal": 3091.42,
          "priceTotalNet": 3740.62,
          "tax": 649.20,
          "taxPercentage": 21,
          "discount": 33.40,
          "originalPrice": 342.54,
          "notes": "",
          "product": {
            "productId": 44,
            "names": [
              {
                "value": "EcoSpot Recessed Downlight",
                "language": "NL"
              }
            ],
            "sku": "EL-ESD1",
            "slugs": [
              {
                "value": "ecospot-recessed-downlight",
                "language": "NL"
              }
            ]
          }
        },
        {
          "id": 26992,
          "class": "product",
          "productId": 12,
          "sku": "LL-EEDL01",
          "name": "Eclipse Elite LED Desk Lamp",
          "quantity": 5,
          "price": 85.49,
          "priceNet": 103.44,
          "priceTotal": 427.45,
          "priceTotalNet": 517.22,
          "tax": 89.77,
          "taxPercentage": 21,
          "discount": 4.50,
          "originalPrice": 89.99,
          "notes": "",
          "product": {
            "productId": 12,
            "names": [
              {
                "value": "Eclipse Elite LED Desk Lamp",
                "language": "NL"
              }
            ],
            "sku": "LL-EEDL01",
            "slugs": [
              {
                "value": "eclipse-elite-led-desk-lamp",
                "language": "NL"
              }
            ]
          }
        }
      ],
      "deliveryAddress": [
        {
          "firstName": "Lisa",
          "middleName": null,
          "lastName": "de Vries",
          "company": "Brouwer Industrie",
          "street": "Keizersgracht",
          "number": "112",
          "numberExtension": null,
          "postalCode": "1016 GE",
          "city": "Amsterdam",
          "region": null,
          "country": "NL",
          "phone": "+31 20 123 4567",
          "email": "lisa@brouwerindustrie.nl"
        }
      ],
      "invoiceAddress": [
        {
          "firstName": "Lisa",
          "middleName": null,
          "lastName": "de Vries",
          "company": "Brouwer Industrie",
          "street": "Keizersgracht",
          "number": "112",
          "numberExtension": null,
          "postalCode": "1016 GE",
          "city": "Amsterdam",
          "region": null,
          "country": "NL",
          "phone": "+31 20 123 4567",
          "email": "finance@brouwerindustrie.nl"
        }
      ],
      "postageData": {
        "method": "REGULAR",
        "gross": 10.00,
        "net": 12.10,
        "tax": 2.10,
        "taxPercentage": 21,
        "carrier": null,
        "partialDeliveryAllowed": "N",
        "requestDate": "2026-02-06T09:20:53.728Z"
      },
      "paymentData": {
        "method": "ACCOUNT",
        "status": "UNKNOWN",
        "gross": 0,
        "net": 0,
        "tax": 0,
        "taxPercentage": 21
      }
    }
  }
}

By UUID​

You can also fetch an order by its UUID using the orderUUID parameter. This is useful when you use UUIDs in your frontend URLs instead of numeric IDs.

query OrderByUUID($orderUUID: String!) {
  order(orderUUID: $orderUUID) {
    id
    status
    createdAt
  }
}
{
  "orderUUID": "019c7543-8693-7954-bdc5-76acae4f8c92"
}

Response​

{
  "data": {
    "order": {
      "id": 244,
      "status": "CONFIRMED",
      "createdAt": "2026-02-19T09:38:05.649Z"
    }
  }
}

The order query accepts either orderId or orderUUID. You do not need to provide both.

Order items​

Each order contains an items array with all order lines. Items have a class field that indicates what type of line item it is.

ClassDescription
productA product the customer ordered
incentiveA bonus or free item added by a promotion
surchargeAn additional fee (handling, small order surcharge)

When displaying items in a portal, you will typically show all items but may want to visually distinguish incentives and surcharges from regular products.

Item pricing​

Each item carries both unit and total pricing, with and without tax.

FieldDescription
priceUnit price excluding tax
priceNetUnit price including tax
priceTotalTotal price excluding tax (price x quantity)
priceTotalNetTotal price including tax
taxTotal tax amount for this item
taxPercentageTax percentage applied

Discounts​

If an item has a discount applied, the discount field contains the discount amount per unit and originalPrice contains the price before the discount was applied. When discount is null or 0, no discount was applied.

Linking to product pages​

Use the product field on each item to get the product's slugs for building links to product detail pages. The product field returns null if the product has been deleted from the catalog since the order was placed.

Order totals​

The total field provides the financial summary for the entire order.

FieldTypeDescription
grossFloat!Order total excluding tax
netFloat!Order total including tax
taxFloat!Total tax amount
discountTypeOrderDiscountType!Discount type: N (none), P (percentage), A (absolute)
discountValueFloat!Discount value (percentage or absolute amount, depending on discountType)
taxPercentages[OrderTotalTaxPercentage!]!Tax breakdown per rate

The taxPercentages array lists each tax rate applied to the order with its total. This is useful for invoices where you need to show the tax breakdown by rate.

{
  "taxPercentages": [
    {
      "percentage": 21,
      "total": 741.06
    }
  ]
}

Addresses​

The addresses field on an order accepts a type argument to filter by address type: delivery, invoice or home. Use GraphQL aliases to fetch both delivery and invoice addresses in a single query.

deliveryAddress: addresses(type: delivery) {
  firstName
  middleName
  lastName
  company
  street
  number
  numberExtension
  postalCode
  city
  country
}
invoiceAddress: addresses(type: invoice) {
  firstName
  middleName
  lastName
  company
  street
  number
  numberExtension
  postalCode
  city
  country
}

The addresses field returns an array because an order can technically have multiple addresses of the same type. In most cases there is one delivery address and one invoice address.

If you need all addresses without filtering by type, use the orderAddresses field instead. This returns [OrderAddress!]! with a type field on each address.

Shipping and payment summary​

The postageData and paymentData fields contain the shipping and payment details set during checkout.

postageData fields​

FieldTypeDescription
methodString!Shipping method name
grossFloat!Shipping cost excluding tax
netFloat!Shipping cost including tax
taxFloat!Tax on shipping costs
taxPercentageFloat!Tax percentage for shipping
carrierStringSelected carrier name
requestDateDateTimeRequested delivery date
partialDeliveryAllowedYesNoWhether partial delivery is allowed (Y or N)

paymentData fields​

FieldTypeDescription
methodString!Payment method name
statusStringPayment status
grossFloat!Transaction cost excluding tax
netFloat!Transaction cost including tax
taxFloat!Tax on transaction costs
taxPercentageFloat!Tax percentage for transaction costs

For full payment tracking with individual transactions, see Payment integration. For shipment tracking with carrier details and tracking codes, see Shipment tracking.

Next steps​