Toast Stock API

openapi: 3.2.0
info:
  title: Stock API
  description: 'The stock API lets you retrieve and update inventory information for a

    restaurant''s menu items and modifiers.'
  contact:
    name: Toast developer support
  version: 1.0.0
servers:
- url: https://toast-api-server/stock
tags:
- name: Stock
paths:
  /v1/inventory:
    get:
      tags:
      - Stock
      summary: Toast Get Menu Item Inventory for a Restaurant
      description: 'Returns inventory information for all menu items that have an

        `OUT_OF_STOCK` or `QUANTITY` status.


        Inventory information is not returned for menu items with an `IN_STOCK`

        status, because they are not considered at risk for going out of stock.


        To restrict the menu items in the response to either `OUT_OF_STOCK` or

        `QUANTITY` stock status, use the `status` query parameter.'
      operationId: getInventory
      parameters:
      - name: Toast-Restaurant-External-ID
        in: header
        description: 'The Toast GUID of the restaurant queried for inventory information.

          '
        required: true
        schema:
          type: string
      - name: status
        in: query
        description: "Limits the items in the response to those items with the specified\nstock status. Values are:\n\n* `OUT_OF_STOCK`- Returns all menu items that have the\n  `OUT_OF_STOCK` stock status.\n\n* `QUANTITY` - Returns all menu items that have the\n  `QUANTITY` stock status.\n"
        schema:
          type: string
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/MenuItemInventory'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                type: object
                items:
                  $ref: '#/components/schemas/ErrorMessage'
      security:
      - oauth2:
        - stock:read
  /v1/inventory/search:
    post:
      tags:
      - Stock
      summary: Toast Get Inventory Information for Specific Menu Items
      description: 'Returns inventory information for a list of menu items.


        The request must include a message body that contains an

        `InventorySearchRequest` object with one or both of these values:


        * A`multiLocationIds` value that contains an array of menu item

        multi-location IDs to search for.


        * A `guids` value that contains an array of menu item GUIDs to search

        for.


        For information on these two identifier types, see Toast

        identifiers.'
      operationId: postInventorySearch
      parameters:
      - name: Toast-Restaurant-External-ID
        in: header
        description: 'The Toast GUID of the restaurant queried for inventory information.

          '
        required: true
        schema:
          type: string
      requestBody:
        description: 'An `InventorySearchRequest` object containing identifiers for the

          menu items to include in the search.

          '
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InventorySearchRequest'
        required: true
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/MenuItemInventory'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                type: object
                items:
                  $ref: '#/components/schemas/ErrorMessage'
      security:
      - oauth2:
        - stock:read
  /v1/inventory/update:
    put:
      tags:
      - Stock
      summary: Toast Update Inventory Information for Specific Menu Items
      description: Updates inventory information for a list of menu items.
      operationId: updateInventory
      parameters:
      - name: Toast-Restaurant-External-ID
        in: header
        description: 'The Toast GUID of the restaurant whose inventory information will be updated.

          '
        required: true
        schema:
          type: string
      requestBody:
        description: "An array of `MenuItemInventory` objects for the menu items to be\nupdated, with the following values:\n\n* An identifier for the menu item to be updated. This may be either the\n  menu item's `multiLocationId` or its `guid`. See <a\n  href=\"https://doc.toasttab.com/doc/devguide/portalToastIdentifiers.html\">Toast\n  identifiers</a> for more information on these two identifier types.\n\n* The `status` for the menu item. Must be one of the following:\n  * `IN_STOCK`\n  * `OUT_OF_STOCK`\n  * `QUANTITY`\n\n* For menu items with a status of `QUANTITY`, you must also provide a\n  `quantity` value that is a double greater than 0 (such as 0.5, 7.0, or\n  10.75). Do not include a `quantity` value for menu items with a\n  `status` of `IN_STOCK` or `OUT_OF_STOCK`.\n"
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/MenuItemInventory'
        required: true
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/MenuItemInventory'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                type: object
                items:
                  $ref: '#/components/schemas/ErrorMessage'
      security:
      - oauth2:
        - stock:write
