Filtering With PXM
You can filter results returned from the API using a standard URI format.
- There is a maximum of 10 filters allowed on a single request.
- A request containing filters must not exceed 8KB. This is equal to approximately 200 IDs when using an
infilter. - Passing an incorrectly formatted filter or using an unsupported operator returns a
400response 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) becomes filter=eq%28email%2Cron%2B1%40swanson.com%29.
Filtering in pcm/products
The following table describes the supported operator and attributes when filtering on the pcm/products endpoint.
| Operator | Description | Supported Attributes | Example Endpoints |
|---|---|---|---|
Eq | Checks if the values of two operands are equal. If they are, the condition is true. | sku, slug, upc_ean, mpn, name, description | |
Like | Checks if the operand contains the specified string. Wildcards are supported. | sku, slug, upc_ean, mpn, name, description | |
In | Checks if the values are included in the specified string. If they are, the condition is true. | id | /pcm/products?filter=in(id,some-id) |
Filtering in pcm/catalogs and catalog
The following tables describe the supported operator and attributes when filtering on the pcm/catalogs and catalog endpoints.
For endpoints related to hierarchies or nodes:
| Operator | Description | Supported Attributes | Example Endpoints |
|---|---|---|---|
Eq | Checks if the values of two operands are equal. If they are, the condition is true. | name, slug | /pcm/catalogs/{{catalogId}}/releases/latest/hierarchies?filter=eq(name,some-name) |
In | Checks if the values are included in the specified string. If they are, the condition is true. | id | /pcm/catalogs/{catalog_id}/releases/{release_id}/hierarchies/{hierarchy_id}/nodes?filter=in(id,some-id) |
For endpoints related to products:
| Operator | Description | Supported Attributes | Example Endpoints |
|---|---|---|---|
Eq | Checks if the values of two operands are equal. If they are, the condition is true. | name, sku, slug, mpn, upc_ean | /pcm/catalogs/{catalog_id}/releases/{release_id}/products/{product_id}/relationships/children?filter=eq(name,some-name) |
In | Checks if the values are included in the specified string. If they are, the condition is true. | id, name, sku, slug, mpn, upc_ean | /pcm/catalogs/{catalog_id}/releases/{release_id}/products/{product_id}?filter=in(id,some-id) |
Building breadcrumbs in a storefront
In a catalog, you can use a filter to return a list of nodes in a hierarchy structure that a product belongs to. You can use this to build breadcrumbs in your storefront. An example is shown below.
filter=in(id,c83bfe55-0d87-4302-a86d-ab19e7e323f1,6003d7ef-84f3-49bb-a8bd-4cbfa203dcbb)
- Specify the node Ids in the filter expression.
- You can have as many node Ids as you want.
- It does not matter what order you specify the node Ids. The nodes are returned in the order they were last updated.
Filtering on Custom Data (Flows)
You can filter on custom data fields (Flows). eq (equals) is the only supported operator. To find a product related to a flow with a slug of products(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)
Where:
face_productsis a sanitized flow slug. If we have a flow whose name isFace Skin Productsand whose slug isproducts(face_products)then the sanitized flow slug isface_products. The sanitized flow slug is what you use in the filter. See Create a flow.skinTypeis the slug of your field. See Create a field.Oilyis the value of your field. See Create a field.
In addition, you can filter your flow entries on the entry id. For example, you may want to return a specific list of flow entries. in is the only supported operator.
filter=in(id,dd9b190b-1ba1-4185-bb73-d70ccd4e3835,99a77b76-1882-4c81-8f39-517347e9e5fb,a2b8ebb2-853e-4141-9ca4-a449576ce165)
See Get all Entries.
Best Practices
Fitering when you have thousands of products can be resource intensive so we recommend that your filters are as specific as possible. For example, see the following filters.
filter=like(sku,Belted*). This filter returns products whose SKU begin withBelted.filter=like(sku,*45). This filter returns products whose SKU end with45.
The above filters are more specific than the following example that returns products whose SKU contain Belted anywhere.
filter=like(sku,Belted)
Request Examples
Returns products that begin with specified SKU
curl GET https://api.moltin.com/pcm/products?filter=like(sku,Belted*)
-H "Authorization: Bearer XXXX"
-H "Content-Type: application/json"
Response example for products that begin with specified SKU
200 OK
{
"data": [
{
"type": "product",
"id": "fcaf530f-201b-4314-9bdb-099546c393fe",
"attributes": {
"commodity_type": "physical",
"components": {
"dresses_185844257279": {
"name": "dresses_185844257279",
"options": [
{
"id": "3b433505-7ee5-40a2-8408-655ff11d5502",
"type": "product",
"quantity": 2
}
]
}
},
"description": "Pim Bundle 055005594194",
"mpn": "Product-mpn-055005594194",
"name": "PIM Product Updated",
"sku": "BeltedCordDressBundle_933612204401",
"status": "live",
"upc_ean": "055005594194"
},
"relationships": {
"children": {
"data": [],
"links": {
"self": "/products/fcaf530f-201b-4314-9bdb-099546c393fe/children"
}
},
"component_products": {
"data": [],
"links": {
"self": "/products/fcaf530f-201b-4314-9bdb-099546c393fe/relationships/component_products"
}
},
"files": {
"data": [],
"links": {
"self": "/products/fcaf530f-201b-4314-9bdb-099546c393fe/relationships/files"
}
},
"main_image": {
"data": null
},
"templates": {
"data": [],
"links": {
"self": "/products/fcaf530f-201b-4314-9bdb-099546c393fe/relationships/templates"
}
},
"variations": {
"data": [],
"links": {
"self": "/products/fcaf530f-201b-4314-9bdb-099546c393fe/relationships/variations"
}
}
},
"meta": {
"created_at": "2022-03-03T10:19:57.995Z",
"updated_at": "2022-03-03T10:20:37.984Z",
"variation_matrix": {}
}
},
{
"type": "product",
"id": "3b433505-7ee5-40a2-8408-655ff11d5502",
"attributes": {
"commodity_type": "physical",
"description": "Product 478534958942",
"mpn": "Product-mpn-478534958942",
"name": "PIMProduct 478534958942",
"sku": "BeltedCordDress_694005267795",
"slug": "product-slug-478534958942",
"status": "live",
"upc_ean": "478534958942"
},
"relationships": {
"children": {
"data": [],
"links": {
"self": "/products/3b433505-7ee5-40a2-8408-655ff11d5502/children"
}
},
"component_products": {
"data": [],
"links": {
"self": "/products/3b433505-7ee5-40a2-8408-655ff11d5502/relationships/component_products"
}
},
"files": {
"data": [],
"links": {
"self": "/products/3b433505-7ee5-40a2-8408-655ff11d5502/relationships/files"
}
},
"main_image": {
"data": {
"type": "file",
"id": "cba780b5-c242-448e-9c63-44c6d9c0a218"
},
"links": {
"self": "/products/3b433505-7ee5-40a2-8408-655ff11d5502/relationships/main_image"
}
},
"templates": {
"data": [],
"links": {
"self": "/products/3b433505-7ee5-40a2-8408-655ff11d5502/relationships/templates"
}
},
"variations": {
"data": [],
"links": {
"self": "/products/3b433505-7ee5-40a2-8408-655ff11d5502/relationships/variations"
}
}
},
"meta": {
"created_at": "2022-03-03T10:19:22.123Z",
"updated_at": "2022-03-03T10:19:44.544Z",
"variation_matrix": {}
}
}
],
"meta": {
"results": {
"total": 2
}
}
}
Building a storefront
curl GET https://api.moltin.com/catalog/nodes?filter=in(id,0ad394b5-33b3-4a1f-ad75-f24fc24445f5,85f2fa96-ae67-4ac5-9b5f-6f44b468d753)
-H "Authorization: Bearer XXXX"
-H "Content-Type: application/json"
Response example for building a storefront
200 OK
{
"data": [
{
"id": "85f2fa96-ae67-4ac5-9b5f-6f44b468d753",
"type": "node",
"attributes": {
"created_at": "2022-03-03T10:20:38.330Z",
"description": "Description-931808449185",
"name": "Kids",
"slug": "Slug-931808449185",
"updated_at": "2022-03-03T10:20:38.330Z",
"published_at": "2022-09-30T08:43:46.259Z"
},
"relationships": {
"children": {
"links": {
"related": "/catalog/nodes/85f2fa96-ae67-4ac5-9b5f-6f44b468d753/relationships/children"
}
},
"hierarchy": {
"data": {
"id": "85f2fa96-ae67-4ac5-9b5f-6f44b468d753",
"type": "hierarchy"
},
"links": {
"related": "/catalog/hierarchies/85f2fa96-ae67-4ac5-9b5f-6f44b468d753"
}
},
"products": {
"links": {
"related": "/catalog/nodes/85f2fa96-ae67-4ac5-9b5f-6f44b468d753/relationships/products"
}
}
}
},
{
"id": "0ad394b5-33b3-4a1f-ad75-f24fc24445f5",
"type": "node",
"attributes": {
"created_at": "2022-03-03T10:19:19.452Z",
"description": "Description-098983310281",
"name": "Womens",
"slug": "Slug-098983310281",
"updated_at": "2022-03-03T10:19:19.452Z",
"published_at": "2022-09-30T08:43:46.259Z"
},
"relationships": {
"children": {
"links": {
"related": "/catalog/nodes/0ad394b5-33b3-4a1f-ad75-f24fc24445f5/relationships/children"
}
},
"hierarchy": {
"data": {
"id": "0ad394b5-33b3-4a1f-ad75-f24fc24445f5",
"type": "hierarchy"
},
"links": {
"related": "/catalog/hierarchies/0ad394b5-33b3-4a1f-ad75-f24fc24445f5"
}
},
"products": {
"links": {
"related": "/catalog/nodes/0ad394b5-33b3-4a1f-ad75-f24fc24445f5/relationships/products"
}
}
}
}
],
"links": {
"first": "/catalog/nodes?filter=in(id,0ad394b5-33b3-4a1f-ad75-f24fc24445f5,85f2fa96-ae67-4ac5-9b5f-6f44b468d753)&page[offset]=0&page[limit]=25",
"last": "/catalog/nodes?filter=in(id,0ad394b5-33b3-4a1f-ad75-f24fc24445f5,85f2fa96-ae67-4ac5-9b5f-6f44b468d753)&page[offset]=0&page[limit]=25",
"self": "/catalog/nodes?filter=in(id,0ad394b5-33b3-4a1f-ad75-f24fc24445f5,85f2fa96-ae67-4ac5-9b5f-6f44b468d753)"
},
"meta": {
"page": {
"current": 1,
"limit": 25,
"total": 2
},
"results": {
"total": 2
}
}
}
Returns a product related to a flow with a slug of products(face_products), with a field whose slug is SkinType and whose value is Oily
curl GET https://api.moltin.com/v2/flows?filter=eq(extensions.face_products.SkinType,Oily)
-H "Authorization: Bearer XXXX"
-H "Content-Type: application/json"
Response example
200 OK
{
"data": [
{
"id": "24c2a332-a76a-4988-81e3-8a24324998a6",
"type": "flow",
"name": "products(face_products)",
"slug": "SkinType",
"description": "Face products",
"enabled": true,
"links": {
"self": "https://epcc-integration.global.ssl.fastly.net/v2/flows/24c2a332-a76a-4988-81e3-8a24324998a6"
},
"relationships": {
"fields": {
"data": [
{
"id": "565aa2a5-1d6f-446d-8f4a-bee8df2b50b9",
"type": "oily"
}
]
}
},
"meta": {
"timestamps": {
"created_at": "2022-03-03T10:19:30.964Z",
"updated_at": "2022-03-03T10:19:30.964Z"
}
}
}
]
}