openapi: 3.2.0
info:
  contact:
    email: x-series.api@lightspeedhq.com
    name: Lightspeed Developer Relations
    url: https://developers.retail.lightspeed.app
  description: Lightspeed Retail (X-Series) API.
  license:
    name: Apache 2.0
    url: http://www.apache.org/licenses/LICENSE-2.0.html
  termsOfService: https://developers.lightspeedhq.com/terms
  title: 2026-07 Consignments API
  version: 2026-07
servers:
- url: https://{domain_prefix}.retail.lightspeed.app/api/2026-07
  variables:
    domain_prefix:
      default: example
      description: Domain prefix of the store to be operated on
security:
- bearerAuth: []
tags:
- description: Stock control operations
  name: Consignments
paths:
  /consignments:
    get:
      description: 'Return a paginated list of consignments.


        🔒 Requires: `consignments:read` scope'
      operationId: GetConsignments
      parameters:
      - description: The consignment type to search for.
        in: query
        name: type
        schema:
          enum:
          - SUPPLIER
          - OUTLET
          - STOCKTAKE
          - RETURN
          format: string
          type: string
      - description: The consignment status to search for.
        in: query
        name: status
        schema:
          enum:
          - OPEN
          - SENT
          - DISPATCHED
          - RECEIVED
          - STOCKTAKE_IN_PROGRESS
          - STOCKTAKE_SCHEDULED
          - STOCKTAKE_IN_PROGRESS_PROCESSED
          - STOCKTAKE_COMPLETE
          - CLOSED
          - CANCELLED
          format: string
          type: string
      - description: Filter response by the ID of the outlet associated with the consignments.
        in: query
        name: outlet_id
        schema:
          format: uuid
          type: string
      - description: The lower limit for the version numbers to be included in the response.
        in: query
        name: after
        schema:
          format: int64
          type: integer
      - description: The upper limit for the version numbers to be included in the response.
        in: query
        name: before
        schema:
          format: int64
          type: integer
      - description: The maximum number of items to be returned in the response.
        in: query
        name: page_size
        schema:
          type: integer
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConsignmentCollection'
          description: OK
      summary: List consignments
      tags:
      - Consignments
    post:
      description: "Creates a new consignment.\n\nThe consignment type can be `SUPPLIER`, `OUTLET`, `STOCKTAKE` or `RETURN`. The workflows for these are:\n\n- `SUPPLIER` workflow: `OPEN` -> `SENT` -> `DISPATCHED` -> `RECEIVED`\n  * Can be `CANCELLED` at any time, except from `RECEIVED`\n  * Cannot create a `DISPATCHED` or `RECEIVED` consignment directly\n  * In the response `reference` refers to `Order number` and `name` refers to `Note`\n- `OUTLET` workflow: `OPEN` -> `SENT` -> `RECEIVED` (can be `CANCELLED` at any time after `OPEN`)\n- `RETURN` workflow: `OPEN` -> `SENT` or `CANCELLED`\n- `STOCKTAKE` workflow: `STOCKTAKE` or `STOCKTAKE_SCHEDULED` -> `STOCKTAKE_IN_PROGRESS` -> `STOCKTAKE_IN_PROGRESS_PROCESSED` -> `STOCKTAKE_COMPLETE` (can be `CANCELLED` or `CLOSED` at any time)\n\n\U0001F512 Requires: One of the following scopes:\n- `consignments:write:stock_order` scope for `SUPPLIER` and `RETURN` consignments\n- `consignments:write:stock_transfer` scope for `OUTLET` consignments\n- `consignments:write:inventory_count` scope for `STOCKTAKE` consignments"
      operationId: CreateConsignment
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ConsignmentRequest'
        required: true
      responses:
        '201':
          content:
            application/json:
              example:
                data:
                  consignment_date: '2017-05-24T01:49:25+00:00'
                  created_at: '2017-05-24T01:49:25+00:00'
                  filters: []
                  id: 0af7b240-ab83-11e7-eddc-402337165363
                  name: API Invenotry Count
                  outlet_id: b1e04bd8-f019-11e3-a0f5-b8ca3a64f8f4
                  show_inactive: true
                  status: STOCKTAKE_SCHEDULED
                  type: STOCKTAKE
                  updated_at: '2017-05-24T01:49:25+00:00'
                  version: 3505324485
              schema:
                $ref: '#/components/schemas/ConsignmentResponse'
          description: ''
      summary: Create a consignment
      tags:
      - Consignments
  /consignments/{consignment_id}:
    delete:
      description: 'Deletes the consignment with the given ID.


        🔒 Requires: One of the following scopes:

        - `consignments:write:stock_order` scope for `SUPPLIER` and `RETURN` consignments

        - `consignments:write:stock_transfer` scope for `OUTLET` consignments

        - `consignments:write:inventory_count` scope for `STOCKTAKE` consignments'
      operationId: DeleteConsignmentByID
      parameters:
      - description: The consignment id
        in: path
        name: consignment_id
        required: true
        schema:
          format: uuid
          type: string
      responses:
        '204':
          description: ''
      summary: Delete a consignment
      tags:
      - Consignments
    get:
      description: 'Returns a single consignment with the requested ID.


        🔒 Requires: `consignments:read` scope'
      operationId: GetConsignmentByID
      parameters:
      - description: The consignment id
        in: path
        name: consignment_id
        required: true
        schema:
          format: uuid
          type: string
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                  consignment_date: '2014-07-13T23:22:00+00:00'
                  created_at: '2014-07-13T23:22:00+00:00'
                  filters: []
                  id: 7dbe52cd-0ae4-11e4-a0f5-b8ca3a64f8f4
                  name: Order - Mon 14 Jul 2014
                  outlet_id: b1e04bd8-f019-11e3-a0f5-b8ca3a64f8f4
                  received_at: '2015-07-30T02:59:51+00:00'
                  show_inactive: true
                  status: RECEIVED
                  supplier_invoice: ''
                  type: SUPPLIER
                  updated_at: '2015-07-30T02:59:51+00:00'
                  version: 827406
              schema:
                $ref: '#/components/schemas/ConsignmentResponse'
          description: ''
      summary: Get a single consignment
      tags:
      - Consignments
    put:
      description: 'Updates the given consignment.


        If the type is SUPPLIER then:


        - Cannot change from `SUPPLIER` to a different consignment type

        - `SUPPLIER` workflow: `OPEN` -> `SENT` -> `DISPATCHED` -> `RECEIVED`

        - Can be `CANCELLED` at any time, except from `RECEIVED`

        - Cannot update a `SUPPLIER` consignment that has the status `RECEIVED` or `CANCELLED`

        - Cannot update status if there are no products in the order

        - At least one product should have non-zero received quantity before updating to `RECEIVED`


        🔒 Requires: One of the following scopes:

        - `consignments:write:stock_order` scope for `SUPPLIER` and `RETURN` consignments

        - `consignments:write:stock_transfer` scope for `OUTLET` consignments

        - `consignments:write:inventory_count` scope for `STOCKTAKE` consignments'
      operationId: UpdateConsignmentByID
      parameters:
      - description: The consignment id
        in: path
        name: consignment_id
        required: true
        schema:
          format: uuid
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ConsignmentRequest'
        required: true
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                  consignment_date: '2014-08-20T03:07:07+00:00'
                  created_at: '2014-08-20T03:07:07+00:00'
                  due_at: '2014-08-21T00:00:00+00:00'
                  filters: []
                  id: b8ca3a65-0183-11e4-fbb5-281711e05741
                  name: Stock Transfer
                  outlet_id: b8ca3a65-0183-11e4-fbb5-2816d2677218
                  received_at: '2014-08-20T03:08:49+00:00'
                  show_inactive: true
                  source_outlet_id: b1e04bd8-f019-11e3-a0f5-b8ca3a64f8f4
                  status: RECEIVED
                  supplier_invoice: ''
                  type: OUTLET
                  updated_at: '2014-08-20T03:08:49+00:00'
                  version: 1228872
              schema:
                $ref: '#/components/schemas/ConsignmentResponse'
          description: ''
      summary: Update a consignment
      tags:
      - Consignments
  /consignments/{consignment_id}/totals:
    get:
      description: 'Returns the count and cost for the given consignment.


        The consignment type can be `SUPPLIER`, `OUTLET` or `RETURN` (not `STOCKTAKE`).


        The status of the consignment will determine which values make sense:


        - If the consignment type is `OUTLET` the sent cost may not be accurate when the status is `OPEN`.

        - If the consignment is `OPEN` or `SENT` the received count and cost should both be zero.

        - For completely received consignments received cost should equal the sent cost and the received count should equal the sent count.

        - For partially received consignments we would expect the received cost value to be less than sent cost value, and the received count to be less than the sent count.


        🔒 Requires: `consignments:read` scope'
      operationId: ListConsignmentTotals
      parameters:
      - description: The consignment id
        in: path
        name: consignment_id
        required: true
        schema:
          format: uuid
          type: string
      responses:
        '200':
          content:
            Example:
              example:
                data:
                - total_received_cost: '50.0000000000'
                  total_received_count: '5.00000'
                  total_sent_cost: '150.0000000000'
                  total_sent_count: '15.00000'
            application/json:
              schema:
                $ref: '#/components/schemas/ConsignmentTotalsResponse'
          description: OK
      summary: Get consignment totals
      tags:
      - Consignments
