Order Queries

You can fetch orders in your templates or PHP code using order queries.

{# Create a new order query #}
{% set myOrderQuery = craft.orders() %}

Once you’ve created an order query, you can set parameters on it to narrow down the results, and then execute it by calling .all(). An array of Order objects will be returned.

TIP

See Introduction to Element Queries in the Craft docs to learn about how element queries work.

Example

We can display an order with a given order number by doing the following:

  1. Create an order query with craft.orders().
  2. Set the number parameter on it.
  3. Fetch the order with .one().
  4. Output information about the order as HTML.
{# Get the requested order number from the query string #}
{% set orderNumber = craft.app.request.getQueryParam('number') %}

{# Create an order query with the 'number' parameter #}
{% set myOrderQuery = craft.orders()
    .number(orderNumber) %}

{# Fetch the order #}
{% set order = myOrderQuery.one() %}

{# Make sure it exists #}
{% if not order %}
    {% exit 404 %}
{% endif %}

{# Display the order #}
<h1>Order {{ order.getShortNumber() }}</h1>
<!-- ... ->

Parameters

Order queries support the following parameters:

anyStatus

Clears out the status() and enabledForSite() parameters.

{# Fetch all orders, regardless of status #}
{% set orders = craft.orders()
    .anyStatus()
    .all() %}

asArray

Causes the query to return matching orders as arrays of data, rather than Order objects.

{# Fetch orders as arrays #}
{% set orders = craft.orders()
    .asArray()
    .all() %}

customer

Narrows the query results based on the customer.

Possible values include:

ValueFetches orders…
a Customer objectwith a customer represented by the object.
{# Fetch the current user's orders #}
{% set orders = craft.orders()
    .customer(currentUser.customerFieldHandle)
    .all() %}

customerId

Narrows the query results based on the customer, per their ID.

Possible values include:

ValueFetches orders…
1with a customer with an ID of 1.
'not 1'not with a customer with an ID of 1.
[1, 2]with a customer with an ID of 1 or 2.
['not', 1, 2]not with a customer with an ID of 1 or 2.
{# Fetch the current user's orders #}
{% set orders = craft.orders()
    .customerId(currentUser.customerFieldHandle.id)
    .all() %}

dateCreated

Narrows the query results based on the orders’ creation dates.

Possible values include:

ValueFetches orders…
'>= 2018-04-01'that were created on or after 2018-04-01.
'< 2018-05-01'that were created before 2018-05-01
['and', '>= 2018-04-04', '< 2018-05-01']that were created between 2018-04-01 and 2018-05-01.
{# Fetch orders created last month #}
{% set start = date('first day of last month')|atom %}
{% set end = date('first day of this month')|atom %}

{% set orders = craft.orders()
    .dateCreated(['and', ">= #{start}", "< #{end}"])
    .all() %}

dateOrdered

Narrows the query results based on the orders’ completion dates.

Possible values include:

ValueFetches orders…
'>= 2018-04-01'that were completed on or after 2018-04-01.
'< 2018-05-01'that were completed before 2018-05-01
['and', '>= 2018-04-04', '< 2018-05-01']that were completed between 2018-04-01 and 2018-05-01.
{# Fetch orders that were completed recently #}
{% set aWeekAgo = date('7 days ago')|atom %}

{% set orders = craft.orders()
    .dateCompleted(">= #{aWeekAgo}")
    .all() %}

datePaid

Narrows the query results based on the orders’ paid dates.

Possible values include:

ValueFetches orders…
'>= 2018-04-01'that were paid on or after 2018-04-01.
'< 2018-05-01'that were paid before 2018-05-01
['and', '>= 2018-04-04', '< 2018-05-01']that were completed between 2018-04-01 and 2018-05-01.
{# Fetch orders that were paid for recently #}
{% set aWeekAgo = date('7 days ago')|atom %}

{% set orders = craft.orders()
    .datePaid(">= #{aWeekAgo}")
    .all() %}

dateUpdated

Narrows the query results based on the orders’ last-updated dates.

Possible values include:

ValueFetches orders…
'>= 2018-04-01'that were updated on or after 2018-04-01.
'< 2018-05-01'that were updated before 2018-05-01
['and', '>= 2018-04-04', '< 2018-05-01']that were updated between 2018-04-01 and 2018-05-01.
{# Fetch orders updated in the last week #}
{% set lastWeek = date('1 week ago')|atom %}

{% set orders = craft.orders()
    .dateUpdated(">= #{lastWeek}")
    .all() %}

email

Narrows the query results based on the customers’ email addresses.

Possible values include:

ValueFetches orders with customers…
'foo@bar.baz'with an email of foo@bar.baz.
'not foo@bar.baz'not with an email of foo@bar.baz.
'*@bar.baz'with an email that ends with @bar.baz.
{# Fetch orders from customers with a .co.uk domain on their email address #}
{% set orders = craft.orders()
    .email('*.co.uk')
    .all() %}

expiryDate

Narrows the query results based on the orders’ expiry dates.

Possible values include:

ValueFetches orders…
'>= 2020-04-01'that will expire on or after 2020-04-01.
'< 2020-05-01'that will expire before 2020-05-01
['and', '>= 2020-04-04', '< 2020-05-01']that will expire between 2020-04-01 and 2020-05-01.
{# Fetch orders expiring this month #}
{% set nextMonth = date('first day of next month')|atom %}

{% set orders = craft.orders()
    .expiryDate("< #{nextMonth}")
    .all() %}

fixedOrder

Causes the query results to be returned in the order specified by id.

{# Fetch orders in a specific order #}
{% set orders = craft.orders()
    .id([1, 2, 3, 4, 5])
    .fixedOrder()
    .all() %}

gateway

Narrows the query results based on the gateway.

Possible values include:

ValueFetches orders…
a Gateway objectwith a gateway represented by the object.

gatewayId

Narrows the query results based on the gateway, per its ID.

Possible values include:

ValueFetches orders…
1with a gateway with an ID of 1.
'not 1'not with a gateway with an ID of 1.
[1, 2]with a gateway with an ID of 1 or 2.
['not', 1, 2]not with a gateway with an ID of 1 or 2.

hasPurchasables

Narrows the query results to only orders that have certain purchasables.

Possible values include:

ValueFetches orders…
a PurchasableInterface objectwith a purchasable represented by the object.
an array of PurchasableInterface objectswith all the purchasables represented by the objects.

id

Narrows the query results based on the orders’ IDs.

Possible values include:

ValueFetches orders…
1with an ID of 1.
'not 1'not with an ID of 1.
[1, 2]with an ID of 1 or 2.
['not', 1, 2]not with an ID of 1 or 2.
{# Fetch the order by its ID #}
{% set order = craft.orders()
    .id(1)
    .one() %}

TIP

This can be combined with fixedOrder if you want the results to be returned in a specific order.

inReverse

Causes the query results to be returned in reverse order.

{# Fetch orders in reverse #}
{% set orders = craft.orders()
    .inReverse()
    .all() %}

isCompleted

Narrows the query results to only orders that are completed.

{# Fetch completed orders #}
{% set orders = {twig-function}
    .isCompleted()
    .all() %}

isPaid

Narrows the query results to only orders that are paid.

{# Fetch paid orders #}
{% set orders = {twig-function}
    .isPaid()
    .all() %}

isUnpaid

Narrows the query results to only orders that are not paid.

{# Fetch unpaid orders #}
{% set orders = {twig-function}
    .isUnpaid()
    .all() %}

limit

Determines the number of orders that should be returned.

{# Fetch up to 10 orders  #}
{% set orders = craft.orders()
    .limit(10)
    .all() %}

number

Narrows the query results based on the order number.

Possible values include:

ValueFetches orders…
'xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'with a matching order number
{# Fetch the requested order #}
{% set orderNumber = craft.app.request.getQueryParam('number') %}
{% set order = craft.orders()
    .number(orderNumber)
    .one() %}

offset

Determines how many orders should be skipped in the results.

{# Fetch all orders except for the first 3 #}
{% set orders = craft.orders()
    .offset(3)
    .all() %}

orderBy

Determines the order that the orders should be returned in.

{# Fetch all orders in order of date created #}
{% set orders = craft.orders()
    .orderBy('elements.dateCreated asc')
    .all() %}

orderStatus

Narrows the query results based on the order statuses.

Possible values include:

ValueFetches orders…
'foo'with an order status with a handle of foo.
'not foo'not with an order status with a handle of foo.
['foo', 'bar']with an order status with a handle of foo or bar.
['not', 'foo', 'bar']not with an order status with a handle of foo or bar.
a OrderStatus objectwith an order status represented by the object.
{# Fetch shipped orders #}
{% set orders = craft.orders()
    .orderStatus('shipped')
    .all() %}

orderStatusId

Narrows the query results based on the order statuses, per their IDs.

Possible values include:

ValueFetches orders…
1with an order status with an ID of 1.
'not 1'not with an order status with an ID of 1.
[1, 2]with an order status with an ID of 1 or 2.
['not', 1, 2]not with an order status with an ID of 1 or 2.
{# Fetch orders with an order status with an ID of 1 #}
{% set orders = craft.orders()
    .authorGroupId(1)
    .all() %}

relatedTo

Narrows the query results to only orders that are related to certain other elements.

See Relations for a full explanation of how to work with this parameter.

{# Fetch all orders that are related to myCategory #}
{% set orders = craft.orders()
    .relatedTo(myCategory)
    .all() %}

Narrows the query results to only orders that match a search query.

See Searching for a full explanation of how to work with this parameter.

{# Get the search query from the 'q' query string param #}
{% set searchQuery = craft.request.getQueryParam('q') %}

{# Fetch all orders that match the search query #}
{% set orders = craft.orders()
    .search(searchQuery)
    .all() %}

uid

Narrows the query results based on the orders’ UIDs.

{# Fetch the order by its UID #}
{% set order = craft.orders()
    .uid('xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx')
    .one() %}

user

Narrows the query results based on the customer’s user account.

Possible values include:

ValueFetches orders…
1with a customer with a user account ID of 1.
a User objectwith a customer with a user account represented by the object.
{# Fetch the current user's orders #}
{% set orders = craft.orders()
    .user(currentUser)
    .all() %}

with

Causes the query to return matching orders eager-loaded with related elements.

See Eager-Loading Elements for a full explanation of how to work with this parameter.

{# Fetch orders eager-loaded with the "Related" field’s relations #}
{% set orders = craft.orders()
    .with(['related'])
    .all() %}