Medusa Inventory Items API

openapi: 3.2.0
info:
  version: 2.19.0
  title: Medusa Admin Inventory Items API
  license:
    name: MIT
    url: https://github.com/medusajs/medusa/blob/develop/LICENSE
  description: 'An inventory item is a stock-kept product whose inventory is managed.


    These API routes allow admin users to manage inventory items.

    '
servers:
- url: http://localhost:9000
- url: https://api.medusajs.com
tags:
- name: Inventory Items
  description: 'An inventory item is a stock-kept product whose inventory is managed.


    These API routes allow admin users to manage inventory items.

    '
  externalDocs:
    description: Learn more about inventory items.
    url: https://docs.medusajs.com/resources/commerce-modules/inventory/concepts
  x-associatedSchema:
    $ref: '#/components/schemas/AdminInventoryItem'
paths:
  /admin/inventory-items:
    get:
      operationId: GetInventoryItems
      summary: List Inventory Items
      description: Retrieve a list of inventory items. The inventory items can be filtered by fields such as `id`. The inventory items can also be sorted or paginated.
      x-authenticated: true
      parameters:
      - name: fields
        in: query
        description: Comma-separated fields that should be included in the returned data. if a field is prefixed with `+` it will be added to the default fields, using `-` will remove it from the default fields. without prefix it will replace the entire default fields.
        required: false
        schema:
          type: string
          title: fields
          description: Comma-separated fields that should be included in the returned data. if a field is prefixed with `+` it will be added to the default fields, using `-` will remove it from the default fields. without prefix it will replace the entire default fields.
          externalDocs:
            url: '#select-fields-and-relations'
      - name: offset
        in: query
        description: The number of items to skip when retrieving a list.
        required: false
        schema:
          type: number
          title: offset
          description: The number of items to skip when retrieving a list.
          externalDocs:
            url: '#pagination'
      - name: limit
        in: query
        description: Limit the number of items returned in the list.
        required: false
        schema:
          type: number
          title: limit
          description: Limit the number of items returned in the list.
          externalDocs:
            url: '#pagination'
      - name: order
        in: query
        description: The field to sort the data by. By default, the sort order is ascending. To change the order to descending, prefix the field name with `-`.
        required: false
        schema:
          type: string
          title: order
          description: The field to sort the data by. By default, the sort order is ascending. To change the order to descending, prefix the field name with `-`.
      - name: q
        in: query
        description: The inventory item's q.
        required: false
        schema:
          type: string
          title: q
          description: The inventory item's q.
      - name: id
        in: query
        required: false
        schema:
          oneOf:
          - type: string
            title: id
            description: The inventory item's ID.
          - type: array
            description: The inventory item's ID.
            items:
              type: string
              title: id
              description: The id's ID.
      - name: sku
        in: query
        required: false
        schema:
          oneOf:
          - type: string
            title: sku
            description: The inventory item's sku.
          - type: array
            description: The inventory item's sku.
            items:
              type: string
              title: sku
              description: The sku's details.
      - name: origin_country
        in: query
        required: false
        schema:
          oneOf:
          - type: string
            title: origin_country
            description: The inventory item's origin country.
          - type: array
            description: The inventory item's origin country.
            items:
              type: string
              title: origin_country
              description: The origin country's details.
      - name: mid_code
        in: query
        required: false
        schema:
          oneOf:
          - type: string
            title: mid_code
            description: The inventory item's mid code.
          - type: array
            description: The inventory item's mid code.
            items:
              type: string
              title: mid_code
              description: The mid code's details.
      - name: hs_code
        in: query
        required: false
        schema:
          oneOf:
          - type: string
            title: hs_code
            description: The inventory item's hs code.
          - type: array
            description: The inventory item's hs code.
            items:
              type: string
              title: hs_code
              description: The hs code's details.
      - name: material
        in: query
        required: false
        schema:
          oneOf:
          - type: string
            title: material
            description: The inventory item's material.
          - type: array
            description: The inventory item's material.
            items:
              type: string
              title: material
              description: The material's details.
      - name: requires_shipping
        in: query
        description: The inventory item's requires shipping.
        required: false
        schema:
          type: boolean
          title: requires_shipping
          description: The inventory item's requires shipping.
      - name: weight
        in: query
        description: Filter the inventory item's weight.
        required: false
        schema:
          description: Filter the inventory item's weight.
          properties:
            $eq:
              type: string
              description: Filter by an exact match.
            $ne:
              type: string
              description: Filter by values not matching this parameter.
            $in:
              type: array
              description: Filter by values in this array's items.
              items:
                type: string
            $nin:
              type: array
              description: Filter by values not in this array's items.
              items:
                type: string
            $like:
              type: string
              description: Apply a `like` filter. Useful for strings only.
            $ilike:
              type: string
              description: Apply a case-insensitive `like` filter. Useful for strings only.
            $re:
              type: string
              description: Apply a regex filter. Useful for strings only.
            $contains:
              type: array
              description: Filter arrays that contain some of the values of this parameter.
              items:
                type: string
            $gt:
              type: string
              description: Filter by values greater than this parameter. Useful for numbers and dates only.
            $gte:
              type: string
              description: Filter by values greater than or equal to this parameter. Useful for numbers and dates only.
            $lt:
              type: string
              description: Filter by values less than this parameter. Useful for numbers and dates only.
            $lte:
              type: string
              description: Filter by values less than or equal to this parameter. Useful for numbers and dates only.
      - name: length
        in: query
        description: Filter the inventory item's length.
        required: false
        schema:
          description: Filter the inventory item's length.
          properties:
            $eq:
              type: string
              description: Filter by an exact match.
            $ne:
              type: string
              description: Filter by values not matching this parameter.
            $in:
              type: array
              description: Filter by values in this array's items.
              items:
                type: string
            $nin:
              type: array
              description: Filter by values not in this array's items.
              items:
                type: string
            $like:
              type: string
              description: Apply a `like` filter. Useful for strings only.
            $ilike:
              type: string
              description: Apply a case-insensitive `like` filter. Useful for strings only.
            $re:
              type: string
              description: Apply a regex filter. Useful for strings only.
            $contains:
              type: array
              description: Filter arrays that contain some of the values of this parameter.
              items:
                type: string
            $gt:
              type: string
              description: Filter by values greater than this parameter. Useful for numbers and dates only.
            $gte:
              type: string
              description: Filter by values greater than or equal to this parameter. Useful for numbers and dates only.
            $lt:
              type: string
              description: Filter by values less than this parameter. Useful for numbers and dates only.
            $lte:
              type: string
              description: Filter by values less than or equal to this parameter. Useful for numbers and dates only.
      - name: height
        in: query
        description: Filter by the inventory item's height.
        required: false
        schema:
          description: Filter by the inventory item's height.
          properties:
            $eq:
              type: string
              description: Filter by an exact match.
            $ne:
              type: string
              description: Filter by values not matching this parameter.
            $in:
              type: array
              description: Filter by values in this array's items.
              items:
                type: string
            $nin:
              type: array
              description: Filter by values not in this array's items.
              items:
                type: string
            $like:
              type: string
              description: Apply a `like` filter. Useful for strings only.
            $ilike:
              type: string
              description: Apply a case-insensitive `like` filter. Useful for strings only.
            $re:
              type: string
              description: Apply a regex filter. Useful for strings only.
            $contains:
              type: array
              description: Filter arrays that contain some of the values of this parameter.
              items:
                type: string
            $gt:
              type: string
              description: Filter by values greater than this parameter. Useful for numbers and dates only.
            $gte:
              type: string
              description: Filter by values greater than or equal to this parameter. Useful for numbers and dates only.
            $lt:
              type: string
              description: Filter by values less than this parameter. Useful for numbers and dates only.
            $lte:
              type: string
              description: Filter by values less than or equal to this parameter. Useful for numbers and dates only.
      - name: width
        in: query
        description: Filter by the inventory item's width.
        required: false
        schema:
          description: Filter by the inventory item's width.
          properties:
            $eq:
              type: string
              description: Filter by an exact match.
            $ne:
              type: string
              description: Filter by values not matching this parameter.
            $in:
              type: array
              description: Filter by values in this array's items.
              items:
                type: string
            $nin:
              type: array
              description: Filter by values not in this array's items.
              items:
                type: string
            $like:
              type: string
              description: Apply a `like` filter. Useful for strings only.
            $ilike:
              type: string
              description: Apply a case-insensitive `like` filter. Useful for strings only.
            $re:
              type: string
              description: Apply a regex filter. Useful for strings only.
            $contains:
              type: array
              description: Filter arrays that contain some of the values of this parameter.
              items:
                type: string
            $gt:
              type: string
              description: Filter by values greater than this parameter. Useful for numbers and dates only.
            $gte:
              type: string
              description: Filter by values greater than or equal to this parameter. Useful for numbers and dates only.
            $lt:
              type: string
              description: Filter by values less than this parameter. Useful for numbers and dates only.
            $lte:
              type: string
              description: Filter by values less than or equal to this parameter. Useful for numbers and dates only.
      - name: location_levels
        in: query
        description: Filter by the inventory item's associated location IDs.
        required: false
        schema:
          type: object
          description: Filter by the inventory item's associated location IDs.
          properties:
            location_id:
              oneOf:
              - type: string
                title: location_id
                description: The associated location's ID.
              - type: array
                description: The location IDs to retrieve inventory items associated with them.
                items:
                  type: string
                  title: location_id
                  description: A location's ID.
      - name: $and
        in: query
        required: false
        schema:
          type: array
          description: Join query parameters with an AND condition. Each object's content is the same type as the expected query parameters.
          items:
            type: object
          title: $and
      - name: $or
        in: query
        required: false
        schema:
          type: array
          description: Join query parameters with an OR condition. Each object's content is the same type as the expected query parameters.
          items:
            type: object
          title: $or
      - name: with_deleted
        in: query
        description: Whether to include deleted records in the result.
        required: false
        schema:
          type: boolean
          title: with_deleted
          description: Whether to include deleted records in the result.
      security:
      - api_token: []
      - cookie_auth: []
      - jwt_token: []
      x-codeSamples:
      - lang: JavaScript
        label: JS SDK
        source: "import Medusa from \"@medusajs/js-sdk\"\n\nexport const sdk = new Medusa({\n  baseUrl: import.meta.env.VITE_BACKEND_URL || \"/\",\n  debug: import.meta.env.DEV,\n  auth: {\n    type: \"session\",\n  },\n})\n\nsdk.admin.inventoryItem.list()\n.then(({ inventory_items, count, limit, offset }) => {\n  console.log(inventory_items)\n})"
      - lang: Shell
        label: cURL
        source: 'curl ''{backend_url}/admin/inventory-items'' \

          -H ''Authorization: Bearer {jwt_token}'''
      tags:
      - Inventory Items
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                allOf:
                - type: object
                  description: The paginated list of inventory items.
                  required:
                  - limit
                  - offset
                  - count
                  properties:
                    limit:
                      type: number
                      title: limit
                      description: The maximum number of items returned.
                    offset:
                      type: number
                      title: offset
                      description: The number of items skipped before retrieving the returned items.
                    count:
                      type: number
                      title: count
                      description: The total number of items.
                - type: object
                  description: The paginated list of inventory items.
                  required:
                  - inventory_items
                  properties:
                    inventory_items:
                      type: array
                      description: The inventory item's inventory items.
                      items:
                        $ref: '#/components/schemas/AdminInventoryItem'
        '400':
          $ref: '#/components/responses/400_error'
        '401':
          $ref: '#/components/responses/unauthorized'
        '404':
          $ref: '#/components/responses/not_found_error'
        '409':
          $ref: '#/components/responses/invalid_state_error'
        '422':
          $ref: '#/components/responses/invalid_request_error'
        '500':
          $ref: '#/components/responses/500_error'
    post:
      operationId: PostInventoryItems
      summary: Create Inventory Item
      description: Create an inventory item.
      x-authenticated: true
      parameters:
      - name: fields
        in: query
        description: Comma-separated fields that should be included in the returned data. if a field is prefixed with `+` it will be added to the default fields, using `-` will remove it from the default fields. without prefix it will replace the entire default fields.
        required: false
        schema:
          type: string
          title: fields
          description: Comma-separated fields that should be included in the returned data. if a field is prefixed with `+` it will be added to the default fields, using `-` will remove it from the default fields. without prefix it will replace the entire default fields.
          externalDocs:
            url: '#select-fields-and-relations'
      security:
      - api_token: []
      - cookie_auth: []
      - jwt_token: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AdminCreateInventoryItem'
      x-codeSamples:
      - lang: JavaScript
        label: JS SDK
        source: "import Medusa from \"@medusajs/js-sdk\"\n\nexport const sdk = new Medusa({\n  baseUrl: import.meta.env.VITE_BACKEND_URL || \"/\",\n  debug: import.meta.env.DEV,\n  auth: {\n    type: \"session\",\n  },\n})\n\nsdk.admin.inventoryItem.create({\n  sku: \"SHIRT\"\n})\n.then(({ inventory_item }) => {\n  console.log(inventory_item)\n})"
      - lang: Shell
        label: cURL
        source: "curl -X POST '{backend_url}/admin/inventory-items' \\\n-H 'Authorization: Bearer {jwt_token}' \\\n-H 'Content-Type: application/json' \\\n--data-raw '{\n  \"sku\": \"{value}\",\n  \"hs_code\": \"{value}\",\n  \"weight\": 2857134683324416,\n  \"length\": 2322256963305472,\n  \"height\": 8391220613087232,\n  \"width\": 1297863250280448,\n  \"origin_country\": \"{value}\",\n  \"mid_code\": \"{value}\",\n  \"material\": \"{value}\",\n  \"title\": \"{value}\",\n  \"description\": \"{value}\",\n  \"thumbnail\": \"{value}\",\n  \"metadata\": {}\n}'"
      tags:
      - Inventory Items
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdminInventoryItemResponse'
        '400':
          $ref: '#/components/responses/400_error'
        '401':
          $ref: '#/components/responses/unauthorized'
        '404':
          $ref: '#/components/responses/not_found_error'
        '409':
          $ref: '#/components/responses/invalid_state_error'
        '422':
          $ref: '#/components/responses/invalid_request_error'
        '500':
          $ref: '#/components/responses/500_error'
      x-workflow: createInventoryItemsWorkflow
      x-events:
      - name: inventory-item.created
        payload: "```ts\n{\n  id, // The ID of the inventory item\n}\n```"
        description: Emitted when inventory items are created.
        deprecated: false
        since: 2.18.0
      - name: inventory-level.created
        payload: "```ts\n{\n  id, // The ID of the inventory level\n}\n```"
        description: Emitted when inventory levels are created.
        deprecated: false
        since: 2.18.0
  /admin/inventory-items/export:
    post:
      operationId: PostInventoryItemsExport
      summary: Export Inventory Items
      description: 'Start an inventory items export process to retrieve a CSV of exported inventory items.


        You''ll receive in the response the transaction ID of the workflow generating the CSV file. To check the status of the execution, send a GET request to `/admin/workflows-executions/export-inventory-items/:transaction-id`.

        Once the execution finishes successfully, a notification is created for the export. You can retrieve the notifications using the `/admin/notification` API route to retrieve the file''s download URL.

        '
      x-authenticated: true
      parameters:
      - name: id
        in: query
        required: false
        schema:
          oneOf:
          - type: string
            title: id
            description: The ID of the inventory item to export.
          - type: array
            description: The IDs of the inventory items to export.
            items:
              type: string
              title: id
              description: The ID of the inventory item to export.
      - name: q
        in: query
        description: Search query to apply on inventory item searchable fields to filter the results.
        required: false
        schema:
          type: string
          title: q
          description: Search query to apply on inventory item searchable fields to filter the results.
      - name: sku
        in: query
        required: false
        schema:
          oneOf:
          - type: string
            title: sku
            description: Filter by the inventory item's sku.
          - type: array
            description: Filter by the inventory items' sku.
            items:
              type: string
              title: sku
              description: Filter by the inventory item's sku.
      - name: origin_country
        in: query
        required: false
        schema:
          oneOf:
          - type: string
            title: origin_country
            description: Filter by the inventory item's origin country.
          - type: array
            description: Filter by the inventory items' origin country.
            items:
              type: string
              title: origin_country
              description: Filter by the inventory item's origin country.
      - name: mid_code
        in: query
        required: false
        schema:
          oneOf:
          - type: string
            title: mid_code
            description: Filter by the inventory item's mid code.
          - type: array
            description: Filter by the inventory items' mid code.
            items:
              type: string
              title: mid_code
              description: Filter by the inventory item's mid code.
      - name: hs_code
        in: query
        required: false
        schema:
          oneOf:
          - type: string
            title: hs_code
            description: Filter by the inventory item's hs code.
          - type: array
            description: Filter by the inventory items' hs code.
            items:
              type: string
              title: hs_code
              description: Filter by the inventory item's hs code.
      - name: material
        in: query
        required: false
        schema:
          oneOf:
          - type: string
            title: material
            description: Filter by the inventory item's material.
          - type: array
            description: Filter by the inventory items' material.
            items:
              type: string
              title: material
              description: Filter by the inventory item's material.
      - name: requires_shipping
        in: query
        description: Filter by whether the inventory item requires shipping.
        required: false
        schema:
          type: boolean
          title: requires_shipping
          description: Whether the inventory item requires shipping.
      - name: weight
        in: query
        required: false
        schema:
          oneOf:
          - type: number
            title: weight
            description: Filter by the inventory item's weight.
          - type: object
            properties:
              $and:
                type: array
                description: Join query parameters with an AND condition. Each object's content is the same type as the expected query parameters.
                items:
                  type: object
              $or:
                type: array
                description: Join query parameters with an OR condition. Each object's content is the same type as the expected query parameters.
                items:
                  type: object
              $eq:
                oneOf:
                - type: number
                  title: $eq
                  description: Filter by exact value.
                - type: array
                  title: $eq
                  description: Filter by exact value.
                  items:
                    type: number
              $ne:
                type: number
                title: $ne
                description: Filter by not equal to the given value.
              $in:
                type: array
                title: $in
                description: Filter by values included in the given array.
                items:
                  type: number
              $nin:
                type: array
                title: $nin
                description: Filter by values not included in the given array.
                items:
                  type: number
              $not:
                oneOf:
                - type: number
                  title: $not
                  description: Filter by not equal to the given value.
                - type: object
                  title: $not
                  description: Filter by values not matching the conditions in this parameter.
                - type: array
                  title: $not
                  description: Filter by values not matching the conditions in this parameter.
                  items:
                    type: number
              $gt:
                type: number
                title: $gt
                description: Filter by values greater than the given value.
              $gte:
                type: number
                title: $gte
                description: Filter by values greater than or equal to the given value.
              $lt:
                type: number
                title: $lt
                description: Filter by values less than the given value.
              $lte:
                type: number
                title: $lte
                description: Filter by values less than or equal to the given value.
              $like:
                type: number
                title: $like
                description: Apply a `like` filter. Useful for strings only.
              $re:
                type: number
                title: $re
                description: Apply a regex filter. Useful for strings only.
              $ilike:
                type: number
                title: $ilike
                description: Apply a case-insensitive `like` filter. Useful for strings only.
              $fulltext:
                type: number
                title: $fulltext
                description: Filter to apply on full-text properties.
              $overlap:
                type: array
                title: $overlap
                description: Filter to apply on array properties to find overlapping values.
                items:
                  type: number
              $contains:
                type: array
                title: $contains
                description: Filter to apply on array properties to find contained values.
                items:
                  type: number
              $contained:
                type: array
                title: $contained
                description: Filter to apply on array properties to find contained values.
                items:
                  type: number
              $exists:
                type: boolean
                title: $exists
                description: Filter by whether a value exists or not.
            title: weight
            description: Filter by the inventory item's weight.
      - name: length
        in: query
        required: false
        schema:
          oneOf:
          - type: number
            title: length
            description: Filter by the inventory item's length.
          - type: object
            properties:
              $and:
                type: array
                description: Join query parameters with an AND condition. Each object's content is the same type as the expected query parameters.
                items:
                  type: object
              $or:
                type: array
                description: Join query parameters with an OR condition. Each object's content is the same type as the expected query parameters.
                items:
                  type: object
              $eq:
                oneOf:
                - type: number
                  title: $eq
                  description: Filter by exact value.
                - type: array
                  title: $eq
                  description: Filter by exact value.
                  items:
                    type: number
              $ne:
                type: number
                title: $ne
                description: Filter by not equal to the given value.
              $in:
                type: array
                title: $in
                description: Filter by values included in the given array.
                items:
                  type: number
              $nin:
                type: array
                title: $nin
                description: Filter by values not included in the given array.
                items:
                  type: number
              $not:
                oneOf:
                - type: number
                  title: $not
                  description: Filter by not equal to the given value.
                - type: object
                  title: $not
                  description: Filter by values not matching the conditions in this parameter.
                - type: array
                  title: $not
                  description: Filter by values not matching the conditions in this parameter.
                  items:
                    type: number
              $gt:
                type: number
                title: $gt
                description: Filter by values greater than the given value.
              $gte:
                type: number
                title: $gte
                description: Filter by values greater than or equal to the given value.
              $lt:
                type: number
                title: $lt
                description: Filter by values less than the given value.
              $lte:
                type: number
                title: $lte
                description: Filter by values less than or equal to the given value.
              $like:
                type: number
                title: $like
                description: Apply a `like` filter. Useful for strings only.
              $re:
                type: number
                title: $re
                description: Apply a regex filter. Useful for strings only.
              $ilike:
                type: number
                

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