components:
  schemas:
    InventorySearchRequest:
      type: object
      properties:
        guids:
          type: array
          description: 'An array of menu item GUIDs. The `/inventory/search` endpoint tries to

            find menu items with matching GUIDs.

            '
          items:
            type: string
            format: uuid
        multiLocationIds:
          type: array
          description: 'An array of menu item multi-location IDs. The `/inventory/search` endpoint

            tries to find menu items with matching multi-location IDs.


            See <a

            href="https://doc.toasttab.com/doc/devguide/portalToastIdentifiers.html">Toast

            identifiers</a> for more information on multi-location IDs.

            '
          items:
            type: string
        versionIds:
          type: array
          description: For future use.
          items:
            type: string
            format: uuid
      description: Contains search parameters for retrieving menu item inventory information.
    MenuItemInventory:
      type: object
      properties:
        guid:
          type: string
          description: 'The unique GUID assigned to the menu item by the Toast platform.

            '
          format: uuid
        itemGuidValidity:
          type: string
          description: "Indicates whether a menu item identifier that you included in your request is valid or not.\n\n`INVALID` indicates the stock API did not find a matching menu item for the  identifier you supplied in the search or update request. This means either the menu item does not exist at the location being queried or it has been archived.\n            \n`VALID` indicates that the item in the API response is a valid item at the restaurant location.\n\nFor more information, see <a\nhref=\"https://doc.toasttab.com/doc/devguide/apiUsingTheStockApi.html\">Getting stock information using the stock API</a> and <a\nhref=\"https://doc.toasttab.com/doc/devguide/apiUpdatingInventoryInformation.html\">Updating stock API</a>.          \n"
          readOnly: true
          enum:
          - VALID
          - INVALID
        status:
          type: string
          description: 'The inventory status of the menu item. The `status` value can be:


            * `IN_STOCK` - The menu item is in stock in the restaurant.


            * `QUANTITY` - The menu item is in limited supply. The amount

            of remaining items is indicated by the `quantity` value.


            * `OUT_OF_STOCK` - The menu item is no longer in stock and cannot

            be selected for an order.

            '
          enum:
          - IN_STOCK
          - QUANTITY
          - OUT_OF_STOCK
        quantity:
          type:
          - number
          - 'null'
          description: 'Contains the amount of stock remaining when the menu item

            `status` is `QUANTITY`.


            This value is `null` for menu items

            that have a stock staus of `IN_STOCK` or `OUT_OF_STOCK`.

            '
          format: double
        multiLocationId:
          type: string
          description: 'A consistent identifier that applies to all versions of a menu item

            that is shared across locations.


            See <a

            href="https://doc.toasttab.com/doc/devguide/portalToastIdentifiers.html">Toast

            identifiers</a> for more information.

            '
        versionId:
          type: string
          description: 'For future use.

            '
          format: uuid
      description: Contains the stock status and quantity information for a menu item.
    ErrorMessage:
      type: object
      description: 'An object that contains information about one or more errors that the

        Toast platform encountered when processing your API request. For more

        information, see [API responses and errors in the _Toast Developer

        Guide_](https://doc.toasttab.com/doc/devguide/apiResponsesAndErrors.html).

        '
      properties:
        status:
          type: integer
          format: int32
          description: 'The HTTP status code of the response.

            '
        code:
          type: integer
          format: int32
          description: 'A numeric identifier for the error condition.

            '
        message:
          type: string
          description: 'A description of the error condition.

            '
        messageKey:
          type: string
          description: 'Reserved for future use.

            '
        fieldName:
          type: string
          description: 'Reserved for future use.

            '
        link:
          type: string
          description: 'The URL of a resource that provides more information about the error

            condition.

            '
        requestId:
          type: string
          description: 'The unique identifier of the HTTP request that your client sent to

            the Toast API.

            '
        developerMessage:
          type: string
          description: 'Additional detail about the error condition, if it is available.

            '
        errors:
          type: array
          description: 'A JSON array of `ErrorMessage` objects.

            '
          items:
            $ref: '#/components/schemas/ErrorMessage'
  securitySchemes:
    oauth2:
      type: oauth2
      description: "Access to Toast APIs, specific endpoints, \nand specific API endpoint operations is \ncontrolled by the scopes that are associated \nwith your API account. \n\nA full reference for Toast API scopes and \ntheir capabilities can be found in the\n[_Toast Developer Guide_](https://doc.toasttab.com/doc/devguide/apiScopes.html).\n"
      flows:
        clientCredentials:
          tokenUrl: https://toast-api-server/authentication/v1/authentication/login
          scopes:
            stock:read: 'Allows reading from the stock API.

              '
            stock:write: 'Allows updating stock status for menu items (and modifier option item references) using the stock API.

              '