Filtering

You can filter results returned from the API using a standard URI format.

Supported operators

Not all supported operators work with all endpoint attributes. Each endpoint provides a list of filter attributes. Filtering on custom data fields (Flows) is not supported.

note

You can only filter on base object attributes. Filtering through non-base attributes is not supported and returns everything.

caution

There is a maximum of 10 filters allowed on a single request.

Operator	Description
eq	Equals. Checks if the values of two operands are equal. If they are, the condition is true. See the eq example.
like	Like. Checks if the operand contains the specified string. Wildcards are supported. See the like examples.
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.

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

Passing unsupported characters returns a 400 response with the following error:

{
  "errors": [
    {
      "title": "Bad Request",
      "detail": "The supplied filter contained unsupported characters"
    }
  ]
}

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 endpoints

• /brands
• /categories
• /collections
• /customers
• /files
• /orders
• /products

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

Examples

Example: The eq operator

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

cURL

JavaScript SDK

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

const MoltinGateway = require('@moltin/sdk').gateway
const Moltin = MoltinGateway({
  client_id: 'X'
})
Moltin.Products.Filter({ eq: { commodity_type: 'digital' } })
  .All()
  .then(products => {
    // Do something
  })

Example: 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

JavaScript SDK

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

const MoltinGateway = require('@moltin/sdk').gateway
const Moltin = MoltinGateway({
  client_id: 'X'
})
Moltin.Products.Filter({ like: { sku: 'SHOE_DECK_*' } })
  .All()
  .then(products => {
    // Do something
  })

A string contains a specified value

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

cURL

JavaScript SDK

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

const MoltinGateway = require('@moltin/sdk').gateway
const Moltin = MoltinGateway({
  client_id: 'X'
})
Moltin.Products.Filter({ like: { sku: '*_DECK_*' } })
  .All()
  .then(products => {
    // Do something
  })

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

JavaScript SDK

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

const MoltinGateway = require('@moltin/sdk').gateway
const Moltin = MoltinGateway({
  client_id: 'X'
})
Moltin.Products.Filter({ like: { sku: '*_RED' } })
  .All()
  .then(products => {
    // Do something
  })

Example: Chaining multiple operators

caution

This feature is currently in Beta and you should expect it to change.

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

JavaScript SDK

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

const MoltinGateway = require('@moltin/sdk').gateway
const Moltin = MoltinGateway({
  client_id: 'X'
})
Moltin.Products.Filter({
  eq: {
    status: 'draft',
    slug: 'new-slug'
    },
  gt: {
    stock: 2
    }
  }).All()
    .Sort('created_at')
    .then(products => {
      // Do something
    })