fulfillmenttools
API documentationIncident ManagementFeedback
Developer Docs
Developer Docs
  • Developer docs
  • Getting Started
    • Quickstart
    • Integration tutorial
      • Adding facilities
      • Adding listings to facilities
      • Configuring stocks
      • Carrier configuration
      • Placing orders
      • Checkout options
      • Distributed Order Management System (Routing)
      • Local fulfillment configuration
    • Free trial
  • Technical Basics
    • Access to fulfillmenttools
    • Feature status
    • Available regions
    • Backup policies
  • Connecting to fulfillmenttools
    • Client SDKs
    • commercetools connect
    • OpenID connect
      • Configure Microsoft Entra ID / Azure Active Directory
      • Configure Keycloak
  • API
    • Core concepts
      • Authentication & authorization
      • API Versioning & lifecycle
      • Assign user to jobs
      • Localization
      • Resource timestamps
      • Custom attributes
      • Article attributes
      • Recordable attributes
      • Data update guarantees
      • Rate limits & scaling
      • Retries
      • Performance on test vs. production systems
      • Load testing
    • API calls
      • Postman
      • cURL
      • GraphQL Explorer
    • GraphQL API
    • RESTful API
      • Pagination interface
      • RapiDoc
      • OpenAPI 3.0 Spec
    • Eventing
      • Structure of an event
      • Available events
        • Event flows
      • Eventing example
      • Event export
  • Integration Guides
    • Address formats for specific carriers
    • Basics
      • Article categories
      • Audits
      • Custom services & bundled line items
      • Facilities
      • Facility groups
      • GDPR configuration
      • Listings
      • Orders
        • Order types
        • Order status
      • Remote configuration
      • Receipts
      • Search
      • Subscribe to events
      • Sticker
      • Stocks
      • Storage locations
      • Tags
      • Users
    • Channel inventory
    • Facility discounts
    • Inbound process
    • Outbound stocks
    • Purchase order
    • Receipt
    • Routing strategy
    • Show sticker to clients
    • Stow jobs
  • More Integration Guides
    • Carrier management
      • Introduction to carrier configuration
      • Required data when operating carriers
      • Adding & connecting carriers to facilities
      • Custom carrier
    • Configurations for order fulfillment
      • Picking configuration
      • Packing configuration
      • Handover configuration
      • Printing and document configuration
      • Packing container types
      • Parcel tag configuration
      • Headless order fulfillment
      • Short-pick reasons
      • External documents in order fulfillment
      • Service jobs
      • Load units
      • Running sequence
    • DOMS - distributed order management system (routing)
    • External actions
    • Interfacility transfer
    • Notifications
    • Availability & promising
    • Returns
Powered by GitBook
On this page
  • Introduction
  • Fields with Default Query Limits
  • Search function limitations
  • Example API calls
  • Searching for exact equal matches
  • Searching with gt, gte, lt and lte operators
  • Sorting search results
  • Adding a search result total count
  • Searching for several fields in conjunction with and/or
  • Searching for nested fields
  • Searching for custom attributes
Edit on GitHub
  1. Integration Guides
  2. Basics

Search

Last updated 1 day ago

Introduction

More Search-API information can be found in the API documentation for the respective search endpoint (for example, for inbound process: )

Searchable fulfillmenttools entities have their own search endpoint, located at: POST /api/{ENTITY-NAME}/search. Every fulfillmenttools entity defines which fields are queryable in its search endpoint.

  • Strings and numbers can be searched with the operators

    • eq and notEq (search value needs to be a string) or

    • in and notIn (search value needs to be an array of strings)

  • Arrays of strings can be searched with the contains operator

  • Numbers and date values can be searched with the operators gt (>), gte (>=), lt (<) and lte (<=)

  • customAttributes are fully searchable. However, to optimize performance, we recommend storing search-relevant keys in a dedicated property (e.g., searchTerms) and minimizing nesting depth.

Fields with Default Query Limits

Some entities (particularly those representing historical data) include default filters in queries. These default search fields are designed to limit the amount of data returned, improving performance and relevance.

For example, operational entities such as orders typically return only recently created records by default, as older data is often not relevant for current operations.

These default values can be overwritten if needed. However, we recommend caution when expanding filters, especially when querying large datasets, to avoid performance issues.

Search function limitations

