Store Facets API

Manage storefront facets for a site. A facet promotes one product option name,
such as "Material" or "Size", to a filter on that site's storefront catalog.

Facets 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 facet on more than one site.

Facets are part of the storefront search experience. This page covers the
management endpoints; the storefront renders the filters itself.

Endpoints

• List Store Facets - GET /api/v1/sites/{site_id}/store-facets/
• Create Store Facet - POST /api/v1/sites/{site_id}/store-facets/
• Get Store Facet - GET /api/v1/sites/{site_id}/store-facets/{store_facet_id}/
• Update Store Facet - PUT /api/v1/sites/{site_id}/store-facets/{store_facet_id}/
• Delete Store Facet - DELETE /api/v1/sites/{site_id}/store-facets/{store_facet_id}/

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

Related resources:

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

List Store Facets

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

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

Permission Required: Read

Path Parameters

Request

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

Response

Status: 200 OK

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

Create Store Facet

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

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

Permission Required: Write

Path Parameters

Request Body

{
  "name": "Material"
}

Fields

Request

curl -X POST "https://studio.easel.engineering/api/v1/sites/sit_d0b6fmv28q6vn14peun0/store-facets/" \
  -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": "sfa_d0b6fmv28q6vn14peun0"
}

Error Responses

Missing required field

Status: 400 Bad Request

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

Duplicate facet

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

Status: 409 Conflict

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

Failed to create facet

Status: 500 Internal Server Error

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

Get Store Facet

Retrieve a single facet on a site.

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

Permission Required: Read

Path Parameters

Request

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

Response

Status: 200 OK

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

Error Responses

Facet not found

Status: 404 Not Found

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

Update Store Facet

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

Endpoint: PUT /api/v1/sites/{site_id}/store-facets/{store_facet_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-facets/sfa_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"
}

Facet not found

Status: 404 Not Found

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

Delete Store Facet

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

Endpoint: DELETE /api/v1/sites/{site_id}/store-facets/{store_facet_id}/

Permission Required: Write

Path Parameters

Request

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

Response

Status: 204 No Content

Error Responses

Facet not found

Status: 404 Not Found

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