fabric Inventory API

openapi: 3.2.0
info:
  contact:
    email: support@fabric.inc
    name: fabric Orders Team
  description: fabric **Inventory** API lets organizations use *Inventory* as a standalone service, which functions as the repository of product availability for order fulfillment. Typically, Storefront Websites utilize the Inventory service to retrieve data, while Warehouse Management Systems (WMS) use it to create and update inventory details. fabric's Inventory API includes high-performance endpoints built on highly scalable architecture, and includes a configurable data model to orchestrate the inventory lifecycle events.
  license:
    name: fabric API License
    url: https://fabric.inc/api-license
  termsOfService: https://fabric.inc/terms-of-use
  title: fabric Inventory API
  version: 3.0.0
  x-audience: external-public
servers:
- description: Production
  url: https://api.fabric.inc/v3
security:
- authorization: []
tags:
- description: fabric **Inventory** API lets organizations use *Inventory* as a standalone service, which functions as the repository of product availability for order fulfillment. Typically, Storefront Websites utilize the Inventory service to retrieve data, while Warehouse Management Systems (WMS) use it to create and update inventory details. fabric's Inventory API includes high-performance endpoints built on highly scalable architecture, and includes a configurable data model to orchestrate the inventory lifecycle events.
  name: Inventory
paths:
  /inventories:
    post:
      description: Create inventory based on the combination of location number, channel ID, and item ID or SKU.
      operationId: createInventory
      parameters:
      - $ref: '#/components/parameters/xFabricTenantId'
      - $ref: '#/components/parameters/xFabricChannelId'
      - $ref: '#/components/parameters/xFabricRequestId'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/createInventory'
        required: true
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/inventory'
          description: Created
          headers:
            x-fabric-request-id:
              $ref: '#/components/headers/xFabricRequestIdResponseHeader'
        '400':
          content:
            application/json:
              example:
                errors:
                - message: Invalid request
                  type: CLIENT_ERROR
                message: Bad request
                type: CLIENT_ERROR
              schema:
                $ref: '#/components/schemas/errorResponse'
          description: Bad request
          headers:
            x-fabric-request-id:
              $ref: '#/components/headers/xFabricRequestIdResponseHeader'
        '401':
          content:
            application/json:
              example:
                message: Unauthorized request
                type: CLIENT_ERROR
              schema:
                $ref: '#/components/schemas/errorResponse'
          description: Unauthorized
          headers:
            x-fabric-request-id:
              $ref: '#/components/headers/xFabricRequestIdResponseHeader'
        '404':
          content:
            application/json:
              example:
                message: Following attributes not found:[notFoundAttribute]
                type: CLIENT_ERROR
              schema:
                $ref: '#/components/schemas/errorResponse'
          description: Not found
          headers:
            x-fabric-request-id:
              $ref: '#/components/headers/xFabricRequestIdResponseHeader'
        '409':
          content:
            application/json:
              example:
                message: Inventory with same item ID or SKU, location ID and channel ID already exists
                type: CLIENT_ERROR
              schema:
                $ref: '#/components/schemas/errorResponse'
          description: Conflict
          headers:
            x-fabric-request-id:
              $ref: '#/components/headers/xFabricRequestIdResponseHeader'
        '500':
          content:
            application/json:
              example:
                message: Internal server error
                type: SERVER_ERROR
              schema:
                $ref: '#/components/schemas/errorResponse'
          description: Internal server error
          headers:
            x-fabric-request-id:
              $ref: '#/components/headers/xFabricRequestIdResponseHeader'
      summary: Create Inventory
      tags:
      - Inventory
  /inventories/actions/find:
    post:
      description: Search for inventories of specific items by SKUs, itemIds, location numbers, and other parameters as specified in the request body. This endpoint retrieves the exact available quantity of the searched inventory.
      operationId: findInventories
      parameters:
      - description: Number of records to be skipped before returning all records. Default is `0` when no value is specified.
        example: 0
        in: query
        name: offset
        schema:
          default: 0
          example: 0
          format: int32
          type: integer
      - description: Maximum number of records to be returned on a single page. For example, when offset=20 and limit=10, it returns records 21-30 on a single page. Default is `10` when no value is specified.
        example: 10
        in: query
        name: limit
        schema:
          default: 10
          example: 10
          format: int32
          maximum: 100
          minimum: 1
          type: integer
      - $ref: '#/components/parameters/xFabricTenantId'
      - $ref: '#/components/parameters/xFabricRequestId'
      - $ref: '#/components/parameters/xFabricChannelIdOptional'
      - $ref: '#/components/parameters/xFabricChannelIdsOptional'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/inventoriesRequest'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/findInventoriesResponse'
          description: OK
          headers:
            x-fabric-request-id:
              $ref: '#/components/headers/xFabricRequestIdResponseHeader'
        '400':
          content:
            application/json:
              example:
                errors:
                - message: Invalid request
                  type: CLIENT_ERROR
                message: Bad request
                type: CLIENT_ERROR
              schema:
                $ref: '#/components/schemas/errorResponse'
          description: Bad request
          headers:
            x-fabric-request-id:
              $ref: '#/components/headers/xFabricRequestIdResponseHeader'
        '401':
          content:
            application/json:
              example:
                message: Unauthorized request
                type: CLIENT_ERROR
              schema:
                $ref: '#/components/schemas/errorResponse'
          description: Unauthorized
          headers:
            x-fabric-request-id:
              $ref: '#/components/headers/xFabricRequestIdResponseHeader'
        '500':
          content:
            application/json:
              example:
                message: Internal server error
                type: SERVER_ERROR
              schema:
                $ref: '#/components/schemas/errorResponse'
          description: Internal server error
          headers:
            x-fabric-request-id:
              $ref: '#/components/headers/xFabricRequestIdResponseHeader'
      summary: Find Inventories of Specific Items
      tags:
      - Inventory
  /inventories/actions/find-and-adjust-inventory-counters:
    post:
      description: With this endpoint, you can modify inventory counters (also known as inventory positions) to maintain accurate inventory records. These counters are adjusted when new inventory is received or when an item is shipped. If the inventory does not exist, an error message will be displayed. An inventory can have multiple counters, and all counters will be updated when this endpoint is used.
      operationId: updateExistingInventoryCounter
      parameters:
      - $ref: '#/components/parameters/xFabricTenantId'
      - $ref: '#/components/parameters/xFabricChannelId'
      - $ref: '#/components/parameters/xFabricRequestId'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/adjustCounterRequest'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/inventory'
          description: OK
          headers:
            x-fabric-request-id:
              $ref: '#/components/headers/xFabricRequestIdResponseHeader'
        '400':
          content:
            application/json:
              example:
                errors:
                - message: Invalid request
                  type: CLIENT_ERROR
                message: Bad request
                type: CLIENT_ERROR
              schema:
                $ref: '#/components/schemas/errorResponse'
          description: Bad request
          headers:
            x-fabric-request-id:
              $ref: '#/components/headers/xFabricRequestIdResponseHeader'
        '401':
          content:
            application/json:
              example:
                message: Unauthorized request
                type: CLIENT_ERROR
              schema:
                $ref: '#/components/schemas/errorResponse'
          description: Unauthorized
          headers:
            x-fabric-request-id:
              $ref: '#/components/headers/xFabricRequestIdResponseHeader'
        '404':
          content:
            application/json:
              example:
                message: inventory or counter code not found
                type: CLIENT_ERROR
              schema:
                $ref: '#/components/schemas/errorResponse'
          description: Not found
          headers:
            x-fabric-request-id:
              $ref: '#/components/headers/xFabricRequestIdResponseHeader'
        '500':
          content:
            application/json:
              example:
                message: Internal server error
                type: SERVER_ERROR
              schema:
                $ref: '#/components/schemas/errorResponse'
          description: Internal server error
          headers:
            x-fabric-request-id:
              $ref: '#/components/headers/xFabricRequestIdResponseHeader'
      summary: Adjust Inventory Counters
      tags:
      - Inventory
  /inventories/actions/find-and-update:
    post:
      description: Add a new property to existing inventory. <p> **Note:** This endpoint does not override all the existing properties; rather it updates inventory by adding new properties or by updating the existing inventory properties that are specified in the request body. Inventory is identified based on the combination of location number, channel ID, and item ID or SKU. </p>
      operationId: updateInventory
      parameters:
      - $ref: '#/components/parameters/xFabricTenantId'
      - $ref: '#/components/parameters/xFabricChannelId'
      - $ref: '#/components/parameters/xFabricRequestId'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/updateInventory'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/inventory'
          description: OK
          headers:
            x-fabric-request-id:
              $ref: '#/components/headers/xFabricRequestIdResponseHeader'
        '400':
          content:
            application/json:
              example:
                errors:
                - message: Invalid request
                  type: CLIENT_ERROR
                message: Bad request
                type: CLIENT_ERROR
              schema:
                $ref: '#/components/schemas/errorResponse'
          description: Bad request
          headers:
            x-fabric-request-id:
              $ref: '#/components/headers/xFabricRequestIdResponseHeader'
        '401':
          content:
            application/json:
              example:
                message: Unauthorized request
                type: CLIENT_ERROR
              schema:
                $ref: '#/components/schemas/errorResponse'
          description: Unauthorized
          headers:
            x-fabric-request-id:
              $ref: '#/components/headers/xFabricRequestIdResponseHeader'
        '404':
          content:
            application/json:
              example:
                message: Following attributes not found:[isBopis]
                type: CLIENT_ERROR
              schema:
                $ref: '#/components/schemas/errorResponse'
          description: Not found
          headers:
            x-fabric-request-id:
              $ref: '#/components/headers/xFabricRequestIdResponseHeader'
        '500':
          content:
            application/json:
              example:
                message: Internal server error
                type: SERVER_ERROR
              schema:
                $ref: '#/components/schemas/errorResponse'
          description: Internal server error
          headers:
            x-fabric-request-id:
              $ref: '#/components/headers/xFabricRequestIdResponseHeader'
      summary: Update Inventory by Adding New Property
      tags:
      - Inventory
  /inventories/actions/find-by-geography:
    post:
      description: Search for list of inventories of specific items  in a specific region based on SKUs, postal code, latitude, longitude, and other details of the location as specified in the request body.
      operationId: findInventoriesByGeography
      parameters:
      - $ref: '#/components/parameters/xFabricTenantId'
      - $ref: '#/components/parameters/xFabricRequestId'
      - $ref: '#/components/parameters/xFabricChannelIdOptional'
      - $ref: '#/components/parameters/xFabricChannelIdsOptional'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/findInventoryByGeographyRequest'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/inventoryGeographyResponse'
          description: OK
          headers:
            x-fabric-request-id:
              $ref: '#/components/headers/xFabricRequestIdResponseHeader'
        '400':
          content:
            application/json:
              example:
                errors:
                - message: Invalid request
                  type: CLIENT_ERROR
                message: Bad request
                type: CLIENT_ERROR
              schema:
                $ref: '#/components/schemas/errorResponse'
          description: Bad request
          headers:
            x-fabric-request-id:
              $ref: '#/components/headers/xFabricRequestIdResponseHeader'
        '401':
          content:
            application/json:
              example:
                message: Unauthorized request
                type: CLIENT_ERROR
              schema:
                $ref: '#/components/schemas/errorResponse'
          description: Unauthorized
          headers:
            x-fabric-request-id:
              $ref: '#/components/headers/xFabricRequestIdResponseHeader'
        '500':
          content:
            application/json:
              example:
                message: Internal server error
                type: SERVER_ERROR
              schema:
                $ref: '#/components/schemas/errorResponse'
          description: Internal server error
          headers:
            x-fabric-request-id:
              $ref: '#/components/headers/xFabricRequestIdResponseHeader'
      summary: Find Inventory of Specific Items in a Specific Region
      tags:
      - Inventory
  /inventories/search:
    post:
      description: Search for inventories based on filter criteria.
      operationId: searchInventories
      parameters:
      - in: query
        name: fetchOnlyIds
        required: false
        schema:
          default: false
          type: boolean
      - $ref: '#/components/parameters/xFabricTenantId'
      - $ref: '#/components/parameters/xFabricChannelId'
      - $ref: '#/components/parameters/xFabricRequestId'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/inventorySearchRequest'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/inventorySearchResponses'
          description: OK
          headers:
            x-fabric-request-id:
              $ref: '#/components/headers/xFabricRequestIdResponseHeader'
        '400':
          content:
            application/json:
              example:
                errors:
                - message: Invalid request
                  type: CLIENT_ERROR
                message: Bad request
                type: CLIENT_ERROR
              schema:
                $ref: '#/components/schemas/errorResponse'
          description: Bad request
          headers:
            x-fabric-request-id:
              $ref: '#/components/headers/xFabricRequestIdResponseHeader'
        '401':
          content:
            application/json:
              example:
                message: Unauthorized request
                type: CLIENT_ERROR
              schema:
                $ref: '#/components/schemas/errorResponse'
          description: Unauthorized
          headers:
            x-fabric-request-id:
              $ref: '#/components/headers/xFabricRequestIdResponseHeader'
        '500':
          content:
            application/json:
              example:
                message: Internal server error
                type: SERVER_ERROR
              schema:
                $ref: '#/components/schemas/errorResponse'
          description: Internal server error
          headers:
            x-fabric-request-id:
              $ref: '#/components/headers/xFabricRequestIdResponseHeader'
      summary: Search for Inventories
      tags:
      - Inventory
