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:

Param Description
anyStatus Clears out the status() and enabledForSite() parameters.
asArray Causes the query to return matching orders as arrays of data, rather than Order objects.
clearCachedResult Clears the cached result.
customer Narrows the query results based on the customer.
customerId Narrows the query results based on the customer, per their ID.
dateAuthorized Narrows the query results based on the orders’ authorized dates.
dateCreated Narrows the query results based on the orders’ creation dates.
dateOrdered Narrows the query results based on the orders’ completion dates.
datePaid Narrows the query results based on the orders’ paid dates.
dateUpdated Narrows the query results based on the orders’ last-updated dates.
email Narrows the query results based on the customers’ email addresses.
expiryDate Narrows the query results based on the orders’ expiry dates.
fixedOrder Causes the query results to be returned in the order specified by id.
gateway Narrows the query results based on the gateway.
gatewayId Narrows the query results based on the gateway, per its ID.
hasLineItems Narrows the query results to only orders that have line items.
hasPurchasables Narrows the query results to only orders that have certain purchasables.
hasTransactions Narrows the query results to only carts that have at least one transaction.
id Narrows the query results based on the orders’ IDs.
ignorePlaceholders Causes the query to return matching orders as they are stored in the database, ignoring matching placeholder elements that were set by craft\services\Elements::setPlaceholderElement().
inReverse Causes the query results to be returned in reverse order.
isCompleted Narrows the query results to only orders that are completed.
isPaid Narrows the query results to only orders that are paid.
isUnpaid Narrows the query results to only orders that are not paid.
limit Determines the number of orders that should be returned.
number Narrows the query results based on the order number.
offset Determines how many orders should be skipped in the results.
orderBy Determines the order that the orders should be returned in. (If empty, defaults to id ASC.)
orderStatus Narrows the query results based on the order statuses.
orderStatusId Narrows the query results based on the order statuses, per their IDs.
origin Narrows the query results based on the origin.
preferSites If unique() is set, this determines which site should be selected when querying multi-site elements.
reference Narrows the query results based on the order reference.
relatedTo Narrows the query results to only orders that are related to certain other elements.
search Narrows the query results to only orders that match a search query.
shortNumber Narrows the query results based on the order short number.
trashed Narrows the query results to only orders that have been soft-deleted.
uid Narrows the query results based on the orders’ UIDs.
user Narrows the query results based on the customer’s user account.
with Causes the query to return matching orders eager-loaded with related elements.

# 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() %}

# clearCachedResult

Clears the cached result.

# customer

Narrows the query results based on the customer.

Possible values include:

Value Fetches orders…
a Customer object with a customer represented by the object.
{# Fetch the current user's orders #}
{% set customer = craft.commerce.customers.getCustomerByUserId(currentUser.id) %}
{% set orders = craft.orders()
    .customer(customer)
    .all() %}

# customerId

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

Possible values include:

Value Fetches orders…
1 with 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 customer = craft.commerce.customers.getCustomerByUserId(currentUser.id) %}
{% set orders = craft.orders()
    .customerId(customer.id)
    .all() %}

# dateAuthorized

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

Possible values include:

Value Fetches orders…
'>= 2018-04-01' that were authorized on or after 2018-04-01.
'< 2018-05-01' that were authorized 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 authorized recently #}
{% set aWeekAgo = date('7 days ago')|atom %}

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

# dateCreated

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

Possible values include:

Value Fetches 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:

Value Fetches 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()
    .dateOrdered(">= #{aWeekAgo}")
    .all() %}

# datePaid

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

Possible values include:

Value Fetches 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:

Value Fetches 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:

Value Fetches 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:

Value Fetches 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:

Value Fetches orders…
a Gateway object with a gateway represented by the object.

# gatewayId

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

Possible values include:

Value Fetches orders…
1 with 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.

# hasLineItems

Narrows the query results to only orders that have line items.

{# Fetch orders that do or do not have line items #}
{% set orders = {twig-function}
    .hasLineItems()
    .all() %}

# hasPurchasables

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

Possible values include:

Value Fetches orders…
a PurchasableInterface object with a purchasable represented by the object.
an array of PurchasableInterface objects with all the purchasables represented by the objects.

# hasTransactions

Narrows the query results to only carts that have at least one transaction.

{# Fetch carts that have attempted payments #}
{% set orders = {twig-function}
    .hasTransactions()
    .all() %}

# id

Narrows the query results based on the orders’ IDs.

Possible values include:

Value Fetches orders…
1 with 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.

# ignorePlaceholders

Causes the query to return matching orders as they are stored in the database, ignoring matching placeholder elements that were set by craft\services\Elements::setPlaceholderElement().

# 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:

Value Fetches 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. (If empty, defaults to id ASC.)

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

# orderStatus

Narrows the query results based on the order statuses.

Possible values include:

Value Fetches 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 object with 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:

Value Fetches orders…
1 with 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() %}

# origin

Narrows the query results based on the origin.

Possible values include:

Value Fetches orders…
'web' with an origin of web.
'not remote' not with an origin of remote.
['web', 'cp'] with an order origin of web or cp.
['not', 'remote', 'cp'] not with an origin of web or cp.
{# Fetch shipped orders #}
{% set orders = craft.orders()
    .origin('web')
    .all() %}

# preferSites

If unique() is set, this determines which site should be selected when querying multi-site elements.

For example, if element “Foo” exists in Site A and Site B, and element “Bar” exists in Site B and Site C, and this is set to ['c', 'b', 'a'], then Foo will be returned for Site C, and Bar will be returned for Site B.

If this isn’t set, then preference goes to the current site.

{# Fetch unique orders from Site A, or Site B if they don’t exist in Site A #}
{% set orders = craft.orders()
    .site('*')
    .unique()
    .preferSites(['a', 'b'])
    .all() %}

# reference

Narrows the query results based on the order reference.

Possible values include:

Value Fetches orders…
'xxxx' with a matching order reference
{# Fetch the requested order #}
{% set orderReference = craft.app.request.getQueryParam('ref') %}
{% set order = craft.orders()
    .reference(orderReference)
    .one() %}

# 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.app.request.getQueryParam('q') %}

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

# shortNumber

Narrows the query results based on the order short number.

Possible values include:

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

# trashed

Narrows the query results to only orders that have been soft-deleted.

{# Fetch trashed orders #}
{% set orders = craft.orders()
    .trashed()
    .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:

Value Fetches orders…
1 with a customer with a user account ID of 1.
a User object with 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() %}