{
  "openapi": "3.1.0",
  "info": {
    "title": "Sous Chef Ordering API",
    "summary": "Send orders to the restaurants on your ordering channel, keep their delivery status current, and read your stores, their menus and your orders.",
    "version": "0.1.0-draft",
    "description": "The Sous Chef Ordering API is the interface for ordering channels: platforms and storefronts that\ntake orders from guests and send them to restaurants. A channel sends each order to a store on its\nchannel, keeps the delivery status current, and receives signed webhooks as the restaurant handles\nthe order.\n\n## Shape of every call\n\nEvery operation is a **POST** with a single JSON body and a single JSON reply. There are no path\nparameters and no query strings, so a request is fully described by its URL and its body.\n\nThe base path carries **no version segment**. Changes are additive: new optional fields and new\noperations are added. Write your client to ignore fields it does not recognise and it keeps\nworking.\n\n## Authentication\n\nSend your channel key in the `x-api-key` header on every request. It is the only credential. Do not\nsend an organization header.\n\n## Conventions\n\n- **Money is an integer in the currency's minor unit.** `1250` is $12.50.\n- **Times are ISO-8601 in UTC.** Resolve a store's local time from its IANA `timezone`.\n- **Stores are addressed by `code`**, from `fetchStores`. Orders are addressed by your own id,\n  `platformOrderId`. It is the idempotency key, and it must be unique across every order you send.\n\nEvery route under `paths` states whether it is safe to retry, derived from the endpoint's\ndeclared side-effect contract. It covers routes only: a webhook is a call we send, and we\nretry its delivery ourselves, so a webhook carries no retry sentence.\n\n| declared operation | read-only | destructive | idempotent |\n|---|---|---|---|\n| read | yes | no | yes |\n| write-idempotent | no | yes | yes |\n| write | no | yes | no |"
  },
  "servers": [
    {
      "url": "https://api.yoursouschef.com",
      "description": "Production"
    }
  ],
  "tags": [
    {
      "name": "Orders",
      "description": "Send orders to the restaurants on your channel, move them along, and read them back.\n\nStores are addressed by their `code` from `fetchStores`. A code that is unknown, retired or not on\nyour channel answers `404`, indistinguishably. Orders are addressed by YOUR id, `platformOrderId`:\nit is the idempotency key, and it must be unique across every order you send. Sous Chef's own id\nfor the order arrives as `id` on every `order.*` webhook and on `fetchOrder`.\n\n`200` on a write means we accepted the call for processing, not that the order has reached the\nkitchen. An order for a store that is paused or outside its hours comes back as an\n`order.rejected` webhook. Every other order goes to the kitchen: `fetchOrder` returns it, and its\nprogress arrives as `order.status.updated` when it becomes `ready` and then `finished`. Every\nwrite is idempotent, so retry on `500` / `503` freely."
    },
    {
      "name": "Stores",
      "description": "The stores on your channel, in every organization that sells through it. Only these stores accept\nyour orders, and only their menus and orders are readable with your key."
    },
    {
      "name": "Menus",
      "description": "The menus of the stores on your channel. Pull a store's menu with `fetchMenu`; you are told when\nan item or a modifier option becomes unavailable, or available again, through the\n`item.availability.changed` webhook."
    }
  ],
  "security": [
    {
      "ApiKeyAuth": []
    }
  ],
  "paths": {
    "/ordering/orders/createOrder": {
      "post": {
        "operationId": "createOrder",
        "summary": "Create an order",
        "description": "Place an order at one of your channel's stores.\n\nRequired: `storeCode`, `platformOrderId`, `fulfillment`, at least one entry in `items`, `subtotal`\nand `total`. Each item needs `itemId`, `name`, `quantity` and `unitPrice`; each modifier needs\n`itemId`, `name` and `quantity`. A `scheduled` order also needs a future `estimatedPickupAt`; a\n`restaurantDelivery` order needs `deliveryAddress`. A required field that is missing or empty,\nor a value that is not one of those listed for its field, is a `400`.\n\nRe-sending the same `storeCode` and `platformOrderId` answers `200` and creates nothing twice.\nA `platformOrderId` that was already used for another order is not created a second time.\n\nStatuses beyond the common ones: `404` the `storeCode` is unknown, retired or not on your channel;\n`422` the store does not take orders through this API.\n\nSafe to retry: this operation changes state but is idempotent.",
        "tags": [
          "Orders"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "title": "CreateOrderRequest",
                "description": "Request for `OrderingOrdersApi.createOrder`.\n\nEvery field is optional in the type; the ones marked \"Required.\" are enforced by the server with\na `400`. Money is an integer in the currency's minor unit (cents for USD), never a decimal.",
                "properties": {
                  "storeCode": {
                    "type": "string",
                    "description": "Required. The store's `code` from `fetchStores`."
                  },
                  "platformOrderId": {
                    "type": "string",
                    "description": "Required. Your own id for the order, and the idempotency key: sending the same `storeCode`\nand `platformOrderId` again answers `200` and creates nothing twice. It must be unique across\nevery order you send, not only within one store. It comes back as `platformOrderId` on every\n`order.*` webhook and on `fetchOrder`."
                  },
                  "displayId": {
                    "type": "string",
                    "description": "A short reference the guest and courier see."
                  },
                  "placedAt": {
                    "type": "string",
                    "format": "date-time",
                    "description": "When the guest placed the order. Absent means the time we received it."
                  },
                  "fulfillment": {
                    "$ref": "#/components/schemas/OrderFulfillment",
                    "description": "Required. How the guest receives the order."
                  },
                  "scheduling": {
                    "$ref": "#/components/schemas/OrderScheduling",
                    "description": "`asap` (the default) or `scheduled`."
                  },
                  "estimatedPickupAt": {
                    "type": "string",
                    "format": "date-time",
                    "description": "When the order should be ready for pickup. Required when `scheduling` is `scheduled`, and must\nthen be in the future."
                  },
                  "customer": {
                    "$ref": "#/components/schemas/OrderCustomer",
                    "description": "The guest. Personal data."
                  },
                  "deliveryAddress": {
                    "$ref": "#/components/schemas/OrderDeliveryAddress",
                    "description": "Where to deliver. Required when `fulfillment` is `restaurantDelivery`. Personal data."
                  },
                  "note": {
                    "type": "string",
                    "description": "The guest's note for the kitchen. Personal data."
                  },
                  "deliveryNote": {
                    "type": "string",
                    "description": "A note for the courier or the delivering restaurant. Personal data."
                  },
                  "utensils": {
                    "type": "boolean",
                    "description": "Whether the guest wants utensils."
                  },
                  "items": {
                    "type": "array",
                    "items": {
                      "$ref": "#/components/schemas/OrderIntakeItem"
                    },
                    "description": "Required. At least one line."
                  },
                  "promotions": {
                    "type": "array",
                    "items": {
                      "$ref": "#/components/schemas/OrderIntakePromotion"
                    },
                    "description": "Promotions applied to the order."
                  },
                  "subtotal": {
                    "type": "number",
                    "description": "Required. Items before discounts, tax, tip and fees, in the currency's minor unit."
                  },
                  "tax": {
                    "type": "number",
                    "description": "Tax, in the currency's minor unit."
                  },
                  "tip": {
                    "type": "number",
                    "description": "Tip, in the currency's minor unit."
                  },
                  "deliveryFee": {
                    "type": "number",
                    "description": "Delivery fee, in the currency's minor unit."
                  },
                  "serviceFee": {
                    "type": "number",
                    "description": "Service fee, in the currency's minor unit."
                  },
                  "total": {
                    "type": "number",
                    "description": "Required. What the restaurant is owed, as you state it, in the currency's minor unit."
                  },
                  "totalDiscount": {
                    "type": "number",
                    "description": "Total discount, in the currency's minor unit."
                  },
                  "restaurantFundedDiscount": {
                    "type": "number",
                    "description": "The part of the discount the restaurant funds, in the currency's minor unit."
                  },
                  "platformFundedDiscount": {
                    "type": "number",
                    "description": "The part of the discount the platform funds, in the currency's minor unit."
                  },
                  "isTaxRemittedByPlatform": {
                    "type": "boolean",
                    "description": "Whether the platform remits the tax itself."
                  },
                  "taxCollected": {
                    "type": "number",
                    "description": "Tax the platform collected, in the currency's minor unit."
                  },
                  "taxableBase": {
                    "type": "number",
                    "description": "The amount tax applies to, in the currency's minor unit."
                  },
                  "grandTotal": {
                    "type": "number",
                    "description": "What the guest paid, in the currency's minor unit."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The order as received. What happens to it next follows as a webhook.",
            "headers": {
              "x-mealco-tx-id": {
                "$ref": "#/components/headers/x-mealco-tx-id"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "title": "CreateOrderResponse",
                  "description": "Reply from `OrderingOrdersApi.createOrder`.",
                  "properties": {
                    "platformOrderId": {
                      "type": "string",
                      "description": "Your `platformOrderId`, echoed."
                    },
                    "storeCode": {
                      "type": "string",
                      "description": "Your `storeCode`, echoed."
                    },
                    "receivedAt": {
                      "type": "string",
                      "format": "date-time",
                      "description": "When we received the order."
                    },
                    "status": {
                      "$ref": "#/components/schemas/OrderIntakeStatus",
                      "description": "What happened to the order: `queued`. `200` does not mean that the order has reached the\nkitchen: an order for a store that is paused or outside its hours comes back as an\n`order.rejected` webhook."
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "The request body failed validation. Correct the request; a retry returns the same answer.",
            "headers": {
              "x-mealco-tx-id": {
                "$ref": "#/components/headers/x-mealco-tx-id"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/OrderingApiError"
                }
              }
            }
          },
          "401": {
            "description": "Missing, unknown or revoked channel key (x-api-key). Correct the credentials before you send the request again.",
            "headers": {
              "x-mealco-tx-id": {
                "$ref": "#/components/headers/x-mealco-tx-id"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/OrderingApiError"
                }
              }
            }
          },
          "429": {
            "description": "Over the rate limit: 300 requests per minute per channel key (x-api-key). Honour the `Retry-After` header when it is present; otherwise wait 60 seconds, then retry.",
            "headers": {
              "x-mealco-tx-id": {
                "$ref": "#/components/headers/x-mealco-tx-id"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/OrderingApiError"
                }
              }
            }
          },
          "500": {
            "description": "A fault on our side. Retry with exponential backoff and jitter.",
            "headers": {
              "x-mealco-tx-id": {
                "$ref": "#/components/headers/x-mealco-tx-id"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/OrderingApiError"
                }
              }
            }
          }
        }
      }
    },
    "/ordering/orders/cancelOrder": {
      "post": {
        "operationId": "cancelOrder",
        "summary": "Cancel an order",
        "description": "Cancel an order you created.\n\nIdempotent: cancelling an order that is already cancelled, finished or rejected does nothing and\nsends no webhook. A cancellation that arrives just before its order is held and applied once the\norder exists, for up to five minutes.\n\nStatuses beyond the common ones: `404` and `422` as on `createOrder`.\n\nSafe to retry: this operation changes state but is idempotent.",
        "tags": [
          "Orders"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "title": "CancelOrderRequest",
                "description": "Request for `OrderingOrdersApi.cancelOrder`.",
                "properties": {
                  "storeCode": {
                    "type": "string",
                    "description": "Required. The store's `code`. Required so you can never cancel another channel's order."
                  },
                  "platformOrderId": {
                    "type": "string",
                    "description": "Required. The `platformOrderId` you sent on `createOrder`."
                  },
                  "reason": {
                    "$ref": "#/components/schemas/OrderCancelReason",
                    "description": "Why. Defaults to `other`."
                  },
                  "details": {
                    "type": "string",
                    "description": "Free-text detail. Personal data."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The cancellation as received. A cancelled order follows as an `order.cancelled` webhook.",
            "headers": {
              "x-mealco-tx-id": {
                "$ref": "#/components/headers/x-mealco-tx-id"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "title": "CancelOrderResponse",
                  "description": "Reply from `OrderingOrdersApi.cancelOrder`.",
                  "properties": {
                    "platformOrderId": {
                      "type": "string",
                      "description": "Your `platformOrderId`, echoed."
                    },
                    "storeCode": {
                      "type": "string",
                      "description": "Your `storeCode`, echoed."
                    },
                    "receivedAt": {
                      "type": "string",
                      "format": "date-time",
                      "description": "When we received the cancellation."
                    },
                    "status": {
                      "$ref": "#/components/schemas/OrderIntakeStatus",
                      "description": "What happened to the cancellation: `queued`."
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "The request body failed validation. Correct the request; a retry returns the same answer.",
            "headers": {
              "x-mealco-tx-id": {
                "$ref": "#/components/headers/x-mealco-tx-id"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/OrderingApiError"
                }
              }
            }
          },
          "401": {
            "description": "Missing, unknown or revoked channel key (x-api-key). Correct the credentials before you send the request again.",
            "headers": {
              "x-mealco-tx-id": {
                "$ref": "#/components/headers/x-mealco-tx-id"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/OrderingApiError"
                }
              }
            }
          },
          "429": {
            "description": "Over the rate limit: 300 requests per minute per channel key (x-api-key). Honour the `Retry-After` header when it is present; otherwise wait 60 seconds, then retry.",
            "headers": {
              "x-mealco-tx-id": {
                "$ref": "#/components/headers/x-mealco-tx-id"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/OrderingApiError"
                }
              }
            }
          },
          "500": {
            "description": "A fault on our side. Retry with exponential backoff and jitter.",
            "headers": {
              "x-mealco-tx-id": {
                "$ref": "#/components/headers/x-mealco-tx-id"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/OrderingApiError"
                }
              }
            }
          }
        }
      }
    },
    "/ordering/orders/updateOrderDeliveryStatus": {
      "post": {
        "operationId": "updateOrderDeliveryStatus",
        "summary": "Update an order's delivery status",
        "description": "Tell us where a delivery stands (assigned, on the way to the store, on the way to the guest,\ncompleted or canceled) and who the courier is. The restaurant sees it on the order and you read\nit back as `order.delivery.updated`.\n\nStatuses beyond the common ones: `404` and `422` as on `createOrder`.\n\nSafe to retry: this operation changes state but is idempotent.",
        "tags": [
          "Orders"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "title": "UpdateOrderDeliveryStatusRequest",
                "description": "Request for `OrderingOrdersApi.updateOrderDeliveryStatus`.",
                "properties": {
                  "storeCode": {
                    "type": "string",
                    "description": "Required. The store's `code`."
                  },
                  "platformOrderId": {
                    "type": "string",
                    "description": "Required. The `platformOrderId` you sent on `createOrder`."
                  },
                  "deliveryStatus": {
                    "$ref": "#/components/schemas/OrderDeliveryStatus",
                    "description": "Required. Where the delivery stands. The same values `order.delivery.updated` reports."
                  },
                  "courier": {
                    "$ref": "#/components/schemas/OrderCourier",
                    "description": "The courier, once one is assigned. Personal data."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The update as received.",
            "headers": {
              "x-mealco-tx-id": {
                "$ref": "#/components/headers/x-mealco-tx-id"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "title": "UpdateOrderDeliveryStatusResponse",
                  "description": "Reply from `OrderingOrdersApi.updateOrderDeliveryStatus`.",
                  "properties": {
                    "platformOrderId": {
                      "type": "string",
                      "description": "Your `platformOrderId`, echoed."
                    },
                    "storeCode": {
                      "type": "string",
                      "description": "Your `storeCode`, echoed."
                    },
                    "receivedAt": {
                      "type": "string",
                      "format": "date-time",
                      "description": "When we received the update."
                    },
                    "status": {
                      "$ref": "#/components/schemas/OrderIntakeStatus",
                      "description": "What happened to the update: `queued`."
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "The request body failed validation. Correct the request; a retry returns the same answer.",
            "headers": {
              "x-mealco-tx-id": {
                "$ref": "#/components/headers/x-mealco-tx-id"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/OrderingApiError"
                }
              }
            }
          },
          "401": {
            "description": "Missing, unknown or revoked channel key (x-api-key). Correct the credentials before you send the request again.",
            "headers": {
              "x-mealco-tx-id": {
                "$ref": "#/components/headers/x-mealco-tx-id"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/OrderingApiError"
                }
              }
            }
          },
          "429": {
            "description": "Over the rate limit: 300 requests per minute per channel key (x-api-key). Honour the `Retry-After` header when it is present; otherwise wait 60 seconds, then retry.",
            "headers": {
              "x-mealco-tx-id": {
                "$ref": "#/components/headers/x-mealco-tx-id"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/OrderingApiError"
                }
              }
            }
          },
          "500": {
            "description": "A fault on our side. Retry with exponential backoff and jitter.",
            "headers": {
              "x-mealco-tx-id": {
                "$ref": "#/components/headers/x-mealco-tx-id"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/OrderingApiError"
                }
              }
            }
          }
        }
      }
    },
    "/ordering/orders/fetchOrder": {
      "post": {
        "operationId": "fetchOrder",
        "summary": "Fetch an order",
        "description": "Read one of your orders back by your own id.\n\nStatuses beyond the common ones: `404` the store is not on your channel, or no order with that\n`platformOrderId` exists there yet (it may still be queued).\n\nSafe to retry: this operation is read-only and idempotent.",
        "tags": [
          "Orders"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "title": "FetchOrderRequest",
                "description": "Request for `fetchOrder`.",
                "properties": {
                  "storeCode": {
                    "type": "string",
                    "description": "Required. The store's `code` from `fetchStores`."
                  },
                  "platformOrderId": {
                    "type": "string",
                    "description": "Required. The `platformOrderId` you sent on `createOrder`."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The order, with Sous Chef's `id` beside your `platformOrderId`.",
            "headers": {
              "x-mealco-tx-id": {
                "$ref": "#/components/headers/x-mealco-tx-id"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "title": "FetchOrderResponse",
                  "description": "Reply from `fetchOrder`.",
                  "properties": {
                    "order": {
                      "$ref": "#/components/schemas/Order",
                      "description": "The order. `id` is Sous Chef's id for it; `platformOrderId` is yours. An object wrapper so later\nversions can add sibling fields additively."
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "The request body failed validation. Correct the request; a retry returns the same answer.",
            "headers": {
              "x-mealco-tx-id": {
                "$ref": "#/components/headers/x-mealco-tx-id"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/OrderingApiError"
                }
              }
            }
          },
          "401": {
            "description": "Missing, unknown or revoked channel key (x-api-key). Correct the credentials before you send the request again.",
            "headers": {
              "x-mealco-tx-id": {
                "$ref": "#/components/headers/x-mealco-tx-id"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/OrderingApiError"
                }
              }
            }
          },
          "429": {
            "description": "Over the rate limit: 300 requests per minute per channel key (x-api-key). Honour the `Retry-After` header when it is present; otherwise wait 60 seconds, then retry.",
            "headers": {
              "x-mealco-tx-id": {
                "$ref": "#/components/headers/x-mealco-tx-id"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/OrderingApiError"
                }
              }
            }
          },
          "500": {
            "description": "A fault on our side. Retry with exponential backoff and jitter.",
            "headers": {
              "x-mealco-tx-id": {
                "$ref": "#/components/headers/x-mealco-tx-id"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/OrderingApiError"
                }
              }
            }
          }
        }
      }
    },
    "/ordering/stores/fetchStores": {
      "post": {
        "operationId": "fetchStores",
        "summary": "Fetch your stores",
        "description": "List the stores on your channel.\n\nSafe to retry: this operation is read-only and idempotent.",
        "tags": [
          "Stores"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "title": "FetchStoresRequest",
                "description": "Request for `fetchStores`.",
                "properties": {
                  "offset": {
                    "type": "integer",
                    "description": "Stores to skip. Default `0`."
                  },
                  "limit": {
                    "type": "integer",
                    "description": "Page size, `1` to `100`. Default `100`."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "A page of stores.",
            "headers": {
              "x-mealco-tx-id": {
                "$ref": "#/components/headers/x-mealco-tx-id"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "title": "FetchStoresResponse",
                  "description": "Reply from `fetchStores`.",
                  "properties": {
                    "stores": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/ChannelStore"
                      },
                      "description": "The page of stores, ordered stably so offset paging is consistent."
                    },
                    "total": {
                      "type": "integer",
                      "description": "How many stores your channel has in total."
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "The request body failed validation. Correct the request; a retry returns the same answer.",
            "headers": {
              "x-mealco-tx-id": {
                "$ref": "#/components/headers/x-mealco-tx-id"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/OrderingApiError"
                }
              }
            }
          },
          "401": {
            "description": "Missing, unknown or revoked channel key (x-api-key). Correct the credentials before you send the request again.",
            "headers": {
              "x-mealco-tx-id": {
                "$ref": "#/components/headers/x-mealco-tx-id"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/OrderingApiError"
                }
              }
            }
          },
          "429": {
            "description": "Over the rate limit: 300 requests per minute per channel key (x-api-key). Honour the `Retry-After` header when it is present; otherwise wait 60 seconds, then retry.",
            "headers": {
              "x-mealco-tx-id": {
                "$ref": "#/components/headers/x-mealco-tx-id"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/OrderingApiError"
                }
              }
            }
          },
          "500": {
            "description": "A fault on our side. Retry with exponential backoff and jitter.",
            "headers": {
              "x-mealco-tx-id": {
                "$ref": "#/components/headers/x-mealco-tx-id"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/OrderingApiError"
                }
              }
            }
          }
        }
      }
    },
    "/ordering/menus/fetchMenu": {
      "post": {
        "operationId": "fetchMenu",
        "summary": "Fetch a store's menu",
        "description": "Fetch what a store sells.\n\nStatuses beyond the common ones: `404` the `storeCode` is unknown, retired or not on your channel.\n\nSafe to retry: this operation is read-only and idempotent.",
        "tags": [
          "Menus"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "title": "FetchMenuRequest",
                "description": "Request for `fetchMenu`.",
                "properties": {
                  "storeCode": {
                    "type": "string",
                    "description": "Required. The store's `code` from `fetchStores`."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The store's menus.",
            "headers": {
              "x-mealco-tx-id": {
                "$ref": "#/components/headers/x-mealco-tx-id"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "title": "FetchMenuResponse",
                  "description": "Reply from `fetchMenu`.",
                  "properties": {
                    "menus": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Menu"
                      },
                      "description": "The menus the store sells, with prices and availability resolved for that store. Usually one.\nItem and modifier ids here are what `createOrder` takes."
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "The request body failed validation. Correct the request; a retry returns the same answer.",
            "headers": {
              "x-mealco-tx-id": {
                "$ref": "#/components/headers/x-mealco-tx-id"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/OrderingApiError"
                }
              }
            }
          },
          "401": {
            "description": "Missing, unknown or revoked channel key (x-api-key). Correct the credentials before you send the request again.",
            "headers": {
              "x-mealco-tx-id": {
                "$ref": "#/components/headers/x-mealco-tx-id"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/OrderingApiError"
                }
              }
            }
          },
          "429": {
            "description": "Over the rate limit: 300 requests per minute per channel key (x-api-key). Honour the `Retry-After` header when it is present; otherwise wait 60 seconds, then retry.",
            "headers": {
              "x-mealco-tx-id": {
                "$ref": "#/components/headers/x-mealco-tx-id"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/OrderingApiError"
                }
              }
            }
          },
          "500": {
            "description": "A fault on our side. Retry with exponential backoff and jitter.",
            "headers": {
              "x-mealco-tx-id": {
                "$ref": "#/components/headers/x-mealco-tx-id"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/OrderingApiError"
                }
              }
            }
          }
        }
      }
    }
  },
  "webhooks": {
    "order.status.updated": {
      "post": {
        "operationId": "orderStatusUpdatedWebhook",
        "summary": "Order status updated",
        "description": "An order moved through its lifecycle: it became `ready`, or `finished`. There is no event for\nan order reaching the kitchen.\n\nDelivered to the webhook URL registered for your channel, alongside every other event. Return\nany 2xx to acknowledge; anything else is retried up to four more times.\n\nOrder by the transported state (`data.updatedAt`, `data.status`), never by arrival: deliveries\nare unordered.",
        "tags": [
          "Orders"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "title": "OrderStatusUpdatedEvent",
                "description": "An order moved through its lifecycle: `ready`, then `finished`.",
                "properties": {
                  "id": {
                    "type": "string",
                    "description": "Unique event id: the deduplication key.\n\nA delivery that is not acknowledged is sent again, and deliveries are unordered, so you WILL\nreceive the same event more than once. Every copy of one event carries the same `id`. Two\nlegitimate transitions of the same order are two different events and carry two different ids.\n\nKey your idempotency on this field alone. `timestamp` is the moment the attempt was SENT and\ndiffers between copies of one event."
                  },
                  "event": {
                    "type": "string",
                    "enum": [
                      "order.status.updated"
                    ],
                    "description": "Always `order.status.updated`."
                  },
                  "timestamp": {
                    "type": "string",
                    "format": "date-time",
                    "description": "When this delivery was SENT, not when the event happened. Order by the transported state,\nnever by arrival."
                  },
                  "organization_id": {
                    "type": "string",
                    "description": "Your channel's organization id, the same on every delivery to you. It is your channel's\norganization, not the restaurant's.\n\nSnake case on this one field is a long-lived wire value; every other field on this API is\ncamelCase.\n\nTreat it as a sanity check, never as proof of origin. Proof of origin is the\n`X-SousChef-Signature` header, which every delivery on this API carries (the same value is also\nsent as `X-OneTablet-Signature`, for backward compatibility); see \"Verifying webhook\nsignatures\"."
                  },
                  "data": {
                    "$ref": "#/components/schemas/Order",
                    "description": "The order, carrying its new `status`."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Return any 2xx to acknowledge delivery; the body is ignored."
          }
        }
      }
    },
    "order.rejected": {
      "post": {
        "operationId": "orderRejectedWebhook",
        "summary": "Order rejected",
        "description": "An order was rejected at intake, because the store was paused or outside its hours.",
        "tags": [
          "Orders"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "title": "OrderRejectedEvent",
                "description": "An order was rejected automatically at intake, because the store was paused or the order fell\noutside the store's operating or special hours. `data.rejectReason` and `data.rejectReasonCode`\nsay why.",
                "properties": {
                  "id": {
                    "type": "string",
                    "description": "Unique event id: the deduplication key.\n\nA delivery that is not acknowledged is sent again, and deliveries are unordered, so you WILL\nreceive the same event more than once. Every copy of one event carries the same `id`. Two\nlegitimate transitions of the same order are two different events and carry two different ids.\n\nKey your idempotency on this field alone. `timestamp` is the moment the attempt was SENT and\ndiffers between copies of one event."
                  },
                  "event": {
                    "type": "string",
                    "enum": [
                      "order.rejected"
                    ],
                    "description": "Always `order.rejected`."
                  },
                  "timestamp": {
                    "type": "string",
                    "format": "date-time",
                    "description": "When this delivery was SENT, not when the event happened. Order by the transported state,\nnever by arrival."
                  },
                  "organization_id": {
                    "type": "string",
                    "description": "Your channel's organization id, the same on every delivery to you. It is your channel's\norganization, not the restaurant's.\n\nSnake case on this one field is a long-lived wire value; every other field on this API is\ncamelCase.\n\nTreat it as a sanity check, never as proof of origin. Proof of origin is the\n`X-SousChef-Signature` header, which every delivery on this API carries (the same value is also\nsent as `X-OneTablet-Signature`, for backward compatibility); see \"Verifying webhook\nsignatures\"."
                  },
                  "data": {
                    "$ref": "#/components/schemas/Order",
                    "description": "The order, with `status: rejected`."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Return any 2xx to acknowledge delivery; the body is ignored."
          }
        }
      }
    },
    "order.cancelled": {
      "post": {
        "operationId": "orderCancelledWebhook",
        "summary": "Order cancelled",
        "description": "An order was cancelled, with who cancelled it, why, and when.",
        "tags": [
          "Orders"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "title": "OrderCancelledEvent",
                "description": "An order was cancelled, by the restaurant or by you. Spelled `order.cancelled`, two `l`s.",
                "properties": {
                  "id": {
                    "type": "string",
                    "description": "Unique event id: the deduplication key.\n\nA delivery that is not acknowledged is sent again, and deliveries are unordered, so you WILL\nreceive the same event more than once. Every copy of one event carries the same `id`. Two\nlegitimate transitions of the same order are two different events and carry two different ids.\n\nKey your idempotency on this field alone. `timestamp` is the moment the attempt was SENT and\ndiffers between copies of one event."
                  },
                  "event": {
                    "type": "string",
                    "enum": [
                      "order.cancelled"
                    ],
                    "description": "Always `order.cancelled`, two `l`s."
                  },
                  "timestamp": {
                    "type": "string",
                    "format": "date-time",
                    "description": "When this delivery was SENT, not when the event happened. Order by the transported state,\nnever by arrival."
                  },
                  "organization_id": {
                    "type": "string",
                    "description": "Your channel's organization id, the same on every delivery to you. It is your channel's\norganization, not the restaurant's.\n\nSnake case on this one field is a long-lived wire value; every other field on this API is\ncamelCase.\n\nTreat it as a sanity check, never as proof of origin. Proof of origin is the\n`X-SousChef-Signature` header, which every delivery on this API carries (the same value is also\nsent as `X-OneTablet-Signature`, for backward compatibility); see \"Verifying webhook\nsignatures\"."
                  },
                  "data": {
                    "$ref": "#/components/schemas/CancelledOrder",
                    "description": "The cancelled order, carrying `by`, `reason` and `at`."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Return any 2xx to acknowledge delivery; the body is ignored."
          }
        }
      }
    },
    "order.delivery.updated": {
      "post": {
        "operationId": "orderDeliveryUpdatedWebhook",
        "summary": "Order delivery updated",
        "description": "Courier lifecycle of an order. Deduplicate on the envelope's `id`: successive courier\ntransitions of one order are separate events with separate ids.",
        "tags": [
          "Orders"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "title": "OrderDeliveryUpdatedEvent",
                "description": "Courier lifecycle of an order, as you reported it with `updateOrderDeliveryStatus`.",
                "properties": {
                  "id": {
                    "type": "string",
                    "description": "Unique event id: the deduplication key.\n\nA delivery that is not acknowledged is sent again, and deliveries are unordered, so you WILL\nreceive the same event more than once. Every copy of one event carries the same `id`. Two\nlegitimate transitions of the same order are two different events and carry two different ids.\n\nKey your idempotency on this field alone. `timestamp` is the moment the attempt was SENT and\ndiffers between copies of one event."
                  },
                  "event": {
                    "type": "string",
                    "enum": [
                      "order.delivery.updated"
                    ],
                    "description": "Always `order.delivery.updated`."
                  },
                  "timestamp": {
                    "type": "string",
                    "format": "date-time",
                    "description": "When this delivery was SENT, not when the event happened. Order by the transported state,\nnever by arrival."
                  },
                  "organization_id": {
                    "type": "string",
                    "description": "Your channel's organization id, the same on every delivery to you. It is your channel's\norganization, not the restaurant's.\n\nSnake case on this one field is a long-lived wire value; every other field on this API is\ncamelCase.\n\nTreat it as a sanity check, never as proof of origin. Proof of origin is the\n`X-SousChef-Signature` header, which every delivery on this API carries (the same value is also\nsent as `X-OneTablet-Signature`, for backward compatibility); see \"Verifying webhook\nsignatures\"."
                  },
                  "data": {
                    "$ref": "#/components/schemas/Order",
                    "description": "The order, carrying its new `deliveryStatus`."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Return any 2xx to acknowledge delivery; the body is ignored."
          }
        }
      }
    },
    "item.availability.changed": {
      "post": {
        "operationId": "itemAvailabilityChangedWebhook",
        "summary": "Item availability changed",
        "description": "Items were marked out of stock or restocked at a kitchen that sells them through stores on\nyour channel.\n\nDelivered to the webhook URL registered for your channel. Return any 2xx to acknowledge;\nanything else is retried up to four more times. Deduplicate on the envelope's `id`.",
        "tags": [
          "Menus"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "title": "ItemAvailabilityChangedEvent",
                "description": "An item or modifier option was marked out of stock or back in stock at a kitchen that sells it\nthrough a store on your channel. Stop selling an out-of-stock item until it is back: orders are\nnot checked against stock at intake.",
                "properties": {
                  "id": {
                    "type": "string",
                    "description": "Unique event id: the deduplication key.\n\nA delivery that is not acknowledged is sent again, and deliveries are unordered, so you WILL\nreceive the same event more than once. Every copy of one event carries the same `id`. Two\nlegitimate transitions of the same order are two different events and carry two different ids.\n\nKey your idempotency on this field alone. `timestamp` is the moment the attempt was SENT and\ndiffers between copies of one event."
                  },
                  "event": {
                    "type": "string",
                    "enum": [
                      "item.availability.changed"
                    ],
                    "description": "Always `item.availability.changed`."
                  },
                  "timestamp": {
                    "type": "string",
                    "format": "date-time",
                    "description": "When this delivery was SENT, not when the event happened. Order by the transported state,\nnever by arrival."
                  },
                  "organization_id": {
                    "type": "string",
                    "description": "Your channel's organization id, the same on every delivery to you. It is your channel's\norganization, not the restaurant's.\n\nSnake case on this one field is a long-lived wire value; every other field on this API is\ncamelCase.\n\nTreat it as a sanity check, never as proof of origin. Proof of origin is the\n`X-SousChef-Signature` header, which every delivery on this API carries (the same value is also\nsent as `X-OneTablet-Signature`, for backward compatibility); see \"Verifying webhook\nsignatures\"."
                  },
                  "data": {
                    "$ref": "#/components/schemas/ItemAvailabilityChange",
                    "description": "The change."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Return any 2xx to acknowledge delivery; the body is ignored."
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "CancelledOrder": {
        "type": "object",
        "description": "The order as it stands after a cancellation, plus who cancelled it and when.",
        "properties": {
          "id": {
            "type": "string",
            "description": "Sous Chef's identifier for the order (uuid)."
          },
          "platformOrderId": {
            "type": "string",
            "description": "The id the order has on the platform or channel it came from: the order id a channel partner\nsent when it placed the order. Absent when the platform sends none."
          },
          "status": {
            "$ref": "#/components/schemas/OrderStatus",
            "description": "Current state of the order."
          },
          "deliveryStatus": {
            "$ref": "#/components/schemas/OrderDeliveryStatus",
            "description": "Delivery progress, where the platform transmits it."
          },
          "createdAt": {
            "type": "string",
            "format": "date-time",
            "description": "When the order record was created, ISO-8601 UTC."
          },
          "updatedAt": {
            "type": "string",
            "format": "date-time",
            "description": "When the order record last changed, ISO-8601 UTC."
          },
          "estimatedReadyAt": {
            "type": "string",
            "format": "date-time",
            "description": "When the kitchen expects the order to be ready, ISO-8601 UTC. Set when Sous Chef accepts the\norder, from the kitchen's preparation time. A scheduled order carries its scheduled time.\n\nCarried on the order webhooks. Absent when no estimate exists, and on `fetchOrder`."
          },
          "rejectReason": {
            "type": "string",
            "description": "Why the order was rejected, in words (on `order.rejected` only). For example \"Order at 23:10 is\noutside business hours\"."
          },
          "rejectReasonCode": {
            "$ref": "#/components/schemas/OrderCancelReason",
            "description": "Why the order was rejected, as a code (on `order.rejected` only). It is `storeClosed`, which\ncovers a paused store and an order outside the store's hours."
          },
          "store": {
            "$ref": "#/components/schemas/OrderStore",
            "description": "The storefront the order arrived through: which brand, at which kitchen, on which platform.\n\nOn `fetchOrder`; not on the order webhooks."
          },
          "cancellation": {
            "$ref": "#/components/schemas/OrderCancellation",
            "description": "Who cancelled the order, why and when. On `fetchOrder`, present on every\norder whose `status` is `cancelled` and on no other. The `order.cancelled` webhook carries the\nsame facts as top-level fields of its payload instead."
          },
          "details": {
            "$ref": "#/components/schemas/OrderDetails",
            "description": "What was ordered and what it cost: items with their modifiers, promotions, and the order's\nsubtotal, tax, tip, delivery fee and total in cents.\n\nOn `fetchOrder`; not on the order webhooks."
          },
          "by": {
            "type": "string",
            "description": "Who cancelled the order."
          },
          "reason": {
            "type": "string",
            "description": "Why the order was cancelled, as reported by the cancelling party."
          },
          "reasonCode": {
            "$ref": "#/components/schemas/OrderCancelReason",
            "description": "Why the restaurant cancelled the order, as a code. Set when `by` is `kitchen`, beside the\nfree-text `reason`. Absent for a cancellation by you."
          },
          "at": {
            "type": "string",
            "format": "date-time",
            "description": "When the cancellation happened, ISO-8601 UTC."
          }
        }
      },
      "ChannelStore": {
        "type": "object",
        "description": "One store on your channel: a restaurant brand at one kitchen, selling through your platform.",
        "properties": {
          "id": {
            "type": "string",
            "description": "Sous Chef's id for the store. It is `storeId` on the `item.availability.changed` webhook and\n`store.id` on an order."
          },
          "code": {
            "type": "string",
            "description": "The store's code: what every other operation takes as `storeCode`."
          },
          "name": {
            "type": "string",
            "description": "The store's display name."
          },
          "brandName": {
            "type": "string",
            "description": "The brand the store sells."
          },
          "locationName": {
            "type": "string",
            "description": "The kitchen the store cooks at."
          },
          "timezone": {
            "type": "string",
            "description": "The kitchen's time zone, IANA, e.g. `America/New_York`."
          },
          "active": {
            "type": "boolean",
            "description": "Whether the store is live. An order for a store that is not live is answered `200` and then\nrejected with `order.rejected`, unless it is scheduled for after the store resumes."
          }
        }
      },
      "ItemAvailability": {
        "type": "object",
        "description": "One item or modifier option at a location, with its current availability there.",
        "properties": {
          "itemId": {
            "type": "string",
            "description": "Sous Chef's identifier for the item: brand-scoped, stable for that brand's catalogue across\nevery location. The same id as `MenuItem.id` (or `MenuModifierOption.itemId`) on `fetchMenu`.\n\nThe same id space whether or not `isModifier` is set: a modifier option is addressed exactly\nlike any other item."
          },
          "sku": {
            "type": "string",
            "description": "Stock-keeping unit. Not unique. Never match items on it."
          },
          "name": {
            "type": "string",
            "description": "The item's display name."
          },
          "isModifier": {
            "type": "boolean",
            "description": "`true` when this item is configured as a modifier option (e.g. a side or topping added to\nanother item) rather than a standalone menu item. Availability works identically for both."
          },
          "available": {
            "type": "boolean",
            "description": "Current availability."
          }
        }
      },
      "ItemAvailabilityChange": {
        "type": "object",
        "description": "What changed: which items, at which kitchen, for which stores on your channel.",
        "properties": {
          "locationId": {
            "type": "string",
            "description": "The kitchen (location) where availability changed."
          },
          "stores": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ItemAvailabilityStore"
            },
            "description": "The stores on your channel at that kitchen that sell at least one of the items. Availability is\nheld per kitchen, so it applies to every one of them at once."
          },
          "items": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ItemAvailability"
            },
            "description": "The items whose availability changed, each with its new value. `itemId` is the same id as\n`MenuItem.id` on `fetchMenu`. Only items that really changed are announced."
          },
          "changedAt": {
            "type": "string",
            "format": "date-time",
            "description": "When the change was made, ISO-8601 UTC. Order changes for one item by this, never by arrival."
          }
        }
      },
      "ItemAvailabilityStore": {
        "type": "object",
        "description": "One store on your channel at the kitchen where availability changed.",
        "properties": {
          "storeId": {
            "type": "string",
            "description": "Sous Chef's `Store.id`: the store's `id` from `fetchStores`."
          },
          "storeCode": {
            "type": "string",
            "description": "The store's code: the `storeCode` you send `createOrder` and `fetchMenu` with."
          }
        }
      },
      "Menu": {
        "type": "object",
        "description": "The full menu document: categories -> items -> modifier groups -> modifier options.\n\nPrices are the store's kitchen's prices: the item's base price, or the kitchen's price override\nwhere one is set. Dynamic pricing rules (per-platform or date-range price adjustments)\nare not applied to these prices.",
        "properties": {
          "id": {
            "type": "string",
            "description": "Sous Chef's identifier for the menu."
          },
          "name": {
            "type": "string",
            "description": "The menu's name."
          },
          "brandId": {
            "type": "string",
            "description": "Sous Chef's identifier for the brand this menu belongs to."
          },
          "categories": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/MenuCategory"
            },
            "description": "The menu's enabled categories, in configured display order. Categories disabled on this menu\nare omitted. Empty when the menu has none."
          }
        }
      },
      "MenuCategory": {
        "type": "object",
        "description": "One category on the menu.",
        "properties": {
          "id": {
            "type": "string",
            "description": "Sous Chef's identifier for the category."
          },
          "name": {
            "type": "string",
            "description": "The category's display name, e.g. \"Burgers\"."
          },
          "items": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/MenuItem"
            },
            "description": "The category's enabled items, in configured display order. Items disabled in this category\nare omitted. Empty when the category has none."
          }
        }
      },
      "MenuItem": {
        "type": "object",
        "description": "One item on the menu.",
        "properties": {
          "id": {
            "type": "string",
            "description": "Sous Chef's identifier for the item: what `createOrder` takes as `items[].itemId`."
          },
          "sku": {
            "type": "string",
            "description": "The item's SKU, where one has been configured. Absent otherwise."
          },
          "name": {
            "type": "string",
            "description": "The item's display name."
          },
          "description": {
            "type": "string",
            "description": "The item's customer-facing description. Absent when none has been configured."
          },
          "imageUrl": {
            "type": "string",
            "description": "URL of the item's image. Absent when the item has no image."
          },
          "price": {
            "type": "number",
            "description": "Minor units (cents), at the store's kitchen."
          },
          "pickupPrice": {
            "type": "number",
            "description": "Separate pickup price, where configured."
          },
          "available": {
            "type": "boolean",
            "description": "Whether the item can be ordered at the store right now."
          },
          "modifierGroups": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/MenuModifierGroup"
            },
            "description": "Modifier groups attached to this item, in configured display order. Empty when none."
          }
        }
      },
      "MenuModifierGroup": {
        "type": "object",
        "description": "One modifier group attached to an item.",
        "properties": {
          "id": {
            "type": "string",
            "description": "Sous Chef's identifier for this group's attachment to the item: the same modifier group\nattached to two items carries two different ids here."
          },
          "name": {
            "type": "string",
            "description": "The modifier group's display name, e.g. \"Choose a side\"."
          },
          "minSelections": {
            "type": "number",
            "description": "The fewest options a customer must pick from this group. Absent when not configured."
          },
          "maxSelections": {
            "type": "number",
            "description": "The most options a customer may pick from this group. Absent when not configured."
          },
          "options": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/MenuModifierOption"
            },
            "description": "The options in this group, in configured display order. Empty when the group has none."
          }
        }
      },
      "MenuModifierOption": {
        "type": "object",
        "description": "One modifier option, matching the published `Menu.categories[].items[].modifierGroups[].options[]`.",
        "properties": {
          "id": {
            "type": "string",
            "description": "Sous Chef's identifier for this modifier option."
          },
          "itemId": {
            "type": "string",
            "description": "The `Item` this option adds, which is the id an order for it carries\n(`OrderIntakeModifierDto.itemId`). Distinct from `id`, which identifies the option. Absent\nwhen it is not known."
          },
          "name": {
            "type": "string",
            "description": "The option's display name: the name of the item the option adds."
          },
          "price": {
            "type": "number",
            "description": "Upcharge, in cents. Absent means no upcharge."
          },
          "available": {
            "type": "boolean",
            "description": "Whether the option can be ordered at the store right now."
          }
        }
      },
      "Order": {
        "type": "object",
        "description": "A normalized order: one shape whichever delivery platform or channel it arrived from.",
        "properties": {
          "id": {
            "type": "string",
            "description": "Sous Chef's identifier for the order (uuid)."
          },
          "platformOrderId": {
            "type": "string",
            "description": "The id the order has on the platform or channel it came from: the order id a channel partner\nsent when it placed the order. Absent when the platform sends none."
          },
          "status": {
            "$ref": "#/components/schemas/OrderStatus",
            "description": "Current state of the order."
          },
          "deliveryStatus": {
            "$ref": "#/components/schemas/OrderDeliveryStatus",
            "description": "Delivery progress, where the platform transmits it."
          },
          "createdAt": {
            "type": "string",
            "format": "date-time",
            "description": "When the order record was created, ISO-8601 UTC."
          },
          "updatedAt": {
            "type": "string",
            "format": "date-time",
            "description": "When the order record last changed, ISO-8601 UTC."
          },
          "estimatedReadyAt": {
            "type": "string",
            "format": "date-time",
            "description": "When the kitchen expects the order to be ready, ISO-8601 UTC. Set when Sous Chef accepts the\norder, from the kitchen's preparation time. A scheduled order carries its scheduled time.\n\nCarried on the order webhooks. Absent when no estimate exists, and on `fetchOrder`."
          },
          "rejectReason": {
            "type": "string",
            "description": "Why the order was rejected, in words (on `order.rejected` only). For example \"Order at 23:10 is\noutside business hours\"."
          },
          "rejectReasonCode": {
            "$ref": "#/components/schemas/OrderCancelReason",
            "description": "Why the order was rejected, as a code (on `order.rejected` only). It is `storeClosed`, which\ncovers a paused store and an order outside the store's hours."
          },
          "store": {
            "$ref": "#/components/schemas/OrderStore",
            "description": "The storefront the order arrived through: which brand, at which kitchen, on which platform.\n\nOn `fetchOrder`; not on the order webhooks."
          },
          "cancellation": {
            "$ref": "#/components/schemas/OrderCancellation",
            "description": "Who cancelled the order, why and when. On `fetchOrder`, present on every\norder whose `status` is `cancelled` and on no other. The `order.cancelled` webhook carries the\nsame facts as top-level fields of its payload instead."
          },
          "details": {
            "$ref": "#/components/schemas/OrderDetails",
            "description": "What was ordered and what it cost: items with their modifiers, promotions, and the order's\nsubtotal, tax, tip, delivery fee and total in cents.\n\nOn `fetchOrder`; not on the order webhooks."
          }
        }
      },
      "OrderCancelReason": {
        "type": "string",
        "description": "A reason code for a cancelled or rejected order: the item, the store or the kitchen.\n\nYou send one with `cancelOrder` when you cancel an order. Sous Chef sends one on the\n`order.rejected` webhook (`rejectReasonCode`, which is `storeClosed`) and on the\n`order.cancelled` webhook when the restaurant cancelled (`reasonCode`). Anything that is not one\nof the first three is `other`; the free-text reason beside it says more.",
        "enum": [
          "itemOutOfStock",
          "storeClosed",
          "kitchenBusy",
          "other"
        ]
      },
      "OrderCancellation": {
        "type": "object",
        "description": "Who cancelled an order, why and when. See `Order.cancellation`.",
        "properties": {
          "by": {
            "type": "string",
            "description": "Who cancelled: `platform` (on the delivery platform, including a customer or courier\ncancelling there), `kitchen` (the restaurant, in the Kitchen App) or `system` (Sous Chef, for\nexample a scheduled order that was never confirmed). New values may be added. Absent on orders\ncancelled before Sous Chef recorded who cancelled."
          },
          "reason": {
            "type": "string",
            "description": "Why the order was cancelled, as reported by the cancelling party. When the kitchen cancelled,\nthis is the reason it picked, which `reasonCode` also gives as a code."
          },
          "reasonCode": {
            "$ref": "#/components/schemas/OrderCancelReason",
            "description": "Why the restaurant cancelled the order, as a code. Set when `by` is `kitchen`, beside the\nfree-text `reason`. Absent for a cancellation by the platform or by Sous Chef."
          },
          "at": {
            "type": "string",
            "format": "date-time",
            "description": "When the order was cancelled, ISO-8601 UTC."
          }
        }
      },
      "OrderCourier": {
        "type": "object",
        "description": "The courier a platform assigned to the order. Personal data.",
        "properties": {
          "name": {
            "type": "string",
            "description": "The courier's name."
          },
          "phone": {
            "type": "string",
            "description": "The courier's phone number."
          }
        }
      },
      "OrderCustomer": {
        "type": "object",
        "description": "The guest who placed the order. Personal data.",
        "properties": {
          "name": {
            "type": "string",
            "description": "The guest's name."
          },
          "phone": {
            "type": "string",
            "description": "The guest's phone number."
          },
          "email": {
            "type": "string",
            "description": "The guest's email address."
          }
        }
      },
      "OrderDeliveryAddress": {
        "type": "object",
        "description": "Where a `restaurantDelivery` order goes. Personal data.",
        "properties": {
          "label": {
            "type": "string",
            "description": "A single-line display form of the address."
          },
          "street": {
            "type": "string",
            "description": "Street and number."
          },
          "unit": {
            "type": "string",
            "description": "Apartment, suite or floor."
          },
          "city": {
            "type": "string",
            "description": "City."
          },
          "state": {
            "type": "string",
            "description": "State or region."
          },
          "zipCode": {
            "type": "string",
            "description": "Postal code."
          },
          "country": {
            "type": "string",
            "description": "Country as an ISO 3166-1 alpha-2 code, e.g. `US`."
          },
          "lat": {
            "type": "number",
            "description": "Latitude in decimal degrees."
          },
          "lng": {
            "type": "number",
            "description": "Longitude in decimal degrees."
          }
        }
      },
      "OrderDeliveryStatus": {
        "type": "string",
        "description": "Delivery progress of an order. See `Order.deliveryStatus`.",
        "enum": [
          "ASSIGNED",
          "EN_ROUTE_TO_STORE_LOCATION",
          "EN_ROUTE_TO_CUSTOMER",
          "COMPLETED",
          "CANCELED"
        ]
      },
      "OrderDetails": {
        "type": "object",
        "description": "What was ordered and what it cost. See `Order.details`.\n\nEvery amount is an integer in the currency's minor unit (cents). Each field is absent when the\nplatform did not send it, or when what was stored is not a whole number of cents or a readable\ntime, so older orders and orders from a direct channel can carry fewer.\n\nThe guest's identity, the delivery address, the courier and free-text notes are not part of\nthis object.",
        "properties": {
          "externalId": {
            "type": "string",
            "description": "The platform's own order id, in practice the same value as `platformOrderId`."
          },
          "externalReadableOrderNum": {
            "type": "string",
            "description": "The short order number the customer and the courier see."
          },
          "placedAt": {
            "type": "string",
            "format": "date-time",
            "description": "When the customer placed the order, ISO-8601 UTC."
          },
          "estimatedPickupAt": {
            "type": "string",
            "format": "date-time",
            "description": "When the order is due to be picked up, ISO-8601 UTC. A scheduled order carries its scheduled\ntime."
          },
          "isPickup": {
            "type": "boolean",
            "description": "`true` when the customer collects the order; `false` for delivery."
          },
          "isMerchantDelivery": {
            "type": "boolean",
            "description": "`true` when the restaurant delivers the order itself rather than a platform courier."
          },
          "subtotal": {
            "type": "integer",
            "description": "The items' total before tax, tip and fees, in cents."
          },
          "tax": {
            "type": "integer",
            "description": "Tax, in cents."
          },
          "tip": {
            "type": "integer",
            "description": "The tip, in cents."
          },
          "deliveryFee": {
            "type": "integer",
            "description": "The delivery fee, in cents."
          },
          "total": {
            "type": "integer",
            "description": "The order total, in cents, as the platform reported it."
          },
          "items": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/OrderItem"
            },
            "description": "The ordered items, each with its modifiers."
          },
          "promotions": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/OrderPromotion"
            },
            "description": "The promotions applied to the order. Empty or absent when none applied."
          }
        }
      },
      "OrderFulfillment": {
        "type": "string",
        "description": "How the guest receives the order.\n\n`pickup`: the guest collects it. `platformDelivery`: a courier the ordering platform dispatches\ncollects it. `restaurantDelivery`: the restaurant delivers it itself; `deliveryAddress` is then\nrequired.",
        "enum": [
          "pickup",
          "platformDelivery",
          "restaurantDelivery"
        ]
      },
      "OrderIntakeItem": {
        "type": "object",
        "description": "One line of the order.",
        "properties": {
          "itemId": {
            "type": "string",
            "description": "Required. The `MenuItem.id` from `fetchMenu`."
          },
          "name": {
            "type": "string",
            "description": "Required. The item's display name."
          },
          "quantity": {
            "type": "number",
            "description": "Required. How many, at least 1."
          },
          "basePrice": {
            "type": "number",
            "description": "Price of one without modifiers, in the currency's minor unit."
          },
          "unitPrice": {
            "type": "number",
            "description": "Required. Price of one with its modifiers, in the currency's minor unit."
          },
          "totalPrice": {
            "type": "number",
            "description": "`unitPrice` times `quantity`, in the currency's minor unit."
          },
          "note": {
            "type": "string",
            "description": "The guest's note for this item. Personal data."
          },
          "modifiers": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/OrderIntakeModifier"
            },
            "description": "The options chosen on this item."
          }
        }
      },
      "OrderIntakeModifier": {
        "type": "object",
        "description": "One selected modifier option on an item. Options nest: an option can itself carry the options\nchosen under it.",
        "properties": {
          "itemId": {
            "type": "string",
            "description": "Required. The modifier option's `MenuModifierOption.itemId` from `fetchMenu`. When the menu\ndoes not carry `itemId`, send the option's `id`."
          },
          "modifierGroupId": {
            "type": "string",
            "description": "The `MenuModifierGroup.id` this option was chosen from, from `fetchMenu`."
          },
          "modifierGroupName": {
            "type": "string",
            "description": "The modifier group's display name."
          },
          "name": {
            "type": "string",
            "description": "Required. The option's display name."
          },
          "quantity": {
            "type": "number",
            "description": "Required. How many of this option, at least 1."
          },
          "unitPrice": {
            "type": "number",
            "description": "Price of one, in the currency's minor unit (cents for USD)."
          },
          "totalPrice": {
            "type": "number",
            "description": "`unitPrice` times `quantity`, in the currency's minor unit."
          },
          "modifiers": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/OrderIntakeModifier"
            },
            "description": "Options chosen under this option."
          }
        }
      },
      "OrderIntakePromotion": {
        "type": "object",
        "description": "A promotion applied to the order.",
        "properties": {
          "name": {
            "type": "string",
            "description": "The promotion's display name."
          },
          "discount": {
            "type": "number",
            "description": "The discount it gave, in the currency's minor unit."
          },
          "platformPromotionId": {
            "type": "string",
            "description": "The platform's own id for the promotion."
          },
          "externalCampaignId": {
            "type": "string",
            "description": "The campaign the promotion belongs to, in the platform's or an external system."
          },
          "promoCode": {
            "type": "string",
            "description": "The code the guest entered, if any."
          }
        }
      },
      "OrderIntakeStatus": {
        "type": "string",
        "description": "What the call did. It is `queued` today: the call was accepted for processing and takes effect\nshortly. `created` is reserved. An order for a store that is paused or outside its hours comes\nback as an `order.rejected` webhook.",
        "enum": [
          "created",
          "queued"
        ]
      },
      "OrderItem": {
        "type": "object",
        "description": "One line of an order.",
        "properties": {
          "id": {
            "type": "string",
            "description": "Identifier of the item on this order."
          },
          "sku": {
            "type": "string",
            "description": "The item's SKU. Synthesized from its `id` when the platform supplies none."
          },
          "name": {
            "type": "string",
            "description": "Name of the item."
          },
          "quantity": {
            "type": "integer",
            "description": "How many were ordered."
          },
          "price": {
            "$ref": "#/components/schemas/OrderItemPrice",
            "description": "The item's price."
          },
          "modifiers": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/OrderItemModifier"
            },
            "description": "The modifiers chosen on this item."
          }
        }
      },
      "OrderItemModifier": {
        "type": "object",
        "description": "A modifier chosen on an order item: an option such as a size or a topping. Modifiers nest to\nany depth through their own `modifiers`.",
        "properties": {
          "id": {
            "type": "string",
            "description": "Identifier of the modifier option on this order."
          },
          "sku": {
            "type": "string",
            "description": "The option's SKU. Synthesized from its `id` when the platform supplies none."
          },
          "name": {
            "type": "string",
            "description": "Name of the option."
          },
          "quantity": {
            "type": "integer",
            "description": "How many of this option were chosen."
          },
          "price": {
            "$ref": "#/components/schemas/OrderItemPrice",
            "description": "The option's price."
          },
          "modifierGroup": {
            "$ref": "#/components/schemas/OrderItemModifierGroup",
            "description": "The modifier group the option was chosen from."
          },
          "modifiers": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/OrderItemModifier"
            },
            "description": "Modifiers chosen on this option (same shape as this object)."
          }
        }
      },
      "OrderItemModifierGroup": {
        "type": "object",
        "description": "The modifier group an option was chosen from, for example \"Choose your size\".",
        "properties": {
          "id": {
            "type": "string",
            "description": "Identifier of the modifier group."
          },
          "name": {
            "type": "string",
            "description": "Name of the modifier group."
          }
        }
      },
      "OrderItemPrice": {
        "type": "object",
        "description": "A price on an order line. Every amount is an integer in the currency's minor unit (cents).",
        "properties": {
          "total": {
            "type": "integer",
            "description": "The line's total: `unit` multiplied by the quantity."
          },
          "unit": {
            "type": "integer",
            "description": "The price of one, including its modifiers."
          },
          "base": {
            "type": "integer",
            "description": "The price of one, without its modifiers."
          },
          "menu": {
            "type": "integer",
            "description": "The menu price of one when the order was placed."
          }
        }
      },
      "OrderPromotion": {
        "type": "object",
        "description": "A promotion applied to an order, as the platform reported it. Platforms do not report promotions\nthey fund entirely, so these are the merchant-funded and co-funded ones.",
        "properties": {
          "name": {
            "type": "string",
            "description": "The promotion's name, as the platform reported it."
          },
          "discountValue": {
            "type": "integer",
            "description": "How much the promotion took off the order, in cents."
          },
          "discountPercentage": {
            "type": "number",
            "description": "The discount as a percentage, where the platform states one."
          }
        }
      },
      "OrderScheduling": {
        "type": "string",
        "description": "Whether the order is for now or for later.",
        "enum": [
          "asap",
          "scheduled"
        ]
      },
      "OrderStatus": {
        "type": "string",
        "description": "Current state of an order. See `Order.status`.",
        "enum": [
          "new",
          "future",
          "ready",
          "finished",
          "rejected",
          "cancelled"
        ]
      },
      "OrderStore": {
        "type": "object",
        "description": "The storefront an order arrived through. See `Order.store`.",
        "properties": {
          "id": {
            "type": "string",
            "description": "Sous Chef's identifier for the store: the `id` that `fetchStores` reports. Join to your\nstore list on this or on `externalId`, not on the names below."
          },
          "externalId": {
            "type": "string",
            "description": "The store's code: the same value as the store's `code` in `fetchStores` and the `storeCode`\nyou send on `createOrder`."
          },
          "location": {
            "type": "string",
            "description": "The kitchen's display name. Join to the directory via `store.id`, not this string."
          },
          "brand": {
            "type": "string",
            "description": "The brand's display name. Join to the directory via `store.id`, not this string."
          },
          "platform": {
            "type": "string",
            "description": "The ordering platform's slug: on this API, always your channel's own. Treat it as an open\nvalue rather than a fixed list."
          }
        }
      },
      "OrderingApiError": {
        "type": "object",
        "description": "The body of a failure response from an operation on this API: one envelope, whatever the status\ncode.\n\nUnlike a success reply, every field except `txId` is always present: when an operation produces\nan error body it produces all of it, so you can read `path` or `message` without a null check.\n\nTwo responses are produced before a request reaches an operation and do not carry this envelope:\nthe `400` for a body that is not valid JSON, and a `429` from the rate limiter, which may have no\nbody at all.",
        "properties": {
          "statusCode": {
            "type": "number",
            "description": "The HTTP status, repeated in the body so a caller that logs only the body still knows what\nhappened. Always the same number as the status line, never a second, body-only code."
          },
          "timestamp": {
            "type": "string",
            "format": "date-time",
            "description": "When we produced the failure, ISO-8601 UTC."
          },
          "path": {
            "type": "string",
            "description": "The ROUTE that failed, for example `/ordering/orders/createOrder`. No query string."
          },
          "method": {
            "type": "string",
            "description": "The HTTP method of the failed call. Always `POST` on this API."
          },
          "message": {
            "type": "string",
            "description": "A human-readable summary, for a human. Do not branch on it: it is not part of the contract\nand changes without notice. Branch on `statusCode` and on documented fields."
          },
          "txId": {
            "type": "string",
            "description": "The support handle: the identifier for THIS one call, the same value on the `x-mealco-tx-id`\nresponse header and on every log line the call produced. Quote it in a ticket and we can pull\nthe complete record of that single call.\n\nOptional for one reason: a request whose body is not valid JSON is rejected before it reaches\nan operation, so that one `400` answers a bare `{\"message\": \"Bad Request\"}` with no `txId` and\nno header. Every failure that an operation produces carries the full envelope including this\nfield."
          }
        },
        "required": [
          "statusCode",
          "timestamp",
          "path",
          "method",
          "message"
        ]
      }
    },
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "x-api-key",
        "description": "Your Sous Chef Ordering API channel key. Issued per channel; shown once. Treat it as a secret and send it on every request. It is the only credential: send no organization header."
      }
    },
    "headers": {
      "x-mealco-tx-id": {
        "description": "The correlation id for this call, returned on a response from an operation. Quote it when you report a problem so that we can trace the request. You may send your own x-mealco-tx-id on the request and it is used as the id. It is optional in the schema because a request with a malformed JSON body is rejected before an id is assigned.",
        "required": false,
        "schema": {
          "type": "string"
        }
      }
    }
  }
}
