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
andsku
. 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"
}
]
}
Supported Characters
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.
Characters | Can be used in filter? |
---|---|
A-Z (upper & lower case) | Yes |
0-9 | Yes |
$ - _ * . | Yes |
" " (space) | Yes (an unencoded + is also treated as a space). |
+ | Only when URL encoded (%2B ). |
Supported Date Formats
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.
URL Encoding Filters
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
.
Performance
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:
- 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. - The
in
operator with a large number of options can also result in degraded performance.
Some strategies in these cases can be:
- Using
eq
when possible instead oflike
- Adding another search operator can often narrow down the request. For example, adding
eq(status,paid)
, orgt(updated_at,<DATE>)
tolike(contact.name,<SEARCH>)
may have higher performance. - 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.
Supported Operators
v2/products
endpoints support the following operators.
Operator | Description |
---|---|
eq | Equals. Checks if the values of two operands are equal. If they are, the condition is true. |
like | Like. Checks if the operand contains the specified string. Wildcards are supported. For more information, see like examples. |
in | In. Checks if the values are included in the specified, comma separated, list. If they are, the condition is true. Wildcards are not supported. |
gt | Greater than. Checks if the value of the first operand is greater than that of the second. If they are, the condition is true. |
ge | Greater than or equal to. Checks if the value of the first operand is greater than or equal to that of the second. If they are, the condition is true. |
lt | Less than. Checks if the value of the first operand is less than that of the second. If they are, the condition is true. |
le | Less than or equal to. Checks if the value of the first operand is less than or equal to that of the second. If they are, the condition is true. |
For more detail on filtering, see the Filtering section under each endpoint.
Request Examples
In the following example, we make a request to get all digital products from the catalog.
Curl
curl -X GET https://api.moltin.com/v2/products?filter=eq(commodity_type, digital) \
-H "Authorization: Bearer XXXX"
JavaScript SDK
// Where `EPCC` is an authenticated client
await EPCC.Products.Filter({ eq: { commodity_type: "digital" } }).All();
Request examples using the like
operator
The following examples show how to use strings and wildcards with the like
operator.
A string begins with a specified value
In the following example we make a request to get all products where the SKU begins with SHOE_DECK
.
Curl
curl -X GET https://api.moltin.com/v2/products?filter=like(sku,SHOE_DECK_*) \
-H "Authorization: Bearer XXXX"
JavaScript SDK
// Where `EPCC` is an authenticated client
await EPCC.Products.Filter({ like: { sku: "SHOE_DECK_*" } }).All();
A string contains a specified value
In the following example we make a request to get all products where the SKU contains _DECK_
.
Curl
curl -X GET https://api.moltin.com/v2/products?filter=like(sku,*_DECK_*) \
-H "Authorization: Bearer XXXX"
JavaScript SDK
// Where `EPCC` is an authenticated client
await EPCC.Products.Filter({ like: { sku: "*_DECK_*" } }).All();
A string ends with a specified value
In the following example we make a request to get all products where the SKU ends with _RED
.
Curl
curl -X GET https://api.moltin.com/v2/products?filter=like(sku,*_RED) \
-H "Authorization: Bearer XXXX"\
JavaScript SDK
// Where `EPCC` is an authenticated client
await EPCC.Products.Filter({ like: { sku: "*_RED" } }).All();
Request example chaining multiple operators
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
curl -X GET https://api.moltin.com/v2/products?filter=eq(status,draft):eq(commodity_type,physical) \
-H "Authorization: Bearer XXXX"
JavaScript SDK
// Where `EPCC` is an authenticated client
await EPCC.Products.Filter({
eq: {
status: "draft",
slug: "new-slug",
},
gt: {
stock: 2,
},
})
.All()
.Sort("created_at");
Filtering with v2/promotions
You can filter and find promotions using the promotion codes.
Supported operators
v2/promotions
endpoint supports only the eq
operator.
Operator | Description |
---|---|
eq | Equals. Checks if the values of two operands are equal. If they are, the condition is true. |
Request example using the eq
operator
curl -X GET https://api.moltin.com/v2/promotions?filter=eq(code,{{promo_code}}) \
-H "Authorization: Bearer XXXX"