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.
• 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.

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"