The search functionality has restrictions due to database constraints and performance considerations. These limitations ensure stability and efficiency when handling queries.

  1. No dots (.) in custom search field names: Field names containing dots (.) can cause conflicts with internal database structures and indexing mechanisms. To prevent issues, dots are not allowed in custom search field names.

  2. No custom search fields starting with a dollar sign ($): Field names beginning with a dollar sign ($) conflict with database operators, which use this syntax for system commands. To avoid ambiguity, such field names are not permitted.

  3. Cross-entity search via referenced filter is limited to top-level queries: Cross-entity searches using the referenced filter can only be applied at the top level. Nesting them within AND or OR conditions is not supported due to query optimization constraints.

Example API calls

Searching for exact equal matches

Example: Search for stocks in a facility with facilityRef d083f631-9f4c-463b-85d4-9414fb19239f.

POST https://{YOUR-TENANT-NAME}.fulfillmenttools.com/api/stocks/search
{
    "query": {
        "facilityRef": {
            "eq": "d083f631-9f4c-463b-85d4-9414fb19239f"
        }
    }
}

Searching with gt, gte, lt and lte operators

Example: Search for storage locations created before the 2nd October 2024.

POST https://{YOUR-TENANT-NAME}.fulfillmenttools.com/api/storagelocations/search
{
    "query": {
        "created": {
            "lt": "2024-10-02T14:43:21.257Z"
        }
    }
}

Sorting search results

POST https://{YOUR-TENANT-NAME}.fulfillmenttools.com/api/{ENTITY-NAME}/search
{
    "sort": [
        {
            "<attribute_to_sort_by>": "ASC"
        }
    ],
    "query": {
      ...
    }
}

Adding a search result total count

The total count can significantly slow down the response time of the request.

POST https://{YOUR-TENANT-NAME}.fulfillmenttools.com/api/{ENTITY-NAME}/search
{
    "options": {
        "withTotal": true
    },
    "query": {
      ...
    }
}

withTotal cannot be used in combination with after (pagination). This restriction exists because the total count may change while paginating, which could lead to misleading or inconsistent results.

Searching for several fields in conjunction with and/or

Example: Search for stocks in facility with facilityRef d083f631-9f4c-463b-85d4-9414fb19239f and that are placed on locations 6779689d-4852-4fcf-b13b-78f5ce4954d8 and 3b8be595-6a00-40cf-be09-12195e44eb99.

POST https://{YOUR-TENANT-NAME}.fulfillmenttools.com/api/stocks/search
{
    "query": {
        "and": [
            {
                "facilityRef": {
                    "eq": "d083f631-9f4c-463b-85d4-9414fb19239f"
                }
            }, {
                "locationRef": {
                    "in": [
                        "6779689d-4852-4fcf-b13b-78f5ce4954d8",
                        "3b8be595-6a00-40cf-be09-12195e44eb99"
                    ]
                }
            }
        ]
    }
}

Searching for nested fields

Example: Search for inboundProcesses with a purchaseOrder with ID 678ujnuzb67vg8h8oji.

POST https://{YOUR-TENANT-NAME}.fulfillmenttools.com/api/inboundprocesses/search
{
    "query": {
        "purchaseOrder": {
            "id": {
                "eq": "678ujnuzb67vg8h8oji"
            }
        }
    }
}

Searching for custom attributes

Fields in customAttributes can be made searchable by defining key-value pairs within the searchTerms property. All defined key-value pairs are then queryable in the search endpoints. The customAttributes can contain strings and numbers. For strings, the in and notIn operators are allowed. For numbers, the operatorslt, lte, gt, gte are additionally available.

It is important to use numbers when searching for a number attribute and strings when searching for a string attribute. Otherwise, the search will not give back the desired results. For example, if the search value is the number 5, a query search for eq: "5" would not be successful.

Example: Create a new storage location with user-defined custom attributes that should be searchable and execute the search.

  1. Create a new entity with user-defined custom attributes that should be searchable (searchTerms)

POST https://{YOUR-TENANT-NAME}.fulfillmenttools.com/api/{facilityId}/storagelocations
...
"customAttributes": {
  "searchTerms": {       
    "TYPE": "FROZEN"     
  }
}
... 
  1. Construct a search query on custom attributes

POST https://{YOUR-TENANT-NAME}.fulfillmenttools.com/api/storagelocations/search
{
  "query": {
    "customAttributes": {
      "searchTerms": {
        "TYPE": {
          "eq": "FROZEN"
        }
      }
    }
  }
}
REST API documentation - Inbound Process