Premium Search for Orders

Many of the Elasticsearch-backed capabilities currently available only for products are now being rolled out for orders and line items. Here are the details of these new capabilities.

Better search and filtering for existing orders endpoint

With premium search, the existing GET v1/orders/{direction} endpoint will be enhanced with the following capabilities:

• "Fuzzy" natural-language search on fields like Order.Comments, along with intelligent ranking of search results based on relevance.

• Support for filtering on line item-level properties, even nested ones, e.g. GET v1/orders/incoming?LineItems.Product.Name=xyz

• Support for filtering on any other nested fields, e.g. BillingAddress.City=Chicago.

• Support for field-level "OR" filters, e.g. Name|ID=xyz.

• Support for the searchType parameter.

• All xp fields are searchable and filter-able automatically; there's no need to define xp indexes to filter on Submitted orders.

• Improved performance, especially in more complex scenarios involving xp filters, etc.

Query line items across orders

Until now, line items could only be queried for a single order using the endpoint v1/orders/{direction}/{id}/lineitems. This can be limiting in scenarios such as pulling sales numbers for a given product. Querying line items across orders is now possible via the new endpoint v1/lineitems/{direction}. In addition to filtering on line item fields (top-level or nested), you can also filter on order-level fields by using the Order prefix:

GET v1/lineitems/incoming?Product.ID=xyz&Order.DateSubmitted>1/1/2022

Along with the usual LineItem fields returned in the order-specific endpoint, queries across orders will include an OrderID field.

The line items endpoint also benefits from the enhanced search capabilities listed above for the orders endpoint.

Some limitations and gotchas

Like with most good things in life, the new capabilities come with a few notable strings attached.

1. The new functionality is available for submitted orders only. (Note that orders awaiting approval are not considered submitted.) A direct consequence of this is that it is no longer possible to query submitted and unsubmitted orders in the same call. Submitted is the default unless any of the following filters is used: IsSubmitted=False, Status=Unsubmitted, or Status=AwaitingApproval.

2. Since search now follows a natural-language paradigm, expected results could differ slightly from the exact character sequence matching that you get today if you "search" orders. You should be able to mimic today's behavior by using filters with wildcards, although as always we recommend against filter patterns that start with a wildcard, as these do not tend to perform well with larger data sets.

3. Like with products, you need to be aware that lists of submitted orders and line items will be served from a cache that is not guaranteed to be up-to-the-moment current with changes you make. Changes to submitted orders should normally take between a few seconds and a few minutes to be reflected in search/list results.

4. Also like with products, you'll need to be careful about keeping your xp schemas consistent. Introducing new xp fields shouldn't cause problems, but changing the data type of existing fields might. If the underlying Elasticsearch index cannot coerce values into types already inferred on previous orders, it may reject the entire order from being indexed; likewise for line items.

5. Sorting line items across orders currently requires the sort-by list to start with an order-level field. So, sortBy=Product.ID is not allowed across orders; sortBy=Order.DateSubmitted,Product.ID is allowed.

6. Although you can filter line items across orders by both order-level and item-level fields, you cannot include both in an "OR" expression. For example, ShippingAddress.City|Order.BillingAddress.City=Chicago is not allowed.

A final potential "gotcha" that hopefully won't come to fruition but is worth mentioning is that for the first few months (until such a time that it's no longer opt-in), Order Search should be considered a "beta" feature and subject to change. We don't take that lightly and will make every effort to avoid it, and any planned change will be communicated far in advance. Breaking API changes are highly unlikely; the slightly more likely scenarios would be needing to impose tighter limits on things like result set sizes due to performance concerns.

What's the deal with Meta.NextPageKey?

You may have noticed a new field recently started appearing in the Meta section of list responses: NextPageKey. Although it's now part of the standard response model for lists, the truth is we haven't implemented it anywhere except line items across orders (yet), so anytime it's null it should be ignored. But for line items across orders, it can and should be used as a higher-performance alternative to standard paging.

How is it used? Say you make a request for the first page of line items, specifying pageSize=100. Instead of passing page=2&pageSize=100 to fetch the next page, grab the value from Meta.NextPageKey in page 1's response and pass it as pageKey in the URI of your page 2 request. As a matter of best practice, don't pass page or pageSize when using pageKey. These values are already encoded in pageKey based on the previous request, along with some other metadata that OrderCloud can leverage to improve the performance of the next page fetch.

But keep in mind that "higher performance" is not the same thing as "high performance". Paging through large volumes of data is still inherently slow the deeper you go, even with this enhancement. We therefore strongly recommend using filters to break up large data sets. In the case of orders and line items, using Order.DateSubmitted to fetch in groups of date ranges is often a great choice.

How do I test this?

This feature is now enabled in all non-production marketplaces. Any production marketplace created after April 20, 2022 also has premium search for orders enabled. If your production marketplace was created prior to that date and you would like the feature enabled please reach out to your OrderCloud support contact.

Still have questions?
Ask in our Community Channel

Content Powered By