1. Querying and search

Premium search

Premium search represents OrderCloud's next evolution in search technology, powered by Elasticsearch. This enhancement delivers significant improvements in search capabilities, performance, and user experience.

Key benefits

1. Performance optimization

  • Significantly improved response times
  • Enhanced large dataset handling
  • Optimized query processing
  • Improved system responsiveness

2. Enhanced search capabilities

Natural language processing:

  • Word stemming for plural inference
  • Comprehensive synonym matching
  • Intelligent result ranking
  • Google-like search experience

Search flexibility:

  • Multiple search patterns
  • Context-aware matching
  • Relevance-based results
  • Intuitive user experience

3. Advanced features

Metadata and navigation

  • Rich faceted navigation support
  • Dynamic metadata generation
  • Flexible categorization
  • Enhanced filtering options

Extended property handling

  • Full xp field searchability

  • Wildcard pattern support:

    searchon=xp.foo.*

  • Automatic field indexing

  • No manual index creation

Search operations

  • Universal field sorting

  • Multi-field OR filters:

    Name|ID|xp.SKU=value

  • Complex query support

  • Flexible search patterns

API coverage

Available endpoints

  • Buyer product lists:

    me/products

  • Seller product management:

    /products

  • Order operations:

    /orders

Integration points

  • Product catalog searches
  • Order management queries
  • Custom implementations
  • API integrations

Implementation details

Cost structure

  • Included in core platform
  • No additional charges
  • Standard feature access
  • Gradual rollout process

Compatibility considerations

Endpoint compatibility

  • Maintains existing endpoints
  • Preserves parameter functionality
  • Supports current integrations
  • Ensures API consistency

Search behavior changes

Natural language focus:

  • Semantic matching priority
  • Context-aware results
  • Example changes:
    • "eats" matches "eat" (word stem)
    • "eats" doesn't match "beats" (unrelated)
    • Previous behavior was opposite

Exact matching options:

  • Use wildcard filters

  • Consider performance impacts

  • Example pattern:

    Name=*exact*pattern*

  • Leading wildcard considerations

Performance considerations

  1. Query optimization:

    • Prefer targeted searches
    • Avoid leading wildcards
    • Use specific filters
    • Implement pagination

  2. Result handling:

    • Process manageable sets
    • Implement caching
    • Handle large datasets
    • Monitor performance

Production status

Current deployment

  • Live since mid-2018
  • Extensive production testing
  • Major customer adoption
  • Proven reliability

Implementation status

  • Production-ready feature
  • Default for new systems
  • Comprehensive testing
  • Continuous improvements

Rollout strategy

  • Gradual client migration
  • Controlled deployment
  • Performance monitoring
  • System optimization

Best practices

Search implementation

  1. Prefer natural language:

    • Use semantic searches
    • Implement word stemming
    • Enable synonym matching
    • Support variations

  2. Performance optimization:

    • Avoid leading wildcards
    • Use targeted searches
    • Implement pagination
    • Monitor response times

  3. Result handling:

    • Process manageable sets
    • Implement caching
    • Handle large datasets
    • Provide feedback

Migration considerations

  1. Review current searches:

    • Identify exact matches
    • Update search patterns
    • Test modifications
    • Verify results

  2. Update integrations:

    • Modify search calls
    • Adjust result handling
    • Test functionality
    • Monitor performance

Support resources

Community access

Join the OrderCloud Developer Community for:

  • Implementation guidance
  • Best practices
  • Problem solving
  • Feature updates

Documentation

  • Technical specifications
  • Implementation guides
  • API references
  • Example code

Since introducing Elasticsearch-powered Premium Search for products, we've made significant improvements based on implementation feedback and performance monitoring.

Premium search for admin endpoints

The Premium Search engine now powers both v1/me/products (buyer experience) and v1/products (admin experience).

Rollout schedule:

  1. New organizations enabled by default (since February 2020)
  2. Selected clients/partners transitioned individually
  3. Test/Dev organizations transitioned (April 3, 2020)
  4. All remaining organizations transitioned (April 20, 2020)
  5. Remove Product xp indexes and disable new index creation*

*Premium Search automatically enables searching, sorting, and filtering for all xp fields.

Important behavioral note

