Products API

Manage WebKasa shop products and attach uploaded media as product images.

List Products

GET/api/v1/products

Retrieve products for the authenticated organization

Query Parameters

Parameter	Type	Description
`status`	`string`	Filter by product status, for example published or draft
`search`	`string`	Search product names
`min_price`	`number`	Minimum product price
`max_price`	`number`	Maximum product price
`in_stock`	`boolean`	Only products available for purchase
`limit`	`number`	Max results Default: `50`
`offset`	`number`	Skip results for pagination Default: `0`

Request

curl -X GET "https://api.webkasa.app/api/v1/products?status=published&in_stock=true" \
  -H "Authorization: Bearer wk_live_xxx..."

Create Product

POST/api/v1/products

Create a new shop product

Request Body

Parameter	Type	Description
`name` required	`string`	Product name
`price` required	`number`	Base price in dollars
`slug`	`string`	URL slug. Generated from name when omitted.
`description`	`string`	Product description
`featured_image_id`	`string`	Media file ID to use as the featured image
`status`	`string`	Product status Default: `draft`

Request

curl -X POST "https://api.webkasa.app/api/v1/products" \
  -H "Authorization: Bearer wk_live_xxx..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Golden Jar",
    "price": 42,
    "description": "A handcrafted product",
    "featured_image_id": "media_abc123",
    "status": "published"
  }'

Response

201 Created

{
  "data": {
    "id": "prod_abc123",
    "name": "Golden Jar",
    "slug": "golden-jar",
    "price": 42,
    "featured_image_id": "media_abc123",
    "status": "published"
  }
}

List Product Images

GET/api/v1/products/{id}/images

Retrieve the product image gallery

Request

curl -X GET "https://api.webkasa.app/api/v1/products/prod_abc123/images" \
  -H "Authorization: Bearer wk_live_xxx..."

Attach Product Image

POST/api/v1/products/{id}/images

Attach an uploaded media file to a product

Request Body

Parameter	Type	Description
`media_file_id` required	`string`	Media file ID returned by POST /api/v1/media
`is_featured`	`boolean`	Set this media file as the product featured image Default: `false`
`order_index`	`number`	Optional image sort position. Defaults to the next position.

Request

curl -X POST "https://api.webkasa.app/api/v1/products/prod_abc123/images" \
  -H "Authorization: Bearer wk_live_xxx..." \
  -H "Content-Type: application/json" \
  -d '{
    "media_file_id": "media_abc123",
    "is_featured": true
  }'

Response

201 Created

{
  "data": {
    "id": "image_abc123",
    "product_id": "prod_abc123",
    "media_file_id": "media_abc123",
    "order_index": 0,
    "is_featured": true,
    "media_file": {
      "id": "media_abc123",
      "url": "https://...",
      "alt_text": "Golden jar product photo"
    }
  }
}

404 Not Found

{
  "error": "Media file not found"
}