openapi: 3.0.0
info:
  version: 1.0.0
  title: Inventories Introduction
  description: |
    The Inventory API allows you to manage stock for products at both organization and store levels. 

    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 the 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.
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.
paths:
  /inventories:
    get:
      parameters:
        - $ref: '#/components/parameters/PageOffset'
        - $ref: '#/components/parameters/PageLimit'
      summary: Get Stock for all Products
      description: Returns all products and their associated stock.
      tags:
        - Inventory
      operationId: GetStockForAllProducts
      responses:
        '200':
          description: Success. All products and their stock values are returned
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Inventory'
                  meta:
                    $ref: '#/components/schemas/Meta'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /inventories/multiple:
    post:
      summary: Get Stock for Multiple Products
      description: Returns stock for all products matching the supplied unique identifiers.
      tags:
        - Inventory
      operationId: GetStockForMultipleProducts
      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/Inventory'
              example:
                data:
                  - id: ebc7652d-bb7d-4359-9a83-78f2998208d9
                    type: stock
                    total: 100
                    available: 75
                    allocated: 25
                  - id: 5334e697-a576-4ac5-8075-ab457dfcaddd
                    type: stock
                    total: 22
                    available: 18
                    allocated: 4
        '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'
    post:
      summary: Create Stock for Product
      description: Sets the inventory quantity for the specified product. When you take this action, you are choosing to manage the inventory for this product in Commerce.
      tags:
        - Inventory
      operationId: CreateProductStock
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
                - data
              properties:
                data:
                  $ref: '#/components/schemas/InventoryCreate'
      responses:
        '201':
          description: Success. Stock was successfully created for product
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/Inventory'
        '400':
          $ref: '#/components/responses/ValidationError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '500':
          $ref: '#/components/responses/InternalServerError'
    get:
      summary: Get Stock for Product
      description: Gets the stock for the product matching the specified unique identifier.
      tags:
        - Inventory
      operationId: GetProductStock
      responses:
        '200':
          description: Success. Returns the stock for the given product UUID
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/Inventory'
                  meta:
                    $ref: '#/components/schemas/Meta'
        '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'
      summary: Get Stock Transactions for Product
      description: Returns the transactions recorded for the specified product.
      tags:
        - Transactions
      operationId: GetStockTransactions
      responses:
        '200':
          description: Success. Returns the stock for the given product
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/Meta'
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Transaction'
        '500':
          $ref: '#/components/responses/InternalServerError'
    post:
      summary: Create Stock Transaction on Product
      tags:
        - Transactions
      operationId: UpdateProductStock
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
                - data
              properties:
                data:
                  $ref: '#/components/schemas/TransactionCreate'
      responses:
        '200':
          description: Success. Stock was successfully modified for product
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/Transaction'
        '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: GetSingleStockTransaction
      responses:
        '200':
          description: Success. Returns the stock transaction for the given product
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/Transaction'
        '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
  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 stock found
  schemas:
    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
    Inventory:
      required:
        - type
        - id
        - total
        - available
        - allocated
      properties:
        id:
          description: The unique identifier of the product.
          type: string
          example: f976dace-450f-4a5d-8877-d119c5a550a1
        stock_id:
          description: The Stock ID of a product, or empty if the product ID matches the Stock ID
          type: string
          example: ce9049af-bba2-4db2-8118-5df5268184c7
        type:
          description: The type represents the object being returned. Always `stock`.
          type: string
          example: stock
          enum:
            - stock
          default: stock
        total:
          description: The total amount of stock we have.
          type: integer
          format: int64
          example: 100
        available:
          description: The amount of stock available for purchase.
          type: integer
          format: int64
          example: 75
        allocated:
          description: The amount of paid for stock, also known as **reserved**.
          type: integer
          format: int64
          example: 25
        meta:
          $ref: '#/components/schemas/Meta'
    Transaction:
      required:
        - type
      properties:
        id:
          description: The unique identifier for the stock transaction.
          type: string
          example: f976dace-450f-4a5d-8877-d119c5a550a1
        type:
          description: The type represents the object being returned. Always `stock-transaction`.
          type: string
          example: stock-transaction
          enum:
            - stock-transaction
          default: stock-transaction
        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
        product_id:
          description: The product identifier that this stock transaction is for.
          type: string
          example: 86b84d3e-0a86-43d6-a347-78ba4adacca2
        quantity:
          description: The amount of stock affected by the stock transaction.
          type: integer
          format: int64
          example: 5
        timestamps:
          $ref: '#/components/schemas/Timestamps'
    InventoryCreate:
      properties:
        quantity:
          description: The amount of inventory available.
          type: integer
          example: 5
    TransactionCreate:
      required:
        - action
        - type
      properties:
        product_id:
          description: The ID of the product to perform the transaction against
          type: string
          format: uuid
          example: b9ad64bd-fc21-4918-b6ec-768809f4a1e9
        type:
          description: The type of object being returned. Always `stock-transaction`.
          type: string
          enum:
            - stock-transaction
          default: stock-transaction
          example: stock-transaction
        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.
          type: string
          enum:
            - increment
            - decrement
            - allocate
            - deallocate
          example: allocate
        quantity:
          description: The amount of stock affected by the stock transaction.
          type: integer
          format: int64
          example: 5
          minimum: 1
    MultiTransactionCreate:
      allOf:
        - $ref: '#/components/schemas/TransactionCreate'
        - type: object
          required:
            - product_id
          properties:
            product_id:
              description: The ID of the product to perform the transaction against
              type: string
              format: uuid
              example: b9ad64bd-fc21-4918-b6ec-768809f4a1e9
    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:
      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'
    Meta:
      allOf:
        - $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