components:
  schemas:
    Version:
      description: An object containing the highest and lowest version numbers for all items of the returned collection.
      properties:
        max:
          description: Highest version number of the payload, or `null` when the result set is empty.
          format: int64
          type:
          - integer
          - 'null'
        min:
          description: Lowest version number of the payload, or `null` when the result set is empty.
          format: int64
          type:
          - integer
          - 'null'
      required:
      - max
      - min
      type: object
    ConsignmentCollection:
      properties:
        data:
          description: An array of Consignment objects.
          items:
            $ref: '#/components/schemas/Consignment'
          type: array
        version:
          $ref: '#/components/schemas/Version'
      title: Consignment Collection
      type: object
    Consignment:
      properties:
        consignment_date:
          description: 11-28T19:02:15+00:00 (timestamp) - Consignment creation date.
          type:
          - string
          - 'null'
        created_at:
          description: Creation timestamp in UTC.
          type:
          - string
          - 'null'
        deleted_at:
          description: Deletion timestamp in UTC.
          type:
          - string
          - 'null'
        due_at:
          description: 11-30T19:08:541+00:00 (timestamp) - Due date.
          type:
          - string
          - 'null'
        id:
          description: Auto-generated object ID.
          format: uuid
          type: string
        name:
          description: Tue 29 Nov 2016 (string) - Consignment name. For orders, the note field in the UI will be the name value.
          type: string
        outlet_id:
          description: A valid ID of an outlet where stock will be received.
          format: uuid
          type: string
        received_at:
          description: 11-30T19:08:541+00:00 (timestamp) - The date when consignment was received.
          type:
          - string
          - 'null'
        reference:
          description: Order number.+ `total_count_gain` (number)
          type:
          - string
          - 'null'
        source_outlet_id:
          description: A valid ID of an outlet where stock will come from. **Stock transfers only**.
          format: uuid
          type:
          - string
          - 'null'
        status:
          description: '* Supplier Order: One of `OPEN`, `SENT`, `DISPATCHED`, `RECEIVED`, `CANCELLED`

            * Outlet Transfer: One of `OPEN`, `SENT`, `RECEIVED`, `CANCELLED`

            * Return Order: One of `OPEN`, `SENT`, `CANCELLED`

            * Stocktake: One of `STOCKTAKE_SCHEDULED`, `STOCKTAKE_IN_PROGRESS`, `STOCKTAKE_IN_PROGRESS_PROCESSED`, `STOCKTAKE_COMPLETE`, `CLOSED`, `CANCELLED`

            This is not a definitive list and may be extended in future

            '
          enum:
          - OPEN
          - SENT
          - DISPATCHED
          - RECEIVED
          - STOCKTAKE_IN_PROGRESS
          - STOCKTAKE_SCHEDULED
          - STOCKTAKE_IN_PROGRESS_PROCESSED
          - STOCKTAKE_COMPLETE
          - CLOSED
          - CANCELLED
          type: string
        supplier_id:
          description: a valid supplier ID.
          format: uuid
          type:
          - string
          - 'null'
        supplier_invoice:
          description: Supplier invoice number.
          type:
          - string
          - 'null'
        total_cost_gain:
          description: The cost of items over the expected level.
          format: double
          type:
          - number
          - 'null'
        total_cost_loss:
          description: The cost of items below the expected level.
          format: double
          type:
          - number
          - 'null'
        total_count_gain:
          description: The number of items over the expected level.
          format: double
          type:
          - number
          - 'null'
        total_count_loss:
          description: The number of items below the expected level.
          format: double
          type:
          - number
          - 'null'
        type:
          description: One of `SUPPLIER`, `OUTLET`, `STOCKTAKE`, `RETURN`.
          enum:
          - SUPPLIER
          - OUTLET
          - STOCKTAKE
          - RETURN
          type: string
        updated_at:
          description: Last update timestamp in UTC.
          type: string
        version:
          description: Auto-incrementing object version number.
          format: int64
          type: integer
      required:
      - name
      - outlet_id
      - type
      title: Consignment
      type: object
    ConsignmentResponse:
      properties:
        data:
          $ref: '#/components/schemas/Consignment'
      title: Consignment Response
      type: object
    ConsignmentRequest:
      properties:
        data:
          $ref: '#/components/schemas/Consignment'
      required:
      - data
      title: Consignment Request
      type: object
    ConsignmentTotalsResponse:
      properties:
        data:
          items:
            properties:
              total_received_cost:
                type: string
              total_received_count:
                type: string
              total_sent_cost:
                type: string
              total_sent_count:
                type: string
            type: object
          type: array
      type: object
  securitySchemes:
    bearerAuth:
      description: Bearer Token for API authentication.
      scheme: bearer
      type: http
externalDocs:
  description: List of tz database time zones
  url: https://en.wikipedia.org/wiki/List_of_tz_database_time_zones