Programmatic Product Image Upload

Required API Scopes

Create an API key from the WebKasa dashboard with media:write, products:write, and products:read if your importer verifies the product afterward. Keep this key on your server and never expose it to browser code.

1. Upload the Image

curl -X POST "https://api.webkasa.app/api/v1/media" \
  -H "Authorization: Bearer wk_live_xxx..." \
  -F "file=@./images/golden-jar.jpg;type=image/jpeg" \
  -F "title=Golden Jar" \
  -F "alt_text=Golden jar product photo" \
  -F "tags=shop,product-import,jar"

Store the returned data.id. That media file ID is the value you attach to a product or use as featured_image_id.

2. Attach It to a Product

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
  }'

Setting is_featured also updates the product featured_image_id. Re-attaching the same media file updates the existing product image instead of creating a duplicate.

Create Product With Image

If your importer creates products, upload media first and pass the returned media ID as featured_image_id while creating the product.

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": "Handcrafted jar",
    "featured_image_id": "media_abc123",
    "status": "published"
  }'

Importer Checklist

• Upload each image once, then reuse the returned media ID.
• Use descriptive alt_text so shop pages remain accessible.
• Tag imported files, for example shop and product-import, so they are easy to find later.
• Only attach media files owned by the same WebKasa organization as the product.
• Treat returned file URLs as display URLs. They may be signed and can expire.