1. Search

Premium search for orders

The Elasticsearch-powered premium search features now extend to orders and line items, bringing advanced search capabilities previously available only for products. These enhancements apply exclusively to submitted orders (IsSubmitted=true), providing improved search performance and functionality.

Enhanced order search capabilities

The GET v1/orders/{direction} endpoint now includes powerful search features:

  • "Fuzzy" matching on fields like Order.Comments
  • Intelligent relevance-based result ranking
  • Improved search accuracy and flexibility

Advanced filtering

  • Line item property filtering:

    GET v1/orders/incoming?LineItems.Product.Name=xyz

  • Nested field filtering:

    BillingAddress.City=Chicago

  • Field-level "OR" filters:

    Name|ID=xyz

Additional features

  • Support for the searchType parameter
  • Automatic xp field indexing for submitted orders
    • No manual index configuration required
    • All xp fields immediately searchable
  • Significantly improved performance
    • Faster complex queries
    • Better handling of xp filters
    • Optimized search operations

The new endpoint v1/lineitems/{direction} enables comprehensive line item searching across multiple orders, addressing limitations of the single-order endpoint v1/orders/{direction}/{id}/lineitems.

Key capabilities

  • Search across all orders simultaneously
  • Filter by line item properties
  • Filter by order-level fields using Order prefix
  • Combine multiple filter criteria

Example query:

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

Response details

  • Includes standard LineItem fields
  • Adds OrderID for order reference
  • Supports all enhanced search features
  • Enables complex data analysis

Use cases:

  • Product sales analysis
  • Order history investigation
  • Cross-order item tracking
  • Performance reporting

Important considerations

1. Submitted orders only

  • Applies to orders with IsSubmitted=true
  • Orders awaiting approval not considered submitted
  • Cannot combine submitted and unsubmitted orders in queries
  • Default behavior:
    • Assumes submitted orders
    • Override with:
      • IsSubmitted=False
      • Status=Unsubmitted
      • Status=AwaitingApproval

2. Natural language search implications

  • Results may differ from exact matching
  • Provides more intuitive search behavior
  • Alternative options:
    • Use wildcard filters for exact matching
    • Avoid leading wildcards for performance
    • Consider search term relevance

3. Search result caching

  • Changes to submitted orders not immediately visible
  • Update timing:
    • Typical: Few seconds
    • Maximum: Few minutes
  • Plan for slight data latency

4. XP field management

  • Adding new fields: Safe operation
  • Changing data types: Exercise caution
    • May affect Elasticsearch indexing
    • Could reject entire order from index
    • Same applies to line items
  • Best practices:
    • Maintain consistent schemas
    • Plan field types carefully
    • Document data type changes

5. Sorting requirements

Cross-order line item sorting rules:

  • Must start with order-level field

  • Valid example:

    sortBy=Order.DateSubmitted,Product.ID

  • Invalid example:

    sortBy=Product.ID

6. Filter combinations

Restrictions on field combinations:

  • Cannot combine order and item fields in OR expressions

  • Invalid example:

    ShippingAddress.City|Order.BillingAddress.City=Chicago

Beta status notes

  • Subject to potential adjustments
  • Focus on performance optimization
  • Possible limits on result set sizes
  • Changes will be communicated in advance

NextPageKey pagination

The Meta.NextPageKey field introduces efficient pagination for line items across orders.

Implementation

  1. Initial request:

    GET v1/lineitems/incoming?pageSize=100

  2. Subsequent requests:

    GET v1/lineitems/incoming?pageKey={value_from_meta_nextpagekey}

Best practices

  • Omit page and pageSize with pageKey

  • Use Meta.NextPageKey from previous response

  • Implement date range filtering:

    Order.DateSubmitted>2023-01-01&Order.DateSubmitted<2023-02-01

  • Break large datasets into manageable chunks

Performance considerations

  • Pagination depth affects performance
  • Use filters to reduce result sets
  • Consider date-based filtering
  • Implement reasonable page sizes

Feature availability

Non-production environments

  • Enabled by default
  • Available for testing
  • No activation required

Production environments

  • Automatic for marketplaces created after April 20, 2022
  • Older marketplaces:
    • Requires manual activation
    • Contact OrderCloud support
    • Quick enablement process
If you have suggestions for improving this article, let us know!