Order Search

Activation of the API

The Order Search API is not active for the Project by default. If the API is deactivated for your Project, the Search Orders endpoint returns a 404 Not Found error.

To activate the API for your Projects, please 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).

Once the Project setting has been changed, the indexing of all Orders existing in the Project will start and the Search Orders endpoint will become fully functional soon after.

Automatic deactivation

The Order Search API is automatically deactivated for a Project if there have been no calls to the Search Orders endpoint in the last 30 days. The API can be reactivated again using any of the options listed in Activation of the API.

Representations

OrderSearchRequest

{
  "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

Hit

Search Orders

{
  "total": 3,
  "offset": 0,
  "limit": 50,
  "hits": [
    {
      "id": "c2d430e8-1ccf-44c8-8976-36763b572f3e",
      "version": 12,
      "relevance": 0.9871
    },
    {
      "id": "ee8e3533-00d2-43c2-a2f4-57b1eee0f5b4",
      "version": 2,
      "relevance": 0.735654
    },
    {
      "id": "9a9e129c-2ed1-436d-90d9-af60d83490ed",
      "version": 44,
      "relevance": 0.42415
    }
  ]
}

Check if Order Search index exists

curl --head https://api.{region}.commercetools.com/{projectKey}/orders/search -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}'

On the GraphQL endpoint you can use following query:

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 the reIndexAllOrders mutation to get the job ID.

Find below an example for a 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

The following list contains the Order fields that are supported in query expressions.

Some fields containing data of referenced resources are not updated automatically. Their values are kept in the their original state, even if the referenced resource was changed. You need to initiate an update to get the most recent values for those fields.

Number and date fields

Use the following fields in exact, exists, and range query expressions. Data type indicates the type of field for the field.

Phone fields

Use the following text type fields in exact, fullText, prefix, and exists query expressions. On these fields all non numeric characters are ignored in search requests. For example, a query of type fullText for (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.

Text fields

Use the following text type fields in exact, fullText, prefix, wildcard, and exists query expressions.

Keyword fields

Use the following keyword type fields, containing unique IDs or keys, in exact, prefix, wildcard, and exists query expressions. To query for multiple values of the same field or for several fields in the same request, combine the query expressions with a compound expression.

Custom Fields

In addition to the standard fields on an Order, you can also search for its Custom Fields, if any.

To determine the data type of the Custom Field, you must provide the customType in query expressions.

CustomType

Query expression supported for which CustomType

A checkmark indicates which query expression you can use for which CustomType of field. You can apply the same expressions for the SetType of the CustomType as for the individual CustomType itself.

Examples

An exact query on a StringType Custom Field.

{
  "query": {
    "exact": {
      "field": "custom.myOrderField",
      "value": "special order",
      "customType": "StringType"
    }
  }
}

An exists query on a 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

The query expressions to be used for the 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.

Query expressions

The field in query 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).

Compound expressions

For compound expressions, the following restriction applies to Order Search:

A compound expression can only be used one time on the same level of composition.
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

A fulltext query for Orders that have "yellow car" as the English name for any Custom Line Item in the Order.

{
  "query": {
    "fullText": {
      "field": "customLineItems.name",
      "language": "en",
      "value": "yellow car",
      "mustMatch": "any"
    }
  }
}

exact

An exact query for Orders that have the SKU "chiquita_yellow_123" in any of the Line Items in the Order. The case of the SKU is ignored.

{
  "query": {
    "exact": {
      "field": "lineItems.variant.sku",
      "value": "chiquita_yellow_123",
      "caseInsensitive": true
    }
  }
}

prefix

A prefix query for Orders with customer emails starting with "commercetoo". The case of the email address is ignored.

{
  "query": {
    "prefix": {
      "field": "customerEmail",
      "value": "commerceto",
      "caseInsensitive": true
    }
  }
}

range

A range query for Orders last modified between two specific dates:

{
  "query": {
    "range": {
      "field": "lastModifiedAt",
      "gte": "2018-08-25T12:00:00.000Z",
      "lte": "2018-08-26T12:00:00.000Z"
    }
  }
}

wildcard

A wildcard query for Orders with customer emails that start with "ab" and may or may not contain any additional characters.

{
  "query": {
    "wildcard": {
      "field": "customerEmail",
      "value": "ab*@commercetools.com"
    }
  }
}

A wildcard query for Orders with customer emails that start with "ab" and have exactly one additional character after that. Case is ignored.

{
  "query": {
    "wildcard": {
      "field": "customerEmail",
      "value": "ab?@commercetools.com",
      "caseInsensitive": true
    }
  }
}

The similar wildcard query as before, but now with another wildcard in the same value. The email domain can be any as long as it ends with ".com".

{
  "query": {
    "wildcard": {
      "field": "customerEmail",
      "value": "ab?@*.com",
      "caseInsensitive": true
    }
  }
}

exists

An exists query for Orders that have the field 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

Orders that have 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

Sorting allows you to control how the results of your search query are sorted. If no sort is specified, the results are sorted by relevance in descending order. For more information about sorting the Order Search result, see the search query language documentation.

Example:

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"
        }
      }
    }
  ]
}

Pagination

Pagination allows you to retrieve a large number of search results by requesting them page by page. For the OrderSearchRequest, the default limit for a page is 10, all other parameters of this feature behave as described in the documentation for the search query language.

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

The Order Search index is automatically updated whenever there is a change to an Order. However, this update mechanism only applies to changes to the Order resource itself. Data for resources referenced by an Order, such as Payments, States, or Stores, are initially indexed if they exist when the Order is created, but subsequent changes to these resources will not trigger an update to the Order Search index. You can update the information in these searchable Order fields by initiating an update as described in the next section.

Initiate update

If you notice that the Search Orders endpoint is not returning the most recent Orders, you can initiate a search index rebuild. When a Project is re-indexed, all existing Orders from the last 3 months are re-processed to update the search index. This ensures that any changes made to the Orders, including state transitions or updates to Order details, are accurately reflected in search results.

This service is provided on a GraphQL endpoint by submitting a specific reindex mutation.

Reindex mutation

OAuth 2.0 Scopes: 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:

OAuth 2.0 Scopes: 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:

OAuth 2.0 Scopes: manage_project_settings:{projectKey}

mutation StopIndexingOrders {
  stopOrdersIndexing {
    status
  }
}

The response contains the 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 string
• variables - Object - Optional - containing JSON object that defines variables for your query
• operationName - String - Optional - the name of the operation, in case you defined several of them in the query

GraphiQL

To explore the GraphQL endpoint, you can use an interactive GraphiQL environment with a web browser, accessible through the following URL:

https://api.{region}.commercetools.com/{projectKey}/orders/indexer/graphiql?token={access_token}