While API specifications remain unchanged, cached data behavior requires attention:

  • Write operations (POST/PUT/PATCH) return fresh, consistent data
  • GET operations may return cached data
  • Immediate GET after write may return stale data

Organizations created after February 12, 2020 already have these behaviors enabled.

New searchType parameter

To provide more control over search results, we've introduced the searchType parameter:

TypeDescription
AnyTermDefault. Any search word must appear in any searchable field
AllTermsAnyFieldAll search words must appear across searchable fields
AllTermsSameFieldAll search words must appear in the same searchable field
ExactPhraseExact phrase match (case insensitive) in any searchable field
ExactPhrasePrefixLike ExactPhrase, but allows incomplete last word (ideal for type-ahead)

The parameter is available on:

  • v1/products
  • v1/me/products

Usage recommendations

Consider these search behavior principles:

  • Result ranking remains consistent across search types
  • Exact phrase matches rank higher than individual terms
  • More term matches rank higher than fewer
  • ID and Name matches rank higher than Description
  • Users rarely explore beyond first page of well-ranked results
  • Overly restrictive searches may hide relevant results

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

Using order search to suit your needs

Premium search for orders and line items provides enhanced search and filtering capabilities for the orders endpoint. This feature enables custom order management screens, reporting interfaces, and unique buyer order history experiences.

Line item search capabilities

Sales metrics

Get total quantity sold or gross sales by product:

http
GET v1/lineitems/{direction}?ProductID={ProductID}

Fulfillment tracking

Find unfulfilled items:

http
GET v1/lineitems/{direction}?QuantityShipped=0

Promotion analysis

Track discounted purchases:

http
GET v1/lineitems/{direction}?PromotionDiscount=>0

Track non-discounted purchases:

http
GET v1/lineitems/{direction}?PromotionDiscount=0

Time-based analysis

Get items sold in specific period:

http
GET v1/lineitems/{direction}?Order.DateSubmitted=>=01-01-2022&Order.DateSubmitted=<=07-01-2022

Note: All dates use UTC format

User history

View customer purchase history:

http
GET v1/lineitems/{direction}?Order.FromUserID={BuyerUserID}

Supplier analysis

Compare supplier performance:

http
GET v1/lineitems/All?Order.ToCompanyID={SupplierID}

Note: Requires supplier/seller user with OrderAdmin and OrderReader roles.

Order filtering

Product-based filtering

Find orders containing specific products:

http
GET v1/orders/{direction}?LineItems.Product.ID={ProductID}

Address filtering

Orders with California billing:

http
GET v1/orders/Incoming?BillingAddress.State=CA

Multiple state filtering:

http
GET v1/orders/Incoming?BillingAddress.State=CA|CO

Search optimization

Search types

Available search types:

  • Default: AnyTerm
  • Expanded: Product and order data
  • Configurable ranking

Example scenario

Sample product names:

  • Button-up Black Shirt
  • Sleeveless Black Shirt
  • Cotton Blue Shirt
  • High-top Black Shoes
  • Canvas White Shoes

Find orders with any shirts:

http
GET v1/me/orders/{direction}?searchOn=LineItems.Product.Name&search=Shirt

Find orders with black shirts:

http
GET v1/me/orders/{direction}?searchType=ExactPhrase&searchOn=LineItems.Product.Name&search=Black Shirt

Line item retrieval

Get order line items:

http
GET v1/orders/{direction}/{orderID}/lineitems

Alternative URL format:

http
GET v1/orders/{direction}?searchType=ExactPhrase&searchOn=LineItems.Product.Name&search=Black Shirt

Fuzzy search in comments:

http
GET v1/orders/Incoming?search={searchTerm}

Implementation notes

Order submission status

  • Default: Returns submitted orders
  • Unsubmitted orders require explicit filter:
http
GET v1/orders/{direction}?IsSubmitted=false

Extended properties

Filter by xp without indexing:

http
GET v1/orders/{direction}?xp.ShippingOption={shippingOption}

Pagination optimization

Use NextPageKey for better performance:

http
GET v1/lineitems/{direction}?Order.DateSubmitted={date}&pageKey={Meta.NextPageKey}
If you have suggestions for improving this article, let us know!