check_availability: skill contract

check_availability returns real-time stock for one SKU. Only sku and in_stock are required in the response; every other field is optional.

Request

Machine-readable: /skills/v1/check_availability.request.schema.json

Field	Type	Required	Notes
`sku`	string	yes	Your SKU. 1–256 chars.

{
  "additionalProperties": false,
  "properties": {
    "sku": {
      "maxLength": 256,
      "minLength": 1,
      "type": "string"
    }
  },
  "required": ["sku"],
  "type": "object"
}

Example request

{
  "skill_id": "check_availability",
  "site_id": "01EXAMPLE00000000000000000",
  "arguments": {
    "sku": "beans_medium_12oz"
  },
  "observed_at": "2026-07-05T18:22:15.140Z",
  "nonce": "01K1EXAMPLE0000000000000000"
}

Response

Machine-readable: /skills/v1/check_availability.response.schema.json

Field	Type	Required	Notes
`sku`	string	yes	Echo the requested SKU.
`in_stock`	boolean	yes	`true` when at least one unit is available.
`quantity_on_hand`	integer	no	Non-negative. Omit if you do not want to expose a precise count.
`estimated_ship_days`	integer	no	Non-negative. Business days until dispatch.
`fulfillment_location`	string	no	1–256 chars. Merchant-defined identifier (warehouse code, city, region).

If the SKU is not in your catalog, return { "sku": "<requested>", "in_stock": false }, or 404 with an empty body. Do not return any other error status: it counts as a failed call, and 3 failures in a row mark the skill UNREACHABLE.

{
  "additionalProperties": false,
  "properties": {
    "estimated_ship_days": { "minimum": 0, "type": "integer" },
    "fulfillment_location": { "maxLength": 256, "minLength": 1, "type": "string" },
    "in_stock": { "type": "boolean" },
    "quantity_on_hand": { "minimum": 0, "type": "integer" },
    "sku": { "maxLength": 256, "minLength": 1, "type": "string" }
  },
  "required": ["sku", "in_stock"],
  "type": "object"
}

Example response

{
  "sku": "beans_medium_12oz",
  "in_stock": true,
  "quantity_on_hand": 42,
  "estimated_ship_days": 1,
  "fulfillment_location": "US-EAST-WAREHOUSE"
}

What Sill checks

A response that does not match the schema is not passed to the agent and counts as a failed call; 3 failures in a row mark the skill UNREACHABLE. Common causes:

An extra field, such as per-variant data or an internal bin location.
A number sent as a string, such as "quantity_on_hand": "42".

Verify the signature

Check the X-Sill-Signature header on every request before answering. The scheme is the same for every skill; see Verify the signature for tested TypeScript, Python and Go code.