Set an option's stock

Sets how many of one option are left (null = stop counting; it is then always available). A product shows as sold out when every counted option is at 0. Live at once — use it to sync stock from a till or warehouse.

PATCH/api/v1/sites/{site_id}/products/{product_id}/options/{option_id}

Authentication

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 optionalMCP tool: update_product_stock

Parameters

Named placeholders go in the path; the rest in a JSON body.

site_idstringPath · required: The site's id.1 to 100 characters
product_idstringPath · required: The product's id.1 to 100 characters
option_idstringPath · required: The option's id.1 to 100 characters
stockinteger | nullBody · required: How many are left; null = not counted.0 to 99999

Response

200 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

curl -X PATCH 'https://websites.workflowcorp.com/api/v1/sites/SITE_ID/products/PRODUCT_ID/options/OPTION_ID' \
  -H "Authorization: Bearer $WEBSITEBUDDY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"stock":12}'

Example arguments

{
  "site_id": "SITE_ID",
  "product_id": "PRODUCT_ID",
  "option_id": "OPTION_ID",
  "stock": 12
}

Response schema

{
  "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
}