Filtering

You can filter results returned from the API using a standard URI format. The following v2/product endpoints support filtering.

• /brands
• /categories
• /collections
• /customers
• /files
• /orders
• /products
• /authentication-realms/{{authenticationRealmId}}/user-authentication-info
• /accounts
• /accounts/{{accountId}}/account-memberships
• /accounts/{{accountId}}/account-memberships/unassigned-account-members

Note that:

• You can only filter on base object attributes, such as, name, description, slug and sku. Filtering through non-base attributes is not supported and returns everything.
• There is a maximum of 10 filters allowed on a single request.
• A request containing filters must not exceed 8KB.
• Passing an incorrectly formatted filter or using an unsupported operator returns a 400 response with the following error:

{
    "errors": [
        {
            "title": "Bad Request",
            "detail": "Could not parse the supplied filter"
        }
    ]
}

As filters are passed as URL query string parameters, we must ensure all filters are URL safe and are strict about the characters that can be used in a filter.

If you need to specify a date, specify the date in yyyy-mm-dd format, for example 2022-04-27. You can also specify the date as an integer number of milliseconds since 1970-01-01 00:00:00. It is also known as Unix time. For example, 640912546584.

We recommend URL encoding filters. For ease of use, you can encode the full filter, so filter=eq(email,ron+1@swanson.com) would become filter=eq%28email%2Cron%2B1%40swanson.com%29.

Filtered queries are in general less performant than non-filtered queries, especially at scale (either with high frequency requests or with a high amount of data) and care should be taken when using them. In particular:

1. The like operator can take a noticably longer amount of time especially when there is a leading wildcard or wildcard on both sides of the search term.
2. The in operator with a large number of options can also result in degraded performance.

Some strategies in these cases can be:

1. Using eq when possible instead of like
2. Adding another search operator can often narrow down the request. For example, adding eq(status,paid), or gt(updated_at,<DATE>) to like(contact.name,<SEARCH>) may have higher performance.
3. Storing a copy of the filtered results in a Custom Data (Flows) and querying that. The flow can be populated using a combination of batch processing or Events.

v2/products endpoints support the following operators.

For more detail on filtering, see the Filtering section under each endpoint.

In the following example, we make a request to get all digital products from the catalog.

curl -X GET https://api.moltin.com/v2/products?filter=eq(commodity_type, digital) \
     -H "Authorization: Bearer XXXX"

// Where `EPCC` is an authenticated client
await EPCC.Products.Filter({ eq: { commodity_type: "digital" } }).All();

The following examples show how to use strings and wildcards with the like operator.

In the following example we make a request to get all products where the SKU begins with SHOE_DECK.

curl -X GET https://api.moltin.com/v2/products?filter=like(sku,SHOE_DECK_*) \
     -H "Authorization: Bearer XXXX"

// Where `EPCC` is an authenticated client
await EPCC.Products.Filter({ like: { sku: "SHOE_DECK_*" } }).All();

In the following example we make a request to get all products where the SKU contains _DECK_.

curl -X GET https://api.moltin.com/v2/products?filter=like(sku,*_DECK_*) \
     -H "Authorization: Bearer XXXX"

// Where `EPCC` is an authenticated client
await EPCC.Products.Filter({ like: { sku: "*_DECK_*" } }).All();

In the following example we make a request to get all products where the SKU ends with _RED.

curl -X GET https://api.moltin.com/v2/products?filter=like(sku,*_RED) \
     -H "Authorization: Bearer XXXX"\

// Where `EPCC` is an authenticated client
await EPCC.Products.Filter({ like: { sku: "*_RED" } }).All();

You can chain filters to a query by using a colon (:) to separate your filters. For example, to find all draft products with the slug "new-slug" which have a stock greater than 2 and sorted by created_at, you make the following request:

curl -X GET https://api.moltin.com/v2/products?filter=eq(status,draft):eq(commodity_type,physical) \
     -H "Authorization: Bearer XXXX"

// Where `EPCC` is an authenticated client
await EPCC.Products.Filter({
    eq: {
        status: "draft",
        slug: "new-slug",
    },
    gt: {
        stock: 2,
    },
})
    .All()
    .Sort("created_at");

You can filter and find promotions using the promotion codes.

v2/promotions endpoint supports only the eq operator.

curl -X GET https://api.moltin.com/v2/promotions?filter=eq(code,{{promo_code}}) \
     -H "Authorization: Bearer XXXX"