Products API

Manage products in your store. Products represent items that customers can purchase and can be either simple products or variant products with multiple options.

Endpoints

• List Products - GET /api/v1/products
• Create Product - POST /api/v1/products
• Get Product - GET /api/v1/products/{id}
• Update Product - PUT /api/v1/products/{id}

List Products

Retrieve a paginated list of products for your store.

Endpoint: GET /api/v1/products

Permission Required: Read

Query Parameters

Request

curl -X GET "https://studio.easel.engineering/api/v1/products?status=active&type=simple&after=123" \
  -H "Authorization: Bearer your_api_key_here" \
  -H "Content-Type: application/json"

Response

Status: 200 OK

{
  "products": [
    {
      "id": "prd_abc123",
      "name": "Premium T-Shirt",
      "type": "simple",
      "status": "active",
      "description": "High-quality cotton t-shirt",
      "created_at": "2023-01-01T10:00:00Z",
      "updated_at": "2023-01-01T10:15:00Z"
    }
  ],
  "pagination": {
    "has_next_page": true,
    "has_previous_page": false,
    "next_cursor": 124
  }
}

Error Responses

Invalid cursor parameter

Status: 400 Bad Request

{
  "error": "Invalid 'after' parameter",
  "code": "INVALID_FIELD"
}

Failed to list products

Status: 500 Internal Server Error

{
  "error": "Failed to list products",
  "code": "LIST_ERROR"
}

Create Product

Create a new product in your store.

Endpoint: POST /api/v1/products

Permission Required: Write

Request Body

{
  "name": "Premium T-Shirt",
  "type": "simple",
  "description": "High-quality cotton t-shirt"
}

Fields

Request

curl -X POST "https://studio.easel.engineering/api/v1/products" \
  -H "Authorization: Bearer your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Premium T-Shirt",
    "type": "simple",
    "description": "High-quality cotton t-shirt"
  }'

Response

Returns the created product.

Status: 201 Created

{
  "id": "prd_abc123",
  "name": "Premium T-Shirt",
  "type": "simple",
  "status": "draft",
  "description": "High-quality cotton t-shirt",
  "created_at": "2023-01-01T10:00:00Z",
  "updated_at": "2023-01-01T10:00:00Z"
}

Error Responses

Invalid JSON body

Status: 400 Bad Request

{
  "error": "Invalid JSON body",
  "code": "INVALID_JSON"
}

Missing required field

Status: 400 Bad Request

{
  "error": "Product name is required",
  "code": "MISSING_FIELD"
}

Invalid product type

Status: 400 Bad Request

{
  "error": "Product type must be 'simple' or 'variant'",
  "code": "INVALID_FIELD"
}

Failed to create product

Status: 500 Internal Server Error

{
  "error": "Failed to create product",
  "code": "CREATE_ERROR"
}

Product created but failed to retrieve

Status: 500 Internal Server Error

{
  "error": "Product created but failed to retrieve",
  "code": "GET_ERROR"
}

Get Product

Retrieve a single product by its public ID.

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

Permission Required: Read

Path Parameters

Request

curl -X GET "https://studio.easel.engineering/api/v1/products/prd_abc123" \
  -H "Authorization: Bearer your_api_key_here" \
  -H "Content-Type: application/json"

Response

Status: 200 OK

{
  "id": "prd_abc123",
  "name": "Premium T-Shirt",
  "type": "simple",
  "status": "active",
  "description": "High-quality cotton t-shirt",
  "created_at": "2023-01-01T10:00:00Z",
  "updated_at": "2023-01-01T10:15:00Z"
}

Error Responses

Missing product ID

Status: 400 Bad Request

{
  "error": "Product ID is required",
  "code": "MISSING_FIELD"
}

Product not found

Status: 404 Not Found

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

Failed to get product

Status: 500 Internal Server Error

{
  "error": "Failed to get product",
  "code": "GET_ERROR"
}

Update Product

Update an existing product's name, description, or status.

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

Permission Required: Write

Path Parameters

Request Body

{
  "name": "Premium T-Shirt - Updated",
  "status": "active",
  "description": "Updated high-quality cotton t-shirt"
}

Fields

Request

curl -X PUT "https://studio.easel.engineering/api/v1/products/prd_abc123" \
  -H "Authorization: Bearer your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Premium T-Shirt - Updated",
    "status": "active",
    "description": "Updated high-quality cotton t-shirt"
  }'

Response

Returns the updated product.

Status: 200 OK

{
  "id": "prd_abc123",
  "name": "Premium T-Shirt - Updated",
  "type": "simple",
  "status": "active",
  "description": "Updated high-quality cotton t-shirt",
  "created_at": "2023-01-01T10:00:00Z",
  "updated_at": "2023-01-01T11:30:00Z"
}

Error Responses

Missing product ID

Status: 400 Bad Request

{
  "error": "Product ID is required",
  "code": "MISSING_FIELD"
}

Invalid JSON body

Status: 400 Bad Request

{
  "error": "Invalid JSON body",
  "code": "INVALID_JSON"
}

Missing required field

Status: 400 Bad Request

{
  "error": "Product name is required",
  "code": "MISSING_FIELD"
}

Invalid status

Status: 400 Bad Request

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

Product not found

Status: 404 Not Found

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

Failed to update product

Status: 500 Internal Server Error

{
  "error": "Failed to update product",
  "code": "UPDATE_ERROR"
}

Product updated but failed to retrieve

Status: 500 Internal Server Error

{
  "error": "Product updated but failed to retrieve",
  "code": "GET_ERROR"
}

Product Object

Fields

Product Types

• simple - A standalone product with no variations
• variant - A product with multiple variants (size, color, etc.)

Product Status Values

• draft - Product is being configured, not visible to customers
• active - Product is available for purchase
• archived - Product is no longer available but preserved for historical data