Filtering
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
.
pcm/products
Filtering with 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
(ormanufacturer_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
}
}
}
v2/products
Filtering with 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
})
like
Operator
Request Example - The 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
})