Sites API

Manage the storefront sites in your store. A site has a name, a slug, a status,
a currency, a flat shipping fee, and the set of countries you ship to.

Related resources:

• Pages for the home page and info page content
• Collections for product groupings
• Discount Codes for site-scoped codes

Endpoints

• List Sites - GET /api/v1/sites/
• Create Site - POST /api/v1/sites/
• Get Site - GET /api/v1/sites/{id}/
• Update Site - PUT /api/v1/sites/{id}/

List Sites

Retrieve the sites for your store. This endpoint is not paginated. The list
does not include allowed shipping countries, so allowed_country_ids is empty.
Fetch a single site to see them.

Endpoint: GET /api/v1/sites/

Permission Required: Read

Request

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

Response

Status: 200 OK

{
  "data": [
    {
      "id": "sit_d0b6fmv28q6vn14peun0",
      "name": "My Store",
      "slug": "my-store",
      "status": "active",
      "currency": "USD",
      "shipping_fee": 599,
      "domain_host": null,
      "allowed_country_ids": [],
      "created_at": "2023-01-01T10:00:00Z",
      "updated_at": "2023-01-01T10:00:00Z"
    }
  ]
}

Create Site

Create a new storefront site.

Endpoint: POST /api/v1/sites/

Permission Required: Write

Request Body

{
  "name": "My Store",
  "shipping_fee": 599,
  "allowed_shipping_country_ids": [1, 2]
}

Request

curl -X POST "https://studio.easel.engineering/api/v1/sites/" \
  -H "Authorization: Bearer your_api_key_here" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: unique-request-id-12345" \
  -d '{
    "name": "My Store",
    "shipping_fee": 599,
    "allowed_shipping_country_ids": [1, 2]
  }'

Response

Status: 201 Created

{
  "id": "sit_d0b6fmv28q6vn14peun0"
}

Error Responses

Missing required field

Status: 400 Bad Request

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

Get Site

Retrieve a single site, including its allowed shipping countries.

Endpoint: GET /api/v1/sites/{id}/

Permission Required: Read

Request

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

Response

Status: 200 OK

{
  "id": "sit_d0b6fmv28q6vn14peun0",
  "name": "My Store",
  "slug": "my-store",
  "status": "active",
  "currency": "USD",
  "shipping_fee": 599,
  "domain_host": "shop.example.com",
  "allowed_country_ids": [1, 2],
  "created_at": "2023-01-01T10:00:00Z",
  "updated_at": "2023-01-01T10:00:00Z"
}

Error Responses

Site not found

Status: 404 Not Found

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

Update Site

Update a site's name, status, domain, shipping fee, and allowed countries. All
fields are required. An empty domain_host clears the custom domain. The site
logo is preserved.

Endpoint: PUT /api/v1/sites/{id}/

Permission Required: Write

Request Body

{
  "name": "My Store",
  "status": "active",
  "domain_host": "shop.example.com",
  "shipping_fee": 599,
  "allowed_shipping_country_ids": [1, 2]
}

Request

curl -X PUT "https://studio.easel.engineering/api/v1/sites/sit_d0b6fmv28q6vn14peun0/" \
  -H "Authorization: Bearer your_api_key_here" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: unique-request-id-67890" \
  -d '{
    "name": "My Store",
    "status": "active",
    "domain_host": "shop.example.com",
    "shipping_fee": 599,
    "allowed_shipping_country_ids": [1, 2]
  }'

Response

Status: 204 No Content

Error Responses

Invalid status

Status: 400 Bad Request

{
  "error": "Status must be 'active' or 'draft'",
  "code": "INVALID_FIELD"
}

Site Object

Fields