components:
  schemas:
    updateInventory:
      description: Sample request to update inventory
      properties:
        backorderLimit:
          description: Maximum restock inventory quantity
          example: 50
          format: int32
          type: integer
        backorderShipmentAt:
          description: Time when backorder is shipped
          example: 2022-08-01 20:03:28.483000+00:00
          format: date-time
          type: string
        channelId:
          description: Sales channel ID; identifies business operations location.
          example: channel_xyz
          type: string
        counters:
          additionalProperties:
            description: Inventory counter (also known as inventory position) configured by the merchant
            example:
              allocated: 10
              onHand: 100
              shipped: 20
            type: object
          description: Inventory counter (also known as inventory position) configured by the merchant
          example:
            allocated: 10
            onHand: 100
            shipped: 20
          type: object
        customAttributes:
          additionalProperties:
            description: Placeholder for additional info
            example: '{"isBopis":true}'
            type: string
          description: Placeholder for additional info
          example:
            isBopis: true
          type: object
        hasInfiniteInventory:
          default: false
          description: Infinite inventory flag.**true:** Inventory can be used any number of times and does not have any consumption limit.**false:** Inventory can't be used infinitely, and has a consumption limit.
          example: false
          type: boolean
        isNoStock:
          description: An attribute used to indicate that a SKU is out of stock.
          example: false
          type: boolean
        itemId:
          description: Merchant-defined item ID whose inventory is created or updated. If omitted, fabric Inventory service generates the `itemId`. If you choose to use the `itemId` in your environment, you must include it in all inventory *Write* requests.
          example: 12345
          format: int32
          type: integer
        leadTime:
          description: The time between when an order is placed to replenish inventory and when the order is received at warehouse.
          example: 5 days
          type: string
        locationNumber:
          description: Represents the warehouse or store location where the inventory is stored. The locationNumber is crucial for inventory management. When creating or updating inventory, you need to include the locationNumber to specify which location the inventory belongs to.
          example: 12345
          format: int32
          type: integer
        lowStock:
          description: The lowStock parameter is used to alert low stock at a location when inventory is below a set number.
          example: 10
          format: int32
          type: integer
        preorderLimit:
          description: The maximum preorder limit.
          example: 40
          format: int32
          type: integer
        preorderShipmentAt:
          description: Time when preorder is shipped
          example: 2022-08-01 20:03:28.483000+00:00
          format: date-time
          type: string
        region:
          description: Region where inventory is managed
          example: North America
          type: string
        safetyStock:
          description: Reserved inventory quantity at the location
          example: 10
          format: int32
          type: integer
        sku:
          description: Product SKU (Stock Keeping Unit) identifier. It serves as the primary reference key for the inventory and provides uniqueness to the item.
          example: SKU1
          type: string
        status:
          description: Inventory status IN_STOCK, LOW_STOCK, etc.
          enum:
          - IN_STOCK
          - LOW_STOCK
          - OUT_OF_STOCK
          - BACKORDER_STOCK
          - PREORDER_STOCK
          example: ' IN_STOCK'
          type: string
        type:
          description: Inventory type - a classifier attribute that provides flexibility to define inventory types
          example: primary
          type: string
        vendorId:
          description: ID of the vendor who will replenish the inventory for the retailer
          example: vendor1
          type: string
        virtualCountersStatus:
          $ref: '#/components/schemas/virtualCounters'
      required:
      - counters
      - locationNumber
      - sku
      type: object
    capacity:
      description: Location Capacity Model used by fulfillment specialist to optimize fulfillments across the distribution network and monitor productivity by location
      properties:
        allocationPercentage:
          description: Current percentage of allocations at this location. Calculated by (currentAllocations / maxAllocations)*100
          example: 20
          format: int32
          type: integer
        currentAllocations:
          description: Current allocations at this location.
          example: 5
          format: int32
          readOnly: true
          type: integer
        infiniteAllocation:
          type: boolean
        isCapacityFull:
          description: If location has no allocation capacity limit.
          example: true
          type: boolean
        maxAllocations:
          description: Maximum allocations this location can take at any given time. When currentAllocations=maxAllocations, this location is AtCapacity and can't take any further allocations.
          example: 30
          format: int32
          type: integer
      type: object
    findInventoriesResponse:
      description: Find inventory response
      properties:
        data:
          items:
            $ref: '#/components/schemas/inventory'
          type: array
        pagination:
          $ref: '#/components/schemas/pagination'
      type: object
    inventorySearchResponse:
      description: Inventory search response sample
      properties:
        backorderLimit:
          description: Maximum restock inventory quantity
          example: 50
          format: int32
          type: integer
        backorderShipmentAt:
          description: Time when backorder is shipped
          example: '2022-08-01T20:03:28.483Z'
          format: date-time
          type: string
        channelId:
          description: Sales channel ID; identifies business operations location.
          example: channel_xyz
          type: string
        counters:
          additionalProperties:
            description: Merchant-defined inventory counter (also known as inventory position)
            format: int32
            type: integer
          description: Merchant-defined inventory counter (also known as inventory position)
          example:
            allocated: 10
            onHand: 100
            shipped: 20
          type: object
        createdAt:
          description: Time of inventory creation
          example: '2022-08-01T18:03:28.483Z'
          format: date-time
          type: string
        customAttributes:
          additionalProperties:
            description: Placeholder for additional info
            example: '{"isBopis":true}'
            type: string
          description: Placeholder for additional info
          example:
            isBopis: true
          type: object
        hasInfiniteInventory:
          default: false
          description: Infinite inventory flag.**true:** Inventory can be used any number of times and does not have any consumption limit.**false:** Inventory can't be used infinitely, and has a consumption limit.
          example: false
          type: boolean
        inventoryId:
          description: The fabric system-generated inventory ID. This ID is generated during inventory creation.
          example: 723910d81723
          type: string
        isNoStock:
          description: An attribute used to indicate that a SKU is out of stock.
          example: false
          type: boolean
        itemId:
          description: Merchant-defined item ID whose inventory is created or updated. If omitted, fabric Inventory service generates the `itemId`. If you choose to use the `itemId` in your environment, you must include it in all inventory *Write* requests.
          example: 12345
          format: int32
          type: integer
        leadTime:
          description: The time between when an order is placed to replenish inventory and when the order is received at warehouse.
          example: 5 days
          type: string
        locationNumber:
          description: Represents the warehouse or store location where the inventory is stored. The locationNumber is crucial for inventory management. When creating or updating inventory, you need to include the locationNumber to specify which location the inventory belongs to.
          example: 12345
          format: int32
          type: integer
        lowStock:
          description: The lowStock parameter is used to alert low stock at a location when inventory is below a set number.
          example: 10
          format: int32
          type: integer
        networkCode:
          description: Code of the network to which the inventory belongs
          example: ShipToHome
          type: string
        preorderLimit:
          description: Maximum first-shipping inventory quantity
          example: 40
          format: int32
          type: integer
        preorderShipmentAt:
          description: Time when preorder is shipped
          example: '2022-08-01T20:03:28.483Z'
          format: date-time
          type: string
        region:
          description: Region where inventory is managed
          example: North America
          type: string
        safetyStock:
          description: Reserved inventory quantity at the location
          example: 10
          format: int32
          type: integer
        sku:
          description: Product SKU (Stock Keeping Unit) identifier. It serves as the primary reference key for the inventory and provides uniqueness to the item.
          example: SKU1
          type: string
        status:
          description: Inventory status IN_STOCK, LOW_STOCK, etc.
          enum:
          - IN_STOCK
          - LOW_STOCK
          - OUT_OF_STOCK
          - BACKORDER_STOCK
          - PREORDER_STOCK
          example: ' IN_STOCK'
          type: string
        type:
          description: Inventory type - a classifier attribute that provides flexibility to define inventory types
          example: primary
          type: string
        updatedAt:
          description: Time when inventory was last updated
          example: '2022-08-01T20:03:28.483Z'
          format: date-time
          type: string
        vendorId:
          description: ID of the vendor who will replenish the inventory for the retailer
          example: vendor1
          type: string
        virtualCounters:
          $ref: '#/components/schemas/virtualCounters'
        virtualCountersStatus:
          $ref: '#/components/schemas/virtualCounters'
      type: object
    valueSearchFilter:
      allOf:
      - $ref: '#/components/schemas/inventorySearchFilter'
      - properties:
          value:
            description: A single value to search inventory
            example: SKU
            oneOf:
            - description: Target record's non-numeric identifier
              example: ORDER_CREATE
              type: string
            - description: Target record's numeric identifier
              example: 112233
              format: int64
              type: number
            - description: Target record's numeric identifier
              example: 1122.33
              format: double
              type: number
        type: object
      description: Criteria to find inventories by a single value. Condition between `field` and `value` is anything except IN and NIN when `valueSearchFilter` is used.
      required:
      - condition
      - field
      type: object
    valuesSearchFilter:
      allOf:
      - $ref: '#/components/schemas/inventorySearchFilter'
      - properties:
          values:
            items:
              description: Multiple values using which inventory details are searched
              example: SKU
              oneOf:
              - description: Target record's non-numeric identifier
                example: ORDER_CREATE
                type: string
              - description: Target record's numeric identifier
                example: 112233
                format: int64
                type: number
              - description: Target record's numeric identifier
                example: 1122.33
                format: double
                type: number
            maxItems: 25
            minItems: 1
            type: array
        type: object
      description: Criteria to find inventories by multiple values. Condition between `field` and `values` is either IN or NIN when `valuesSearchFilter` is used.
      required:
      - condition
      - field
      type: object
    geoOrigin:
      description: Geo search origin. Must include (`postalCode`) OR (`city` and `region` and `countryCode`) OR (`latitude` and `longitude`)
      properties:
        city:
          description: City for which location will be searched
          example: San Francisco
          type: string
        countryCode:
          description: ISO 3166-1 alpha-2 based country code
          example: US
          type: string
        distanceUnit:
          default: MILE
          description: Distance unit
          enum:
          - MILE
          - KILOMETER
          - METER
          example: MILE
          type: string
        latitude:
          description: Latitude of the location in degree
          example: 21.2629852
          format: double
          type: number
        longitude:
          description

# --- truncated at 32 KB (55 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/fabric-com/refs/heads/main/openapi/fabric-com-inventory-api-openapi.yml