Product API¶

Send products from your own system. In the dashboard this is the Developer API product source.

Authentication¶

In Products, choose Developer API and select Use the Developer API. Until then, a push returns 409.
Under Settings → API and webhooks, create an API key (kok_<id>.<secret>, shown once). The Order API uses the same key. Older ingest tokens still work as X-Ingest-Token.

Send products¶

POST https://backend.kothok.ai/stores/push
Authorization: Bearer kok_12.Xq3...
Content-Type: application/json

{
  "products": [
    {
      "external_id": "SKU-1001",
      "title": "Trail Runner 3 Waterproof",
      "url": "https://shop.example.com/products/trail-runner-3",
      "description": "Waterproof trail shoe with a grip outsole.",
      "brand": "Northpeak",
      "product_type": "Running shoes",
      "tags": ["waterproof", "trail"],
      "price_min": "2850.00",
      "price_max": "3200.00",
      "currency": "BDT",
      "in_stock": true,
      "inventory": 24,
      "variants": [
        { "sku": "SKU-1001-42", "size": "42", "color": "black",
          "price": "2850.00", "inventory": 11 }
      ],
      "images": ["https://cdn.example.com/trail-runner-3.jpg"]
    }
  ],
  "removed": ["SKU-0950"]
}

Up to 500 products and 500 removed ids per request, 5 MB body.
Products match on external_id; resending updates. Products you leave out are untouched; list an id in removed to delist it.
Send source_modified_at so an older push never overwrites newer data.

All fields: Product fields.

What comes back¶

{ "connection_id": 42, "imported": 499, "removed": 1, "failed": 1,
  "errors": ["SKU-1077: DataError"] }

A 200 can still refuse some products, so check failed. Only the first 10 errors are listed.

Status	Meaning
`401`	Missing, invalid or disconnected key
`403`	Turned off for this shop by Kothok support
`409`	Developer API isn't the product source, or the token belongs to the WordPress plugin
`413`	Body over 5 MB
`422`	A rule in Product fields is broken. Nothing is saved.
`429`	Over 120 requests a minute per store

A 422 detail is a list of strings naming the product (for example "products[3] (SKU-1077): price_min must not exceed price_max") or FastAPI's {loc, msg, type} list. Then test the setup.