Toast Stock API

swagger: '2.0'
info:
  version: 1.0.0
  title: Toast Authentication Stock API
  description: 'The authentication API returns an authentication token that you can present

    when your integration client software uses other Toast APIs. For more

    information about authentication, see [the Toast Developer

    Guide](https://doc.toasttab.com/doc/devguide/authentication.html).

    '
  termsOfService: https://pos.toasttab.com/api-terms-of-use
  contact:
    name: Toast developer support
host: toast-api-server
basePath: /authentication/v1
schemes:
- https
consumes:
- application/json
produces:
- application/json
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'
              examples:
                GetInventory200Example:
                  summary: Default getInventory 200 response
                  x-microcks-default: true
                  value:
                  - guid: 5a401af8-d2e2-4090-8c45-9f87b8b6c4d1
                    itemGuidValidity: VALID
                    status: IN_STOCK
                    quantity: 1.0
                    multiLocationId: 90a86f12
                    versionId: 5a401af8-d2e2-4090-8c45-9f87b8b6c4d1
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                type: object
                items:
                  $ref: '#/components/schemas/ErrorMessage'
              examples:
                GetInventory400Example:
                  summary: Default getInventory 400 response
                  x-microcks-default: true
                  value: {}
      security:
      - oauth2:
        - stock:read
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /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.\n\nThe request must include a message body that contains an\n`InventorySearchRequest` object with one or both of these values:\n\n* A`multiLocationIds` value that contains an array of menu item\n  multi-location IDs to search for.\n\n* A `guids` value that contains an array of menu item GUIDs to search\n  for.\n\nFor information on these two identifier types, see <a\nhref=\"https://doc.toasttab.com/doc/devguide/portalToastIdentifiers.html\">Toast\nidentifiers</a>.\n"
      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'
            examples:
              PostInventorySearchRequestExample:
                summary: Default postInventorySearch request
                x-microcks-default: true
                value:
                  guids:
                  - string
                  multiLocationIds:
                  - string
                  versionIds:
                  - string
        required: true
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/MenuItemInventory'
              examples:
                PostInventorySearch200Example:
                  summary: Default postInventorySearch 200 response
                  x-microcks-default: true
                  value:
                  - guid: 5a401af8-d2e2-4090-8c45-9f87b8b6c4d1
                    itemGuidValidity: VALID
                    status: IN_STOCK
                    quantity: 1.0
                    multiLocationId: 90a86f12
                    versionId: 5a401af8-d2e2-4090-8c45-9f87b8b6c4d1
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                type: object
                items:
                  $ref: '#/components/schemas/ErrorMessage'
              examples:
                PostInventorySearch400Example:
                  summary: Default postInventorySearch 400 response
                  x-microcks-default: true
                  value: {}
      security:
      - oauth2:
        - stock:read
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /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'
            examples:
              UpdateInventoryRequestExample:
                summary: Default updateInventory request
                x-microcks-default: true
                value:
                - guid: 5a401af8-d2e2-4090-8c45-9f87b8b6c4d1
                  itemGuidValidity: VALID
                  status: IN_STOCK
                  quantity: 1.0
                  multiLocationId: 90a86f12
                  versionId: 5a401af8-d2e2-4090-8c45-9f87b8b6c4d1
        required: true
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/MenuItemInventory'
              examples:
                UpdateInventory200Example:
                  summary: Default updateInventory 200 response
                  x-microcks-default: true
                  value:
                  - guid: 5a401af8-d2e2-4090-8c45-9f87b8b6c4d1
                    itemGuidValidity: VALID
                    status: IN_STOCK
                    quantity: 1.0
                    multiLocationId: 90a86f12
                    versionId: 5a401af8-d2e2-4090-8c45-9f87b8b6c4d1
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                type: object
                items:
                  $ref: '#/components/schemas/ErrorMessage'
              examples:
                UpdateInventory400Example:
                  summary: Default updateInventory 400 response
                  x-microcks-default: true
                  value: {}
      security:
      - oauth2:
        - stock:write
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  schemas:
    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.

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

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

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

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

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

            condition.

            '
          example: https://doc.toasttab.com/
        requestId:
          type: string
          description: 'The unique identifier of the HTTP request that your client sent to

            the Toast API.

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

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

            '
          items:
            $ref: '#/components/schemas/ErrorMessage'
    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
          example: 5a401af8-d2e2-4090-8c45-9f87b8b6c4d1
        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
          example: VALID
        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
          example: IN_STOCK
        quantity:
          type: number
          nullable: true
          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
          example: 1.0
        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.

            '
          example: 90a86f12
        versionId:
          type: string
          description: 'For future use.

            '
          format: uuid
          example: 5a401af8-d2e2-4090-8c45-9f87b8b6c4d1
      description: Contains the stock status and quantity information for a menu item.
externalDocs:
  description: Authentication developer guide
  url: https://doc.toasttab.com/doc/devguide/authentication.html