• API Overview/
    Filtering

    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.
    • A request containing filters must not exceed 8KB.
    • 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.

    CharactersCan be used in filter?
    A-Z (upper & lower case)Yes
    0-9Yes
    $ - _ * .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.

    OperatorDescription
    eqEquals. Checks if the values of two operands are equal. If they are, the condition is true.
    likeLike. Checks if the operand contains the specified string. Wildcards are supported. For more information, see like examples.
    inIn. Checks if the values are included in the specified, comma separated, list. If they are, the condition is true. Wildcards are not supported.
    gtGreater than. Checks if the value of the first operand is greater than that of the second. If they are, the condition is true.
    geGreater 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.
    ltLess than. Checks if the value of the first operand is less than that of the second. If they are, the condition is true.
    leLess 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.

    OperatorDescription
    eqEquals. 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"
    

    Was this helpful?

    Previous
    Filtering With PXM