API reference/Store
Add a product
Try itAdds a product to the site's store — on the site at once (no publish) unless active=false. The site's package must include the store, and its product limit applies. Without options it gets one unnamed option; several options each need a name.
POST
/api/v1/sites/{site_id}/productsAuthentication
An API key as Authorization: Bearer or x-api-key. It needs the store:write scope — add and change products and stock (live at once); move orders along.
store:writeChanges the live siteIdempotency-Key requiredMCP tool: create_product
Parameters
Named placeholders go in the path; the rest in a JSON body.
site_idstringPath · required- The site's id.1 to 100 characters
namestringBody · required- e.g. Glazed serving bowl.2 to 120 characters
price_centsintegerBody · required- The price in cents, e.g. 5400 for $54.00.0 to 10000000
slugstringBody · optional- The product's address, /store/{slug}. Made from the name when left out.At most 60 characters
descriptionstringBody · optional- At most 4000 characters
image_urlstring | nullBody · optional- A picture from the site's library: a /media/… or /stock/… address.At most 500 characters
activebooleanBody · optional- Shown on the site. Default true.
weight_gramsinteger | nullBody · optional- Shipping weight of one, in grams (by-weight shipping). null = not weighed.0 to 1000000
kindstringBody · optional- physical (default), gift_card (each option's price is the card's value, at least 100 cents) or download (then add its file with upload_product_download).One of: physical, gift_card, download
optionsarray of objectBody · optional- The product's options (sizes, colours…), in order. Sending the list REPLACES the options: ones left out are deleted (past orders keep their own lines).
Response
201 with JSON on success (schema on the right). Errors use the standard envelope; a retry with the same Idempotency-Key gets the first answer back (how retries work).
curl -X POST 'https://websites.workflowcorp.com/api/v1/sites/SITE_ID/products' \
-H "Authorization: Bearer $WEBSITEBUDDY_API_KEY" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{"name":"Glazed serving bowl","price_cents":5400,"description":"Wide and shallow, for salads, fruit or bread.","image_url":"/stock/retail/pottery.jpg","options":[{"name":"Medium","stock":4},{"name":"Large","price_cents":6800,"stock":2}]}'{
"site_id": "SITE_ID",
"name": "Glazed serving bowl",
"price_cents": 5400,
"description": "Wide and shallow, for salads, fruit or bread.",
"image_url": "/stock/retail/pottery.jpg",
"options": [
{
"name": "Medium",
"stock": 4
},
{
"name": "Large",
"price_cents": 6800,
"stock": 2
}
]
}{
"type": "object",
"properties": {
"id": {
"type": "string"
},
"name": {
"type": "string"
},
"slug": {
"type": "string"
},
"description": {
"type": "string"
},
"price_cents": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"image_url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"weight_grams": {
"anyOf": [
{
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
{
"type": "null"
}
],
"description": "Shipping weight of one, in grams (for by-weight shipping); null = not weighed."
},
"kind": {
"type": "string",
"enum": [
"physical",
"gift_card",
"download"
],
"description": "physical = picked up or shipped; gift_card = a code emailed after payment, spent at checkout; download = a file emailed as a one-use link after payment."
},
"download": {
"anyOf": [
{
"type": "object",
"properties": {
"name": {
"type": "string"
},
"bytes": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
}
},
"required": [
"name",
"bytes"
],
"additionalProperties": false
},
{
"type": "null"
}
],
"description": "A download's file (upload it with upload_product_download); null for other kinds or before a file is added."
},
"active": {
"type": "boolean",
"description": "Shown on the site."
},
"address": {
"type": "string",
"description": "The product's page on the site's free address."
},
"options": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"name": {
"type": "string",
"description": "\"\" for a product with a single, unnamed option."
},
"price_cents": {
"anyOf": [
{
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
{
"type": "null"
}
],
"description": "null = the product's price."
},
"stock": {
"anyOf": [
{
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
{
"type": "null"
}
],
"description": "How many are left; null = not counted (always available)."
}
},
"required": [
"id",
"name",
"price_cents",
"stock"
],
"additionalProperties": false
}
},
"in_stock": {
"type": "boolean",
"description": "At least one option can be bought."
},
"is_sample": {
"type": "boolean"
},
"created_at": {
"type": "string"
},
"updated_at": {
"type": "string"
}
},
"required": [
"id",
"name",
"slug",
"description",
"price_cents",
"image_url",
"weight_grams",
"kind",
"download",
"active",
"address",
"options",
"in_stock",
"is_sample",
"created_at",
"updated_at"
],
"additionalProperties": false
}