Collections API

Manage collections for a site. A collection groups products and has its own
slug on the storefront. Tags attached to a collection can drive navigation.

Endpoints

Collections:

• List Collections - GET /api/v1/sites/{site_id}/collections/
• Create Collection - POST /api/v1/sites/{site_id}/collections/
• Get Collection - GET /api/v1/sites/{site_id}/collections/{collection_id}/
• Update Collection - PUT /api/v1/sites/{site_id}/collections/{collection_id}/
• Delete Collection - DELETE /api/v1/sites/{site_id}/collections/{collection_id}/

Collection tags:

• List Collection Tags - GET /api/v1/sites/{site_id}/collections/{collection_id}/tags/
• Add Collection Tag - POST /api/v1/sites/{site_id}/collections/{collection_id}/tags/
• Delete Collection Tag - DELETE /api/v1/sites/{site_id}/collections/{collection_id}/tags/{tag_id}/

Tags themselves are managed with the Tags endpoints.

List Collections

Retrieve the collections for a site. This endpoint is not paginated and does
not include tags. Fetch a single collection to see its tags.

Endpoint: GET /api/v1/sites/{site_id}/collections/

Permission Required: Read

Request

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

Response

Status: 200 OK

{
  "data": [
    {
      "id": "col_d0b6fmv28q6vn14peun0",
      "name": "Summer",
      "slug": "summer",
      "tags": [],
      "created_at": "2023-01-01T10:00:00Z",
      "updated_at": "2023-01-01T10:00:00Z"
    }
  ]
}

Create Collection

Create a collection for a site. The slug is generated from the name.

Endpoint: POST /api/v1/sites/{site_id}/collections/

Permission Required: Write

Request Body

{
  "name": "Summer"
}

Request

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

Response

Status: 201 Created

{
  "id": "col_d0b6fmv28q6vn14peun0"
}

Get Collection

Retrieve a single collection, including its tags.

Endpoint: GET /api/v1/sites/{site_id}/collections/{collection_id}/

Permission Required: Read

Request

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

Response

Status: 200 OK

{
  "id": "col_d0b6fmv28q6vn14peun0",
  "name": "Summer",
  "slug": "summer",
  "tags": [
    {
      "id": "ctg_d0b6fmv28q6vn14peun0",
      "tag": {
        "id": "tag_d0b6fmv28q6vn14peun0",
        "name": "Summer"
      }
    }
  ],
  "created_at": "2023-01-01T10:00:00Z",
  "updated_at": "2023-01-01T10:00:00Z"
}

Update Collection

Rename a collection. The slug is regenerated from the new name.

Endpoint: PUT /api/v1/sites/{site_id}/collections/{collection_id}/

Permission Required: Write

Request Body

{
  "name": "Summer 2024"
}

Request

curl -X PUT "https://studio.easel.engineering/api/v1/sites/sit_d0b6fmv28q6vn14peun0/collections/col_d0b6fmv28q6vn14peun0/" \
  -H "Authorization: Bearer your_api_key_here" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: unique-request-id-67890" \
  -d '{"name": "Summer 2024"}'

Response

Status: 204 No Content

Delete Collection

Delete a collection.

Endpoint: DELETE /api/v1/sites/{site_id}/collections/{collection_id}/

Permission Required: Write

Request

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

Response

Status: 204 No Content

List Collection Tags

Retrieve the tags attached to a collection.

Endpoint: GET /api/v1/sites/{site_id}/collections/{collection_id}/tags/

Permission Required: Read

Request

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

Response

Status: 200 OK

{
  "data": [
    {
      "id": "ctg_d0b6fmv28q6vn14peun0",
      "tag": {
        "id": "tag_d0b6fmv28q6vn14peun0",
        "name": "Summer"
      }
    }
  ]
}

Add Collection Tag

Attach an existing tag to a collection.

Endpoint: POST /api/v1/sites/{site_id}/collections/{collection_id}/tags/

Permission Required: Write

Request Body

{
  "tag_id": "tag_d0b6fmv28q6vn14peun0"
}

Request

curl -X POST "https://studio.easel.engineering/api/v1/sites/sit_d0b6fmv28q6vn14peun0/collections/col_d0b6fmv28q6vn14peun0/tags/" \
  -H "Authorization: Bearer your_api_key_here" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: unique-request-id-13579" \
  -d '{"tag_id": "tag_d0b6fmv28q6vn14peun0"}'

Response

Status: 201 Created

The response body is empty.

Delete Collection Tag

Detach a tag from a collection.

Endpoint: DELETE /api/v1/sites/{site_id}/collections/{collection_id}/tags/{tag_id}/

Permission Required: Write

Request

curl -X DELETE "https://studio.easel.engineering/api/v1/sites/sit_d0b6fmv28q6vn14peun0/collections/col_d0b6fmv28q6vn14peun0/tags/tag_d0b6fmv28q6vn14peun0/" \
  -H "Authorization: Bearer your_api_key_here"

Response

Status: 204 No Content

Collection Object

Fields

Collection Tag Object

Fields