openapi: 3.0.0
info:
  version: 2.0.0
  title: Inventories Introduction
  description: |
    The Inventory API allows you to manage stock for products at both organization and store levels. Stock can be optionally managed in [multiple locations](#multi-location-inventories) representing different stores or warehouses.

    :::note

    This version of the inventories service is not entirely compatible with the [basic version](/docs/api/pxm/inventory) and so must be enabled by setting the following HTTP header when making requests:

    ```
      EP-Inventories-Multi-Location: true
    ```

    The two systems operate on the same database and may be used interchangeably for stock that does not use multiple locations.

    :::

    Inventory is the quantity of each product that you have in stock. The inventory service allows you and your business to keep track of inventory, including a transactional historic log. 

    Inventory for each product is tracked using the following values:

    - **Total**: The amount of product in stock. (Total = Available + Allocated)
    - **Available**: The amount of product available in stock minus allocated products. (Available = Total - Allocated)
    - **Allocated**: The amount of reserved product in stock.

    :::note

    In Commerce Manager, you can manage the inventory while creating a new product in Product Experience Manager. Go to **Products** > **Inventory** and you can specify the inventory details (**allocate**, **deallocate**, **increment**, and **decrement**). 

    :::

    ### Order flow

    There are three mandatory steps to complete an order in relation to inventory:

    1. Added to a cart
    2. Checked out
    3. Paid
    4. Shipped (optional)

    #### Unpaid order flow

    The following flowchart depicts the process of an unpaid order.

    ![The order is created from the cart during the checkout process.](/assets/order-flow.png)

    #### Payment flow

    The following flowchart depicts the process of paying for an order.

    ![The payment workflow.](/assets/payment-workflow-1.png)

    ### How stock is managed

    Stock is managed as follows:

    1. When a customer attempts to add products to a cart, the inventory service checks if there is enough available stock. If there is not enough stock available, you receive a 400 HTTP response with a warning. The response does not describe what products cannot be added, nor does it return how many products are in stock.
    2. If a customer successfully adds products to a cart, the customer can checkout to create an unpaid order.
    3. A final check on the available stock is performed. 
    4. After creating the unpaid order, the payment for an order can be taken. When a customer attempts to pay for an order, the inventory service reserves the stock before the payment is processed internally. At any time before the point of payment, a customer might lose their order, if the customer is slower than everyone else.

        If the payment fails, the temporary stock allocation is removed, and the stock becomes available again for anyone to buy. 

        If the payment succeeds, that stock is still allocated, and the items belong to the customer, unless for any reason they are reallocated before shipment. For example, if the customer cancels, or you realize the order is fraudulent, then you can reallocate the inventory. 
    5. Finally, when the order is marked as shipped, that stock is fully decremented. This means the allocation number is reduced, and therefore the total, and the products are no longer in the warehouse.

    During split payments, stocks are allocated only if the first transaction for an order is complete. If the transaction fails, the stocks are deallocated. Once the first transaction is complete, the stocks are not allocated for the subsequent transactions as they are already reserved for the order. The stocks are deallocated and return to available when then the order is canceled.

    ### Implications of the inventories API

    - It is possible for more products to be in carts than there are in stock if the `add to cart` request quantity is less than available stocks. For example, when available stocks are 100, a user can add 60 to cart 1 and then 50 to cart 1, or user A can add 80 to cart 1, while user B can add 30 to cart 2.
    - It is possible for more products to be checked out than there are in stock if the `add to cart` request quantity is less than the available stocks.
    - It is not possible for more stock to be paid for than is in stock.
    - It is a race for your customers to pay for an order, and whoever does not pay fast enough, is left disappointed.

    ### Multi-location inventories

    If you wish to manage stock in multiple locations you can [create a number of locations](/docs/api/pxm/inventory_mli/create-location) and then when [creating stock inventory](/docs/api/pxm/inventory_mli/create-stock), specify a different stock position for each location.

    Then, when adding to cart, one can specify the location that will supply the inventory for that product and the system will manage stock in that location, checking stock levels and allocating and decrementing the correct stock position through the life cycle of the order.
servers:
  - url: https://euwest.api.elasticpath.com/v2
    description: EU West cluster
  - url: https://useast.api.elasticpath.com/v2
    description: US East cluster
security:
  - bearerAuth: []
tags:
  - name: Inventory
    description: |
      The Inventory API allows you to manage stock for products at both organization and store levels. Each product keeps a history of inventory transactions, enabling easier stock auditing.

      You can specify an initial stock level when you create a product. The stock is set to `0` by default.

      :::caution 

      You cannot create multiple inventories of the same organization-level product in different stores because no unique stock ID, specific to each store, is currently generated. Hence, when you try to manage inventory of the same product for different stores, you get an invalid product identifier error. 

      :::
  - name: Transactions
    description: Methods to allow you to modify and view a products stock via transactions.
  - name: Imports
    description: |
      You can import stock positions for up to 50,000 products in a single operation via an import. This is useful for synchronosing external systems with Elastic Path.
      The API uses a [**JSONL**](https://jsonlines.org/) file, with one line per product. For each product one specifies the total stock in each location. For example

      ```
      {"data":{"type":"stock","id":"b36ba644-6fdc-49b3-9ebb-410ed34908a8","attributes":{"locations":{"vancouver":{"total":20}}}}}
      {"data":{"type":"stock","id":"2e5a4c7b-6f88-4aad-a3c2-4d8b29bc32a4","attributes":{"locations":{"vancouver":{"total":54},"denver":{"total":1},"boston":{"total":20},"portland":{"total":100}}}}}
      ```

      ### Characteristics of Inventories Import

      The Inventories Import API has the following characteristics:

      - The Inventories Import API reads the entire file and then updates the inventory.

      - Inventories imports are asynchronous and are processed one at a time. You can continue to send import requests, but these are queued. 

      - If a product in an import does not already exist in the inventories database it will be created.
paths:
  /inventories:
    post:
      summary: Create Stock for Product
      description: Sets the inventory quantity for the specified product.
      tags:
        - Inventory
      operationId: CreateStock
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                data:
                  $ref: '#/components/schemas/StockCreate'
              required:
                - data
      responses:
        '201':
          description: Success. Stock was successfully created for product
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/StockResponse'
                required:
                  - data
        '400':
          $ref: '#/components/responses/ValidationError'
        '500':
          $ref: '#/components/responses/InternalServerError'
    get:
      parameters:
        - $ref: '#/components/parameters/PageOffset'
        - $ref: '#/components/parameters/PageLimit'
        - $ref: '#/components/parameters/Filter'
      summary: Get Stock for all Products
      description: Returns all products and their associated stock.
      tags:
        - Inventory
      operationId: ListStock
      responses:
        '200':
          description: Success. All products and their stock values are returned
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                  - links
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/StockResponse'
                  links:
                    $ref: '#/components/schemas/Links'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /inventories/multiple:
    post:
      summary: List Stock
      description: Returns stock for all products matching the supplied unique identifiers.
      tags:
        - Inventory
      operationId: GetStockForProducts
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
                - data
              properties:
                data:
                  type: array
                  items:
                    $ref: '#/components/schemas/MultipleProducts'
            example:
              data:
                - id: ebc7652d-bb7d-4359-9a83-78f2998208d9
                - id: 5334e697-a576-4ac5-8075-ab457dfcaddd
      responses:
        '200':
          description: Success. Multiple products and their stock values are returned.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/StockResponse'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /inventories/{product_uuid}:
    parameters:
      - name: product_uuid
        in: path
        description: The unique identifier of the product.
        required: true
        schema:
          $ref: '#/components/schemas/UUID'
    get:
      summary: Get Stock for Product
      description: Gets the stock for the product matching the specified unique identifier.
      tags:
        - Inventory
      operationId: GetStock
      responses:
        '200':
          description: Success. Returns the stock for the given product UUID
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/StockResponse'
                required:
                  - data
        '404':
          $ref: '#/components/responses/NotFoundError'
        '500':
          $ref: '#/components/responses/InternalServerError'
    put:
      summary: Update Stock for Product
      description: Updates the inventory for the specified product.
      tags:
        - Inventory
      operationId: UpdateStock
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
                - data
              properties:
                data:
                  $ref: '#/components/schemas/StockUpdateRequest'
      responses:
        '200':
          description: Success. The stock item was updated successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/StockResponse'
                required:
                  - data
        '400':
          $ref: '#/components/responses/ValidationError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '500':
          $ref: '#/components/responses/InternalServerError'
    delete:
      summary: Delete Stock for Product
      description: Deletes the inventory for the specified product. The product inventory is null and is no longer managed by Commerce. If you want to keep managing inventory but have none of the product in stock, set the inventory to `0` instead of deleting the inventory.
      tags:
        - Inventory
      operationId: DeleteStock
      responses:
        '204':
          description: Success. Removes the stock information about the product
        '400':
          $ref: '#/components/responses/ValidationError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /inventories/{product_uuid}/transactions:
    parameters:
      - name: product_uuid
        in: path
        description: The unique identifier of the product.
        required: true
        schema:
          $ref: '#/components/schemas/UUID'
    get:
      parameters:
        - $ref: '#/components/parameters/PageOffset'
        - $ref: '#/components/parameters/PageLimit'
        - $ref: '#/components/parameters/Filter'
      summary: Get Stock Transactions for Product
      description: Returns the transactions recorded for the specified product.
      tags:
        - Transactions
      operationId: ListTransactions
      responses:
        '200':
          description: Success. Returns the stock for the given product
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/TransactionResponse'
                  links:
                    $ref: '#/components/schemas/Links'
        '400':
          $ref: '#/components/responses/ValidationError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '500':
          $ref: '#/components/responses/InternalServerError'
    post:
      summary: Create Stock Transaction on Product
      tags:
        - Transactions
      operationId: CreateTransaction
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
                - data
              properties:
                data:
                  $ref: '#/components/schemas/TransactionCreate'
      responses:
        '201':
          description: Success. Stock was successfully created for product
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/TransactionResponse'
        '400':
          $ref: '#/components/responses/ValidationError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '422':
          $ref: '#/components/responses/UnprocessableEntityError'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /inventories/{product_uuid}/transactions/{transaction_uuid}:
    parameters:
      - name: product_uuid
        in: path
        description: The unique identifier of the product.
        required: true
        schema:
          $ref: '#/components/schemas/UUID'
      - name: transaction_uuid
        in: path
        description: The unique identifier of the transaction.
        required: true
        schema:
          $ref: '#/components/schemas/UUID'
    get:
      summary: Get Single Stock Transaction for Product
      description: Returns the specific transaction with transaction_uuid for product_uuid
      tags:
        - Transactions
      operationId: GetTransaction
      responses:
        '200':
          description: Success. Returns the stock transaction for the given product
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/TransactionResponse'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /inventories/locations:
    get:
      parameters:
        - $ref: '#/components/parameters/PageOffset'
        - $ref: '#/components/parameters/PageLimit'
        - $ref: '#/components/parameters/Filter'
        - description: Only supported value is `location`. When specified, the results are sorted in ascending order based on the value of the field. For `location`, this means ascending distance from the supplied geolocation. For more information, see [Sorting](/guides/Getting-Started/sorting). For location sorting, `Ep-Geolocation` header must be provided as well.
          name: sort
          in: query
          schema:
            type: string
            enum:
              - location
        - $ref: '#/components/parameters/EpGeolocation'
      summary: List Locations
      description: Lists all Inventory Locations
      tags:
        - Locations
      operationId: ListLocations
      responses:
        '200':
          description: Success. A list of locations is returned
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Location'
                  links:
                    $ref: '#/components/schemas/Links'
              example:
                data:
                  - id: ebc7652d-bb7d-4359-9a83-78f2998208d9
                    type: inventory_location
                    attributes:
                      name: Milton Keynes Warehouse
                      external_ref: mk-stock-warehouse-walnut-tree
                      slug: milton-keynes-warehouse
                      description: Southern dispatch location for all inventory
                      address:
                        - Troughton Supplies
                        - 38 Pipernel Grove
                        - Walnut Tree
                        - MK7 4UL
                      geolocation:
                        lat: -90
                        lon: 180
        '400':
          $ref: '#/components/responses/ValidationError'
    post:
      summary: Create a Location
      description: Creates an Inventory Location
      tags:
        - Locations
      operationId: CreateLocation
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
                - data
              properties:
                data:
                  $ref: '#/components/schemas/LocationRequest'
      responses:
        '201':
          description: Success. The location was created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/Location'
              example:
                data:
                  id: ebc7652d-bb7d-4359-9a83-78f2998208d9
                  type: inventory_location
                  attributes:
                    name: Milton Keynes Warehouse
                    external_ref: mk-stock-warehouse-walnut-tree
                    slug: milton-keynes-warehouse
                    description: Southern dispatch location for all inventory
                    address:
                      - Troughton Supplies
                      - 38 Pipernel Grove
                      - Walnut Tree
                      - MK7 4UL
                    geolocation:
                      lat: -90
                      lon: 180
        '400':
          $ref: '#/components/responses/ValidationError'
  /inventories/locations/{location_uuid}:
    parameters:
      - name: location_uuid
        in: path
        description: The unique identifier of the location.
        required: true
        schema:
          $ref: '#/components/schemas/UUID'
    get:
      summary: Get a Location
      description: Get an Inventory Location
      tags:
        - Locations
      operationId: GetLocation
      responses:
        '200':
          description: Success. The location is returned
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/Location'
              example:
                data:
                  id: ebc7652d-bb7d-4359-9a83-78f2998208d9
                  type: inventory_location
                  attributes:
                    name: Milton Keynes Warehouse
                    external_ref: mk-stock-warehouse-walnut-tree
                    slug: milton-keynes-warehouse
                    description: Southern dispatch location for all inventory
                    address:
                      - Troughton Supplies
                      - 38 Pipernel Grove
                      - Walnut Tree
                      - MK7 4UL
                    geolocation:
                      lat: -90
                      lon: 180
        '404':
          $ref: '#/components/responses/NotFoundError'
    put:
      summary: Update a Location
      description: Updates an Inventory Location
      tags:
        - Locations
      operationId: UpdateLocation
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
                - data
              properties:
                data:
                  $ref: '#/components/schemas/LocationUpdateRequest'
      responses:
        '200':
          description: Success. The location was updated successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/Location'
              example:
                data:
                  id: ebc7652d-bb7d-4359-9a83-78f2998208d9
                  type: inventory_location
                  attributes:
                    name: Milton Keynes Warehouse
                    external_ref: mk-stock-warehouse-walnut-tree
                    slug: milton-keynes-warehouse
                    description: Southern dispatch location for all inventory
                    address:
                      - Troughton Supplies
                      - 38 Pipernel Grove
                      - Walnut Tree
                      - MK7 4UL
                    geolocation:
                      lat: -90
                      lon: 180
        '400':
          $ref: '#/components/responses/ValidationError'
        '404':
          $ref: '#/components/responses/NotFoundError'
    delete:
      summary: Delete a Location
      description: Delete an Inventory Location
      tags:
        - Locations
      operationId: DeleteLocation
      responses:
        '204':
          description: Success. The location is deleted
  /inventories/imports:
    post:
      tags:
        - Imports
      summary: Import a dataset
      operationId: CreateImport
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              required:
                - import_file
              properties:
                external_ref:
                  $ref: '#/components/schemas/ExternalRef'
                import_file:
                  description: The JSONL file you want to upload.
                  type: string
                  format: binary
      responses:
        '201':
          description: Success. The import was started.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/Import'
        '400':
          $ref: '#/components/responses/ValidationError'
        '500':
          $ref: '#/components/responses/InternalServerError'
    get:
      tags:
        - Imports
      summary: List import jobs
      description: |
        Retrieves a list of all import jobs.
      parameters:
        - $ref: '#/components/parameters/Filter'
        - $ref: '#/components/parameters/PageOffset'
        - $ref: '#/components/parameters/PageLimit'
      operationId: ListImportJobs
      responses:
        '200':
          description: Success. A list of import jobs is returned.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Import'
                  links:
                    $ref: '#/components/schemas/Links'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /inventories/imports/{import_uuid}:
    parameters:
      - name: import_uuid
        in: path
        description: The unique identifier of the import.
        required: true
        schema:
          $ref: '#/components/schemas/UUID'
    get:
      parameters:
        - $ref: '#/components/parameters/PageOffset'
        - $ref: '#/components/parameters/PageLimit'
      tags:
        - Imports
      summary: Get import
      description: Retrieves the import job for the specified ID.
      operationId: GetImport
      responses:
        '200':
          description: Success. The import is returned.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/Import'
        '400':
          $ref: '#/components/responses/ValidationError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /inventories/imports/{import_uuid}/errors:
    parameters:
      - name: import_uuid
        in: path
        description: The unique identifier of the import.
        required: true
        schema:
          $ref: '#/components/schemas/UUID'
    get:
      tags:
        - Imports
      parameters:
        - $ref: '#/components/parameters/PageOffset'
        - $ref: '#/components/parameters/PageLimit'
      summary: Get import errors
      description: |
        Retrieves all errors encountered as part of the import. Each error is attributed to a line in the JSONL file 
        imported, so for example, if at line 1 in your JSONL you had a stock without locations, there would
        be a missing key error for locations.

        Errors are also ordered by line number ascending, and can be paginated.
      operationId: GetImportErrors
      responses:
        '200':
          description: Success. The import errors are returned.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/InventoriesImportError'
                  links:
                    $ref: '#/components/schemas/Links'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '500':
          $ref: '#/components/responses/InternalServerError'
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
  parameters:
    PageOffset:
      name: page[offset]
      description: The current offset by number of records, not pages. Offset is zero-based. The maximum records you can offset is 10,000. If no page size is set, the [**page length**](https://elasticpath.dev/docs/commerce-cloud/global-project-settings/settings-overview#page-length) store setting is used.
      in: query
      required: false
      schema:
        type: integer
        format: int
        minimum: 0
        maximum: 10000
        example: 10
    PageLimit:
      description: The maximum number of records per page for this response. You can set this value up to 100. If no page size is set, the the [**page length**](https://elasticpath.dev/docs/commerce-cloud/global-project-settings/settings-overview#page-length) store setting is used.
      name: page[limit]
      in: query
      required: false
      schema:
        type: integer
        format: int
        minimum: 0
        example: 100
    Filter:
      name: filter
      in: query
      required: false
      schema:
        type: string
        format: string
        description: |
          Some Inventories API endpoints support filtering. For the general syntax, see [**Filtering**](/guides/Getting-Started/filtering), but you must go to a specific endpoint to understand the attributes and operators an endpoint supports.
        example: eq(location,new-york)
    EpGeolocation:
      description: Latitude, Longitude representing current location
      name: Ep-Geolocation
      in: header
      schema:
        type: string
        pattern: ^-?\d+(\.\d+)?,-?\d+(\.\d+)?$
      example: 49.2847027,-123.1109329
  responses:
    ValidationError:
      description: Bad request. The request failed validation.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            missing-name:
              value:
                errors:
                  - title: Validation Error
                    status: '400'
                    detail: Your request was invalid
    UnprocessableEntityError:
      description: The request was understood, but could not be processed by the server
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            missing-name:
              value:
                errors:
                  - title: Cannot complete request
                    status: '422'
                    detail: Your request could not be completed due to insufficient stock levels
    InternalServerError:
      description: Internal server error. There was a system failure in the platform.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            internal-server-error:
              value:
                errors:
                  - title: Internal Server Error
                    status: '500'
    NotFoundError:
      description: Not found. The requested entity does not exist.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            not-found:
              value:
                errors:
                  - title: Not Found
                    status: '404'
                    detail: No location found
  schemas:
    StockType:
      type: string
      enum:
        - stock
      default: stock
      example: stock
    StockTransactionType:
      type: string
      enum:
        - stock-transaction
      default: stock-transaction
      example: stock-transaction
    MultipleProducts:
      type: object
      required:
        - id
      properties:
        type:
          type: string
          enum:
            - stock
          default: stock
          example: stock
        id:
          description: The unique identifier of the product.
          type: string
          format: uuid
          example: 3c78777a-cf09-4b2d-be91-a73acbf9166f
    TransactionResponse:
      type: object
      required:
        - id
        - type
        - attributes
      properties:
        id:
          $ref: '#/components/schemas/UUID'
        type:
          $ref: '#/components/schemas/StockTransactionType'
        attributes:
          $ref: '#/components/schemas/TransactionResponseAttributes'
        meta:
          $ref: '#/components/schemas/Meta'
    TransactionResponseAttributes:
      type: object
      required:
        - action
        - product_id
        - quantity
      properties:
        action:
          description: |
            The type of action performed by this transaction.

            - **increment** - use this when you want to make products available for purchase, for example, when you have received stock from a supplier.

            - **decrement** - Use this when you want to remove stock from product inventory.

            - **allocate** - Use this when you want to allocate stock, normally to a reseller who sells on the stock.

            - **deallocate** - Use this when you want to deallocate any previously allocated stock.
          type: string
          enum:
            - increment
            - decrement
            - allocate
            - deallocate
          example: allocate
          x-go-type: model.TransactionAction
          x-go-type-import:
            name: model
            path: gitlab.elasticpath.com/commerce-cloud/inventories.svc/internal/domain/model
        product_id:
          $ref: '#/components/schemas/UUID'
        quantity:
          description: The amount of stock affected by the stock transaction.
          type: integer
          format: int64
          example: 5
        location:
          description: The slug of the location that the transaction should act on.
          type: string
          minLength: 1
          maxLength: 128
          example: milton-keynes-warehouse
    StockCreate:
      type: object
      required:
        - type
        - attributes
      properties:
        id:
          $ref: '#/components/schemas/UUID'
        type:
          $ref: '#/components/schemas/StockType'
        attributes:
          $ref: '#/components/schemas/StockCreateAttributes'
    StockUpdateRequest:
      type: object
      required:
        - id
        - type
        - attributes
      properties:
        id:
          $ref: '#/components/schemas/UUID'
        type:
          $ref: '#/components/schemas/StockType'
        attributes:
          $ref: '#/components/schemas/StockUpdateAttributes'
    StockUpdateAttributes:
      properties:
        locations:
          $ref: '#/components/schemas/NullableLocations'
    NullableLocation:
      type: object
      required:
        - available
      properties:
        available:
          type: integer
          format: int64
          example: 20
      nullable: true
    NullableLocations:
      type: object
      additionalProperties:
        $ref: '#/components/schemas/NullableLocation'
    StockCreateAttributes:
      type: object
      properties:
        available:
          type: integer
          format: int64
          example: 20
        locations:
          type: object
          additionalProperties:
            type: object
            required:
              - available
            properties:
              available:
                type: integer
                format: int64
                example: 20
          example:
            york_warehouse:
              available: 10
            stevenage_warehouse:
              available: 20
    StockResponse:
      type: object
      required:
        - id
        - type
        - attributes
        - meta
      properties:
        id:
          $ref: '#/components/schemas/UUID'
        type:
          $ref: '#/components/schemas/StockType'
        attributes:
          $ref: '#/components/schemas/StockResponseAttributes'
        meta:
          $ref: '#/components/schemas/StockMeta'
    StockResponseAttributes:
      type: object
      required:
        - available
        - total
        - allocated
      properties:
        available:
          type: integer
          format: int64
          example: 20
        allocated:
          type: integer
          format: int64
          example: 10
        total:
          type: integer
          format: int64
          example: 30
        locations:
          $ref: '#/components/schemas/StockLocations'
    StockLocations:
      type: object
      additionalProperties:
        type: object
        required:
          - available
          - total
          - allocated
        properties:
          available:
            type: integer
            format: int64
            example: 20
          allocated:
            type: integer
            format: int64
            example: 10
          total:
            type: integer
            format: int64
            example: 30
    TransactionCreate:
      required:
        - type
        - attributes
      properties:
        type:
          $ref: '#/components/schemas/StockTransactionType'
        attributes:
          $ref: '#/components/schemas/TransactionCreateAttributes'
    TransactionCreateAttributes:
      required:
        - action
        - quantity
      properties:
        product_id:
          $ref: '#/components/schemas/UUID'
        action:
          description: |
            The type of action being performed by this transaction.

             - **increment** - use this when you want to make products available for purchase, for example, when you have received stock from a supplier.

             - **decrement** - Use this when you want to remove stock from product inventory.

             - **allocate** - Use this when you want to allocate stock, normally to a reseller who sells on the stock.

             - **deallocate** - Use this when you want to deallocate any previously allocated stock.

             - **set** - Use this when you want to set total stock to a specific value.
          type: string
          enum:
            - increment
            - decrement
            - allocate
            - deallocate
            - set
          example: allocate
          x-go-type: model.TransactionAction
          x-go-type-import:
            name: model
            path: gitlab.elasticpath.com/commerce-cloud/inventories.svc/internal/domain/model
        quantity:
          description: The amount of stock affected by the stock transaction.
          type: integer
          format: int64
          example: 5
          minimum: 0
        location:
          description: The slug of the location that the transaction should act on.
          type: string
          minLength: 1
          maxLength: 128
          example: milton-keynes-warehouse
    Location:
      type: object
      required:
        - id
        - type
        - attributes
      properties:
        id:
          $ref: '#/components/schemas/UUID'
        type:
          $ref: '#/components/schemas/InventoryLocationType'
        attributes:
          $ref: '#/components/schemas/LocationAttributes'
        meta:
          $ref: '#/components/schemas/Meta'
    LocationAttributes:
      required:
        - name
        - slug
      properties:
        name:
          type: string
          minLength: 3
          maxLength: 1024
          example: Milton Keynes Warehouse
        external_ref:
          type: string
          minLength: 3
          maxLength: 1024
          example: mk-stock-warehouse-walnut-tree
        slug:
          type: string
          minLength: 1
          maxLength: 128
          example: milton-keynes-warehouse
        description:
          type: string
          minLength: 3
          maxLength: 1024
          example: Southern dispatch location for all inventory
        address:
          type: array
          minItems: 1
          maxItems: 8
          items:
            type: string
            maxLength: 1024
        geolocation:
          $ref: '#/components/schemas/GeolocationDetails'
    LocationUpdateAttributes:
      properties:
        name:
          type: string
          minLength: 3
          maxLength: 1024
          example: Milton Keynes Warehouse
        external_ref:
          type: string
          minLength: 3
          maxLength: 1024
          example: mk-stock-warehouse-walnut-tree
          nullable: true
        slug:
          type: string
          minLength: 1
          maxLength: 128
          example: milton-keynes-warehouse
        description:
          type: string
          minLength: 3
          maxLength: 1024
          example: Southern dispatch location for all inventory
          nullable: true
        address:
          type: array
          minItems: 1
          maxItems: 8
          nullable: true
          items:
            type: string
            maxLength: 1024
            nullable: true
        geolocation:
          $ref: '#/components/schemas/GeolocationDetails'
    GeolocationDetails:
      type: object
      nullable: true
      description: The longitude and latitude of a location.
      required:
        - lat
        - lon
      properties:
        lat:
          type: number
          format: double
          nullable: false
          example: 51.477928
        lon:
          type: number
          format: double
          nullable: false
          example: -0.001545
      example:
        lat: 51.477928
        lon: -0.001545
    LocationRequest:
      type: object
      required:
        - attributes
      properties:
        type:
          $ref: '#/components/schemas/InventoryLocationType'
        attributes:
          $ref: '#/components/schemas/LocationAttributes'
    LocationUpdateRequest:
      type: object
      required:
        - id
        - type
        - attributes
      properties:
        id:
          $ref: '#/components/schemas/UUID'
        type:
          $ref: '#/components/schemas/InventoryLocationType'
        attributes:
          $ref: '#/components/schemas/LocationUpdateAttributes'
    InventoryLocationType:
      type: string
      enum:
        - inventory_location
      example: inventory_location
    UUID:
      type: string
      description: The unique identifier.
      x-go-type: uuid.UUID
      x-go-type-import:
        name: uuid
        path: github.com/google/uuid
      example: 00000000-0000-0000-0000-000000000000
    Timestamps:
      required:
        - created_at
      properties:
        updated_at:
          description: The date and time a resource was updated.
          type: string
          example: '2017-01-10T11:41:19.244842Z'
        created_at:
          description: The date and time a resource was created.
          type: string
          example: '2017-01-10T11:41:19.244842Z'
    StockMeta:
      type: object
      required:
        - stock_id
        - timestamps
      properties:
        stock_id:
          $ref: '#/components/schemas/UUID'
        timestamps:
          $ref: '#/components/schemas/Timestamps'
    Meta:
      type: object
      required:
        - timestamps
      properties:
        timestamps:
          $ref: '#/components/schemas/Timestamps'
    ErrorResponse:
      type: object
      required:
        - errors
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
    Error:
      type: object
      required:
        - status
        - title
      properties:
        status:
          type: string
          description: The HTTP response code of the error.
          example: 500
        title:
          type: string
          description: A brief summary of the error.
          example: Internal server error
        detail:
          type: string
          description: Optional additional detail about the error.
          example: An internal error has occurred.
        meta:
          type: object
          description: Additional supporting meta data for the error.
          example:
            missing_ids:
              - e7d50bd5-1833-43c0-9848-f9d325b08be8
    Links:
      type: object
      additionalProperties:
        $ref: '#/components/schemas/Link'
    Link:
      anyOf:
        - $ref: '#/components/schemas/LinkURI'
        - $ref: '#/components/schemas/LinkObject'
    LinkURI:
      type: string
      format: uri
      example: http://example.com/articles/1/comments
      nullable: true
    LinkObject:
      type: object
      properties:
        href:
          type: string
          format: uri
          example: http://example.com/articles/1/comments
        title:
          type: string
          example: Comments
        describedby:
          type: string
          format: uri
          example: http://example.com/schemas/article-comments
    Import:
      required:
        - id
        - type
        - meta
        - attributes
      properties:
        id:
          $ref: '#/components/schemas/UUID'
        type:
          $ref: '#/components/schemas/InventoriesImportType'
        attributes:
          $ref: '#/components/schemas/ImportAttributes'
        meta:
          $ref: '#/components/schemas/ImportMeta'
    ImportAttributes:
      required:
        - status
      properties:
        external_ref:
          $ref: '#/components/schemas/ExternalRef'
        status:
          type: string
          description: |
            The status of job.
            - **pending** - Commerce has received the request but is currently busy processing other requests.
            - **started** - Commerce has started processing the job.
            - **success** - The job has successfully completed.
            - **failed** - The job has failed.
          enum:
            - pending
            - started
            - success
            - failed
          example: pending
          x-go-type: model.JobStatus
          x-go-type-import:
            name: model
            path: gitlab.elasticpath.com/commerce-cloud/inventories.svc/internal/domain/model
    ImportMeta:
      readOnly: true
      required:
        - timestamps
        - records
      properties:
        timestamps:
          $ref: '#/components/schemas/JobTimestamps'
        records:
          $ref: '#/components/schemas/ImportRecords'
    ImportRecords:
      type: object
      description: You can track the number of records imported to ensure the completeness, accuracy and integrity of the import. Uploaded shows the number of records ready to be imported. However, this does not mean they are valid objects, only that they have the correct type and their JSON format is properly formatted. Imported shows the number of records that have been both validated and successfully added.
      required:
        - uploaded
        - imported
      properties:
        uploaded:
          type: object
          properties:
            stock:
              description: The total number of product transactions uploaded.
              type: integer
              example: 50000
          required:
            - stock
        imported:
          properties:
            stock:
              description: The total number of product transactions uploaded.
              type: integer
              example: 50000
          required:
            - stock
    InventoriesImportType:
      type: string
      example: inventories_import
      enum:
        - inventories_import
    ExternalRef:
      description: A unique attribute that you could use to contain information from another company system, for example. The maximum length is 2048 characters.
      type: string
      example: abc123
      maxLength: 2048
    JobTimestamps:
      allOf:
        - $ref: '#/components/schemas/Timestamps'
        - properties:
            started_at:
              description: The date and time a job is started.
              type: string
              example: '2017-01-10T11:41:19.244842Z'
            finished_at:
              description: The date and time a job finished.
              type: string
              example: '2017-01-10T11:41:19.244842Z'
    InventoriesImportError:
      type: object
      required:
        - id
        - type
        - meta
      properties:
        id:
          $ref: '#/components/schemas/UUID'
        type:
          $ref: '#/components/schemas/InventoriesImportErrorType'
        meta:
          $ref: '#/components/schemas/InventoriesImportErrorMeta'
    InventoriesImportErrorType:
      type: string
      example: inventories_import_error
      enum:
        - inventories_import_error
    InventoriesImportErrorMeta:
      type: object
      required:
        - timestamps
        - error
        - field
        - line_number
      properties:
        timestamps:
          $ref: '#/components/schemas/Timestamps'
        error:
          type: string
          example: product name cannot be empty
        field:
          type: string
          example: name
        line_number:
          type: integer
          description: The line in the imported JSONL file at which the validation error occurred. Starts from 1.
          example: 123
        external_ref:
          $ref: '#/components/schemas/ExternalRef'