Filtering · Commerce Cloud

You can filter results returned from the API using a standard URI format. The filter expression that you use depends on the API endpoint you are using. This is because not all supported operators work with all endpoint attributes. Each endpoint provides a list of filter attributes.

caution

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.

Filtering with `pcm/products`

The following pcm/products support filtering.

/pcm/products
/pcm/catalog/products
/pcm/catalog/hierarchies
/pcm/catalog/nodes
/pricebooks/:pricebookId/prices
/pricebooks/:pricebookId/price_modifiers

Depending on the endpoint you are using, you can filter on one or more of the following attributes:

sku
slug
upd_ean
mpn (or manufacturer_part_num if you are using /pcm/catalog/products endpoint)
name
description

note

Regarding manufacturing part number (mpn), /pcm/catalog/products uses manufacturer_part_num and pcm/products uses mpn.

You can also chain your filter expressions. For example, eq(manufacturer_part_num,xxx):eq(manufacturer_part_num,yyy).

Filtering on Custom Data (Flows)

You can filter on custom data fields (Flows). eq (equals) is the only supported operator. The filter expression is in the following format filter=eq(extensions.extensionname.field_slug,value) where:

extensionname is the name of your flow. See Create a flow.
field_slug is the slug of your field. See Create a field.
value is the value of your field. See Create a field.

For example, to find a product related to a flow called Face_Products, with a field whose slug is SkinType and whose value is Oily, the filter expression is filter=eq(extensions.Face_Products.SkinType,Oily).

Supported operators

Merchant Admin PCM and Shopper Catalogs 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.
`in`	In. Checks if the values are included in the specified string. If they are, the condition is true. Wildcards are supported.

Request example

In the following example, we make a request retrieve a price modifer called large_supplement.

curl GET https://api.moltin.com/pcm/pricebooks/fe3f3f4c-bf36-44fc-9af6-e460276b2a45/modifiers?filter=eq(name,large_supplement)
     -H "Authorization: Bearer XXXX"
     -H "Content-Type: application/json" \

Response example

200 OK

{
    "data": [
        {
            "id": "dde5425f-1b7b-457e-ba3c-accb0c089f3b",
            "attributes": {
                "currencies": {
                    "USD": {
                        "amount": 99,
                        "includes_tax": false
                    }
                },
                "modifier_type": "price_increment",
                "name": "large_supplement"
            },
            "type": "price-modifier"
        }
    ],
    "links": {
        "first": "/pcm/pricebooks/fe3f3f4c-bf36-44fc-9af6-e460276b2a45/modifiers?filter=eq(name,large_supplement)&page[offset]=0&page[limit]=25&",
        "last": "/pcm/pricebooks/fe3f3f4c-bf36-44fc-9af6-e460276b2a45/modifiers?filter=eq(name,large_supplement)&page[offset]=0&page[limit]=25&",
        "self": "/pcm/pricebooks/fe3f3f4c-bf36-44fc-9af6-e460276b2a45/modifiers?filter=eq(name,large_supplement)&"
    },
    "meta": {
        "page": {
            "current": 1,
            "limit": 25,
            "total": 1
        },
        "results": {
            "total": 1
        }
    }
}

Filtering with `v2/products`

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

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.

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.
`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 example

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"

Java SDK

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

Request 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

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

Java SDK

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

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

Java SDK

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

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

Java SDK

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

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"

Java SDK

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

caution

Supported Characters

Supported Date Formats

URL Encoding Filters

Filtering with pcm/products

note

Filtering on Custom Data (Flows)

Supported operators

Request example

Response example

Filtering with v2/products

note

Supported operators

Request example

Curl

Java SDK

Request Example - The like Operator

A string begins with a specified value

Curl

Java SDK

A string contains a specified value

Curl

Java SDK

A string ends with a specified value

Curl

Java SDK

Example: Chaining multiple operators

Curl

Java SDK

Filtering with `pcm/products`

Filtering with `v2/products`

Request Example - The `like` Operator