The Order Search feature is intended for merchants to perform searches on a large number of Orders in a Project.
3 months
are indexed and can be retrieved.- maintain a cache of Orders,
- compare version numbers to detect outdated Orders,
- detect if the search index for an Order is out of date and react accordingly (for example display a warning, or initiate an update of the Order search index).
Activation of the API
To activate the API for your Projects, choose one of the following options:
- using the Change Order Search Status update action on the Project API.
- contacting the Composable Commerce support team and provide the region, project key(s), and use case(s).
Automatic deactivation
Representations
OrderSearchRequest
query | The Order search query. |
sort Array of OrderSearchSorting | Controls how results to your query are sorted. If not provided, the results are sorted by relevance in descending order. |
limit Int | The maximum number of search results to be returned on one page. Default: 10 Minimum: 0 Maximum: 100 |
offset Int | The number of search results to be skipped in the response for pagination. Default: 0 Minimum: 0 Maximum: 10000 |
{
"query": {
"and": [
{
"fullText": {
"field": "customLineItems.name",
"language": "en",
"value": "banana"
}
},
{
"filter": [
{
"exact": {
"field": "store.name",
"language": "en",
"value": "fruit_store"
}
}
]
}
]
},
"sort": [
{
"field": "customLineItems.name",
"language": "en",
"order": "desc"
}
],
"limit": 50,
"offset": 0
}
OrderPagedSearchResponse
total Int | Total number of results matching the query. |
offset Int | Number of elements skipped. |
limit Int | Number of results requested. Minimum: 0 Maximum: 100 |
hits Array of Hit | Actual results. |
Hit
id String | Unique identifier of the Order. |
version Int | Current version of the Order. |
relevance Float | The higher the value is, the more relevant the hit is for the search request. Minimum:0 Maximum: 1 |
Search Orders
view_orders:{projectKey}
region String | Region in which the Project is hosted. |
projectKey String | key of the Project. |
application/json
application/json
Check if Order Search index exists
200 OK
status if the index exists or a 404 Not Found
error otherwise.view_orders:{projectKey}
region String | Region in which the Project is hosted. |
projectKey String | key of the Project. |
curl --head https://api.{region}.commercetools.com/{projectKey}/orders/search -i \
--header "Authorization: Bearer ${BEARER_TOKEN}"
query FetchIndicesExists {
ordersIndicesExist {
searchableIndexExists
newInProgress
}
}
The query response contains the following fields indicating the status of the search index:
searchableIndexExists
- the index exists and Orders can be searched.newInProgress
- the index is being created by a job. Use thereIndexAllOrders
mutation to get the job ID.
FetchIndicesExists
query to be executed as cURL command:$ curl -X POST https://api.{region}.commercetools.com/{projectKey}/orders/indexer/graphql \
-H "Content-Type:application/json" \
-H "Authorization:Bearer ..." \
-d '{"query": "{ ordersIndicesExist { searchableIndexExists } }" }'
Searchable Order fields
Number and date fields
Standard field | Data type | Query for Orders |
---|---|---|
completedAt | dateTime | completed at a certain date and time. |
createdAt | dateTime | created at a certain date and time. |
lastModifiedAt | dateTime | last modified at any of its fields at a certain date and time. |
version | long | with a certain version of the resource. |
customLineItems.state.quantity | long | with Custom Line Item's ItemState of a certain quantity. You may need to initiate an update to get the latest state of this field. |
lineItems.state.quantity | long | with Line Item's ItemState of a certain quantity. |
returnInfo.items.createdAt | dateTime | with ReturnItems created at a certain date and time. |
returnInfo.items.lastModifiedAt | dateTime | with ReturnItems last modified at a certain date and time. |
returnInfo.returnDate | dateTime | with ReturnInfo of a certain date and time. |
totalPrice.centAmount | long | with a total price of a certain amount. |
Phone fields
(783) 627-3740
will also match (783) 6273740
.
The same applies to prefix queries.
Special characters are only taken into account when performing queries of type exact.Standard field | Query for Orders with |
---|---|
billingAddress.mobile | a billing address of a certain mobile number. |
billingAddress.phone | a billing address of a certain phone number. |
itemShippingAddresses.mobile | a Line Item shipping address of a certain mobile number. |
itemShippingAddresses.phone | a Line Item shipping address of a certain phone number. |
shippingAddress.mobile | a shipping address of a certain mobile number. |
shippingAddress.phone | a shipping address of a certain phone number. |
Text fields
Standard field on Order | Query for Orders |
---|---|
all | with a certain string in the combination of all fields. |
country | with a certain country. |
createdBy.clientId | created by an API Client with a certain client ID. |
customerEmail | with a certain Customer email address. |
customerGroup.key | from Customers of a certain Customer Group specified by its key .You may need to initiate an update to get the latest state of this field. |
customerGroup.name | from Customers of a certain Customer Group specified by its name .You may need to initiate an update to get the latest state of this field. |
lastModifiedBy.clientId | last modified by an API Client with a certain client ID. |
orderState | with a certain OrderState. |
paymentState | with a certain PaymentState. |
shipmentState | with a certain ShipmentState. |
state.name | with a State of a certain name for the language specified in the expression.You may need to initiate an update to get the latest state of this field. |
store.name | with a Store of a certain name for the language specified in the expression.You may need to initiate an update to get the latest state of this field. |
Standard field on Billing Address | Query for Orders with a billing address of |
---|---|
billingAddress.city | a certain city. |
billingAddress.company | a certain company. |
billingAddress.country | a certain country. |
billingAddress.firstName | a certain first name. |
billingAddress.lastName | a certain last name. |
billingAddress.postalCode | a certain post code. |
Standard field on Item Shipping Address | Query for Orders with a Line Item Shipping address of |
---|---|
itemShippingAddresses.city | a certain city. |
itemShippingAddresses.company | a certain company. |
itemShippingAddresses.country | a certain country. |
itemShippingAddresses.firstName | a certain first name. |
itemShippingAddresses.lastName | a certain last name. |
itemShippingAddresses.postalCode | a certain post code. |
Standard field on Shipping Address | Query for Orders with a Shipping address of |
---|---|
shippingAddress.city | a certain city. |
shippingAddress.company | a certain company. |
shippingAddress.country | a certain country. |
shippingAddress.firstName | a certain first name. |
shippingAddress.lastName | a certain last name. |
shippingAddress.postalCode | a certain post code. |
Standard field on Line Items and Custom Line Items | Query for Orders with |
---|---|
lineItems.productId | Line Items of a certain Product with a specified id . |
lineItems.variant.sku | Line Items of a certain Product Variant with a specified sku . |
lineItems.name | Line Items of a certain Product name for the language specified in the expression. |
lineItems.state.state.name | Line Items of a certain State name for the language specified in the expression.You may need to initiate an update to get the latest state of this field. |
customLineItems.name | Custom Line Items of a certain name for the language specified in the expression.You may need to initiate an update to get the latest state of this field. |
customLineItems.state.state.name | Custom Line Items of a certain State name for the language specified in the expression.You may need to initiate an update to get the latest state of this field. |
Standard field on Payment, Return, or Shipping Info | Query for Orders with |
---|---|
paymentInfo.payments.paymentMethodInfo.method | a certain payment method. You may need to initiate an update to get the latest state of this field. |
returnInfo.items.shipmentState | return items in a certain shipment state. |
returnInfo.items.paymentState | return items with a certain payment state. |
shippingInfo.shippingMethodName | a certain Shipping Method. |
Keyword fields
Standard field on Order | Query for |
---|---|
id | an Order with a specific id . |
orderNumber | an Order with a specific orderNumber . |
createdBy.anonymousId | Orders created by anonymous session with a specific ID. |
createdBy.externalUserId | Orders created by a Customer using external OAuth with a specific user ID. |
lastModifiedBy.anonymousId | Orders last modified by anonymous session with a specific ID. |
lastModifiedBy.externalUserId | Orders last modified by a Customer using external OAuth with a specific user ID. |
origin | Orders with a specific origin . |
customerGroup.id | Orders from Customers of a certain Customer Group specified by its id . |
customLineItems.state.state.key | Custom Line Items with a certain State specified by its key .You may need to initiate an update to get the latest state of this field. |
lineItems.state.state.key | Line Items with a certain State specified by its key .You may need to initiate an update to get the latest state of this field. |
paymentInfo.payments.interfaceId | a Payment of a certain interfaceId .You may need to initiate an update to get the latest state of this field. |
paymentInfo.payments.transactions.id | a Payment Transaction of a certain id .You may need to initiate an update to get the latest state of this field. |
paymentInfo.payments.transactions.interactionId | a Payment Transaction of a certain inferactionId .You may need to initiate an update to get the latest state of this field. |
returnInfo.returnTrackingId | a certain returnTrackingId on the ReturnInfo.You may need to initiate an update to get the latest state of this field. |
shippingInfo.deliveries.parcels.trackingData.trackingId | a certain trackingId on a Parcel's TrackingData.You may need to initiate an update to get the latest state of this field. |
state.key | Orders with a certain State specified by its key .You may need to initiate an update to get the latest state of this field. |
store.key | Orders with a certain Store specified by its key .You may need to initiate an update to get the latest state of this field. |
totalPrice.currencyCode | Orders with a total price of a certain CurrencyCode. |
Custom Fields
Custom Field on Order, Payment, and Transaction | Query for Orders |
---|---|
custom.<field-name> | with a Custom Field of a specific name . |
paymentInfo.payments.custom.<field-name> | with Payments with a Custom Field of a specific name .You may need to initiate an update to get the latest state of this field. |
paymentInfo.payments.transactions.custom.<field-name> | with Payment Transactions with a Custom Field of a specific name .You may need to initiate an update to get the latest state of this field. |
customType
in simple expressions.CustomType
customType
property on simple expressions indicating the data type of the field
.BooleanType
- For CustomFieldBooleanType Custom Fields.
StringType
- For CustomFieldStringType Custom Fields.
LocalizedStringType
- For CustomFieldLocalizedStringType Custom Fields.
EnumType
- For CustomFieldEnumType Custom Fields.
LocalizedEnumType
- For CustomFieldLocalizedEnumType Custom Fields.
NumberType
- For CustomFieldNumberType Custom Fields.
DateType
- For CustomFieldDateType Custom Fields.
TimeType
- For CustomFieldTimeType Custom Fields.
DateTimeType
- For CustomFieldDateTimeType Custom Fields.
SetType.StringType
- For CustomFieldSetType of
StringType
Custom Fields. SetType.LocalizedStringType
- For CustomFieldSetType of
LocalizedStringType
Custom Fields. SetType.EnumType
- For CustomFieldSetType of
EnumType
Custom Fields. SetType.LocalizedEnumType
- For CustomFieldSetType of
LocalizedEnumType
Custom Fields. SetType.NumberType
- For CustomFieldSetType of
NumberType
Custom Fields. SetType.DateType
- For CustomFieldSetType of
DateType
Custom Fields. SetType.TimeType
- For CustomFieldSetType of
TimeType
Custom Fields. SetType.DateTimeType
- For CustomFieldSetType of
DateTimeType
Custom Fields.
Query expression supported for which CustomType
SetType
of the CustomType as for the individual CustomType itself.CustomType | exact | fullText | prefix | range | wildcard | exists |
---|---|---|---|---|---|---|
BooleanType | ✓ | ✓ | ||||
NumberType | ✓ | ✓ | ✓ | |||
StringType , EnumType , DateType , TimeType , DateTimeType | ✓ | ✓ | ✓ | ✓ | ✓ | |
LocalizedStringType , LocalizedEnumType | ✓ | ✓ | ✓ | ✓ | ✓ |
Examples
StringType
Custom Field.{
"query": {
"exact": {
"field": "custom.myOrderField",
"value": "special order",
"customType": "StringType"
}
}
}
SetType
of DateType
Custom Field searching through all values for the Custom Field:{
"query": {
"exists": {
"field": "custom.myDateField",
"value": "2021-05-10",
"customType": "SetType.DateType"
}
}
}
Order Search Query
query
field on OrderSearchRequest, as well as for the Advanced Order Search in the Merchant Center, are documented for multiple Search APIs on the Search query language page.
Search query language terms specific to Order Search are documented on this page.Simple expressions
field
in simple expressions can have any of the searchable Order fields, like orderNumber
, createdAt
, country
including fields of nested objects like LineItems (lineItems.productId
) or ShippingMethods (shippingAddress.firstName
).customType
field must be used instead of the fieldType
field that is documented for the generic search query language.Compound expressions
For example, this composition of two
and
expressions is not supported: Z = (A and
B and
C),using only one
and
expression, like: X = (A and
B), is allowed.Using a different compound expression is allowed too, like for: Y = (A
and
B or
C).Z can still be specified by (X
and
C) since X is a compound expression on a different level then.Example queries
fullText
name
for any Custom Line Item in the Order.{
"query": {
"fullText": {
"field": "customLineItems.name",
"language": "en",
"value": "yellow car",
"mustMatch": "any"
}
}
}
exact
{
"query": {
"exact": {
"field": "lineItems.variant.sku",
"value": "chiquita_yellow_123",
"caseInsensitive": true
}
}
}
prefix
{
"query": {
"prefix": {
"field": "customerEmail",
"value": "commerceto",
"caseInsensitive": true
}
}
}
range
{
"query": {
"range": {
"field": "lastModifiedAt",
"gte": "2018-08-25T12:00:00.000Z",
"lte": "2018-08-26T12:00:00.000Z"
}
}
}
wildcard
{
"query": {
"wildcard": {
"field": "customerEmail",
"value": "ab*@commercetools.com"
}
}
}
{
"query": {
"wildcard": {
"field": "customerEmail",
"value": "ab?@commercetools.com",
"caseInsensitive": true
}
}
}
value
. The email domain can be any as long as it ends with ".com".{
"query": {
"wildcard": {
"field": "customerEmail",
"value": "ab?@*.com",
"caseInsensitive": true
}
}
}
exists
customerEmail
set:{
"query": {
"exists": {
"field": "customerEmail"
}
}
}
Compound expression AND
Example of a query with compound expression finding orders with a specific price:
{
"query": {
"and": [
{
"exact": {
"field": "totalPrice.currencyCode",
"value": "EUR"
}
},
{
"exact": {
"field": "totalPrice.centAmount",
"value": 2222
}
}
]
}
}
Compound expression OR with boost
butter
in the lineItems.name
field are scored as more relevant than those that have butter
in their customLineItems.name
field.{
"query": {
"or": [
{
"fullText": {
"field": "lineItems.name",
"language": "en",
"value": "butter",
"boost": 2
}
},
{
"fullText": {
"field": "customLineItems.name",
"language": "en",
"value": "butter"
}
}
]
}
}
Sorting
The following expression sorts the results ascending by the English Line Item name, but filtered on a specific Product ID:
{
"sort": [
{
"field": "lineItems.name",
"language": "en",
"order": "asc",
"filter": {
"exact": {
"field": "lineItems.productId",
"value": "4054a159-7f3e-4fe9-a30c-8db80ca7d665"
}
}
}
]
}
Note that you can only filter on the same parent field you sort by. In this case on the root of the Order.
Pagination
10 000
results by requesting them page by page.
The total
field in a search query result indicates how many results match the search query in total.Limit
limit
field allows you to set the maximum number of results returned on a page.
Any value between 0
and 100
is allowed, the default limit is 10
.Offset
offset
field allows you to control which page number you want to retrieve.
The default value is 0
, meaning you retrieve the first page of query results containing as many results as specified by limit
.
A value of 1
will skip the first page of results, and your result contains the second bucket of results with the specified limit
.9 900
and 10 000
depending on the limit
parameter.
That is, if you set the limit
parameter to its maximum value of 100
, the maximum offset
is 9 900
.
If you use the default page limit of 10
, you can set the maximum offset
value to 9 990
.10 000
results in total, a higher offset would exceed that limit.
In such a case, the API responds with an error.Search Index updates
As the number of Orders in the Project grows over time and Order States change on the existing Orders, the Order Search index has to be kept in sync with the changes.
Automatic updates
Initiate update
Re-indexing can take several hours, depending on the volume of Orders.
Reindex mutation
manage_project_settings:{projectKey}
, view_orders:{projectKey}
mutation ReindexAllOrders {
reIndexAllOrders {
indexingJobId
existingIndexingJobId
}
}
This mutation returns following indexing job IDs:
indexingJobId
is the ID of a new indexing job.existingIndexingJobId
is the ID of an already running job making progress.
Check indexing progress
For each indexing job ID you can check the status of the respective jobs like so:
manage_project_settings:{projectKey}
, view_orders:{projectKey}
query GetReindexingStatus($jobId: String!) {
getReindexingStatus(id: $jobId) {
nbrOfIndexedDocuments
nbrOfFailedDocuments
totalNbrOfDocuments
percentCompleted
completed
}
}
Stop indexing jobs
You can stop the indexing of all Orders with following mutation:
manage_project_settings:{projectKey}
mutation StopIndexingOrders {
stopOrdersIndexing {
status
}
}
status
of the indexing job.GraphQL endpoint
You can access the GraphQL endpoint with following URL:
https://api.{region}.commercetools.com/{projectKey}/orders/indexer/graphql
The endpoint accepts HTTP POST requests with following fields in a JSON body:
query
- String - GraphQL query as a stringvariables
- Object - Optional - containing JSON object that defines variables for your queryoperationName
- String - Optional - the name of the operation, in case you defined several of them in the query