1. Search

Advanced querying

OrderCloud's list endpoints can return thousands or hundreds of thousands of items. The platform provides comprehensive querying tools to help you locate and extract specific data efficiently. These tools enable precise data retrieval for both system operations and user interactions.

Filtering capabilities

Filtering provides precise value matching for specific fields. This method offers improved performance over text searching when exact matches are needed.

Extended property filtering

For filtering on extended property (XP) fields, use dot notation to access nested values. Example XP structure:

json
{
  "xp": {
    "MoreInfo": {
      "TeamName": "Tigers",
      "Gender": "Male"
    }
  }
}

To filter users by team name:

http
GET https://api.ordercloud.io/v1/buyers/{buyerID}/users?xp.MoreInfo.TeamName=Tigers

Pattern matching

The system supports pattern matching using the * wildcard character:

http
GET https://api.ordercloud.io/v1/buyers/{buyerID}/users?LastName=*Smith&FirstName=John*

This returns matches like "John Smith" and "Johnny McSmooth".

Logical operators

OR operations

Use the | character for OR conditions:

http
GET https://api.ordercloud.io/v1/buyers/{buyerID}/users?LastName=Smith|Jo*&FirstName=Johnny

This returns matches like:

  • "John Smith"
  • "Johnny Jones"
  • "John Johnson"

AND and NOT operations

  • Use ! to negate conditions
  • Multiple parameters create AND conditions

Example excluding specific last names:

http
GET https://api.ordercloud.io/v1/buyers/{buyerID}/users?LastName=!Smith&LastName=!Jones

Numeric and date comparisons

Use > and < for value comparisons:

http
GET https://api.ordercloud.io/v1/buyers/{buyerID}/users?DateCreated=>2015-01-01

For inclusive ranges, combine operators:

http
GET https://api.ordercloud.io/v1/buyers/{buyerID}/users?ID=!<0&ID=!>9

This returns IDs from 0 to 9 inclusive.

Null value handling

To find records with undefined or null values:

http
GET https://api.ordercloud.io/v1/orders/all?xp.Billed=!*

For empty string values:

http
GET https://api.ordercloud.io/v1/products?xp.MyProp=

Performance optimization

The system maintains indexes for efficient data retrieval, including XP fields. Consider these performance factors:

  1. Query complexity impact:

    • Multiple OR conditions
    • Leading wildcard patterns
    • Large data sets

  2. Optimization strategies:

    • Use appropriate data grouping
    • Leverage User Groups
    • Implement Categories effectively

Sort operations

Control result ordering using the sortBy parameter:

Ascending order:

http
GET https://api.ordercloud.io/v1/me/orders/incoming?sortBy=LastName

Descending order:

http
GET https://api.ordercloud.io/v1/me/orders/incoming?sortBy=!LastName

Query combinations

Search, filter, and sort operations can be combined for precise data retrieval and presentation.

Pagination implementation

List responses contain metadata and results:

json
{
  "Meta": {
    "Page": 1,
    "PageSize": 20,
    "TotalCount": 25,
    "TotalPages": 2,
    "ItemRange": [1, 20]
  },
  "Items": ["..."]
}

Pagination features:

  • Default page size: 20 items
  • Maximum page size: 100 items
  • Zero-based ItemRange values
  • Page numbering starts at 1

LastID pagination method

For efficient pagination of large datasets (>30 pages), implement this pattern:

  1. Initial request:

    http
    GET /endpoint?page=1&pageSize=100&sortBy=ID

  2. Subsequent requests:

    http
    GET /endpoint?page=1&pageSize=100&sortBy=ID&ID=>{lastID}

  3. Implementation notes:

    • Track the last item's ID
    • Continue until receiving empty results
    • Maintain consistent ID formats for proper sorting

Note: For premium search resources, ensure consistent ID number types to prevent comparison issues.

If you have suggestions for improving this article, let us know!