Store Filters API

Manage storefront filters for a site. A filter lets shoppers narrow that
site's storefront catalog by one product option name, such as "Material" or
"Size".

Filters are scoped to a site, so a jewelry site and a music record site on the
same store can each choose their own filters. Because product options are
shared across the store, one option can feed a filter on more than one site.

Filters are part of the storefront search experience. This page covers the
management endpoints; the storefront renders the filters itself. A filter's name labels
it on the storefront; translate it into the site's other languages with the
Translations API.

Endpoints

• List Store Filters - GET /api/v1/sites/{site_id}/store-filters/
• Create Store Filter - POST /api/v1/sites/{site_id}/store-filters/
• Get Store Filter - GET /api/v1/sites/{site_id}/store-filters/{store_filter_id}/
• Update Store Filter - PUT /api/v1/sites/{site_id}/store-filters/{store_filter_id}/
• Delete Store Filter - DELETE /api/v1/sites/{site_id}/store-filters/{store_filter_id}/

Filters are scoped to a site. See Sites for the site endpoints.

Related resources:

• Product Options for the option names a filter can
  promote
• Products for the catalog the filters filter

List Store Filters

Retrieve every enabled filter for a site. This endpoint is not paginated, since
a site has at most 20 filters.

Endpoint: GET /api/v1/sites/{site_id}/store-filters/

Permission Required: Read

Path Parameters

Request

curl -X GET "https://studio.easel.engineering/api/v1/sites/sit_d0b6fmv28q6vn14peun0/store-filters/" \
  -H "Authorization: Bearer your_api_key_here"

Response

Status: 200 OK

{
  "data": [
    {
      "id": "sfl_d0b6fmv28q6vn14peun0",
      "name": "Material",
      "position": 0,
      "created_at": "2023-01-01T10:00:00Z",
      "updated_at": "2023-01-01T10:00:00Z"
    }
  ]
}

Create Store Filter

Create a filter for a product option name on a site. Every product option with
that name is linked to the filter, so the filter collects their values across the
store. The storefront slug is generated from the name automatically and is not
part of the API. New filters are appended to the end of the site's filter list.
A site has at most 20 filters; creating one past that returns INVALID_FIELD.

Endpoint: POST /api/v1/sites/{site_id}/store-filters/

Permission Required: Write

Path Parameters

Request Body

{
  "name": "Material"
}

Fields

Request

curl -X POST "https://studio.easel.engineering/api/v1/sites/sit_d0b6fmv28q6vn14peun0/store-filters/" \
  -H "Authorization: Bearer your_api_key_here" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: unique-request-id-12345" \
  -d '{"name": "Material"}'

Response

Status: 201 Created

{
  "id": "sfl_d0b6fmv28q6vn14peun0"
}

Error Responses

Missing required field

Status: 400 Bad Request

{
  "error": "Name is required",
  "code": "MISSING_FIELD"
}

Duplicate filter

A filter already exists for the option name on the site.

Status: 409 Conflict

{
  "error": "Resource already exists",
  "code": "DUPLICATE"
}

Failed to create filter

Status: 500 Internal Server Error

{
  "error": "Internal server error",
  "code": "INTERNAL_ERROR"
}

Get Store Filter

Retrieve a single filter on a site.

Endpoint: GET /api/v1/sites/{site_id}/store-filters/{store_filter_id}/

Permission Required: Read

Path Parameters

Request

curl -X GET "https://studio.easel.engineering/api/v1/sites/sit_d0b6fmv28q6vn14peun0/store-filters/sfl_d0b6fmv28q6vn14peun0/" \
  -H "Authorization: Bearer your_api_key_here"

Response

Status: 200 OK

{
  "id": "sfl_d0b6fmv28q6vn14peun0",
  "name": "Material",
  "position": 0,
  "created_at": "2023-01-01T10:00:00Z",
  "updated_at": "2023-01-01T10:00:00Z"
}

Error Responses

Filter not found

Status: 404 Not Found

{
  "error": "Resource not found",
  "code": "NOT_FOUND"
}

Update Store Filter

Update a filter's name or position. The storefront slug is generated from the
option name when the filter is created, is not part of the API, and cannot be
changed. Updating the name does not re-link options: the filter keeps the
options it was linked to when it was created.

Endpoint: PUT /api/v1/sites/{site_id}/store-filters/{store_filter_id}/

Permission Required: Write

Path Parameters

Request Body

{
  "name": "Material",
  "position": 3
}

Fields

Request

curl -X PUT "https://studio.easel.engineering/api/v1/sites/sit_d0b6fmv28q6vn14peun0/store-filters/sfl_d0b6fmv28q6vn14peun0/" \
  -H "Authorization: Bearer your_api_key_here" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: unique-request-id-67890" \
  -d '{"name": "Material", "position": 3}'

Response

Status: 204 No Content

Error Responses

Missing required field

Status: 400 Bad Request

{
  "error": "Name is required",
  "code": "MISSING_FIELD"
}

Filter not found

Status: 404 Not Found

{
  "error": "Resource not found",
  "code": "NOT_FOUND"
}

Delete Store Filter

Delete a filter from a site. The linked product options are unlinked before the
filter is removed, so the storefront stops counting it immediately. The product
options themselves are not changed.

Endpoint: DELETE /api/v1/sites/{site_id}/store-filters/{store_filter_id}/

Permission Required: Write

Path Parameters

Request

curl -X DELETE "https://studio.easel.engineering/api/v1/sites/sit_d0b6fmv28q6vn14peun0/store-filters/sfl_d0b6fmv28q6vn14peun0/" \
  -H "Authorization: Bearer your_api_key_here"

Response

Status: 204 No Content

Error Responses

Filter not found

Status: 404 Not Found

{
  "error": "Resource not found",
  "code": "NOT_FOUND"
}