> ## Documentation Index
> Fetch the complete documentation index at: https://docs.omnicommerce.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# List Inventory Groups

> Read active inventory using the same canonical quantities, filters and grouping as the inventory assistant. Requires catalog:read and inventory.read permission. Organization scope comes only from the credential.

### Stock and listing absence

status=in_stock means positive available stock (on hand minus locked), with variants rolled up for product groups. unlistedMarketplaces checks every organization store and the entire saved catalog, including product/variant identities, exact catalog SKUs, and historical listings. Source marketplace/country/storeIds filters do not restrict absence evidence. All supported marketplaces are accepted.

listingPresence reports saved-catalog evidence and unknown missing-SKU families. It does not establish fresh live marketplace absence. Stock quantities from duplicate SKU records must not be added as independent physical inventory.

### Pagination

Groups are one page, maximum 30. totalGroups is the full matching count. Continue with nextOffset and identical filters until hasMore=false.



## OpenAPI

````yaml /openapi.json get /api/v1/inventory
openapi: 3.1.0
info:
  title: OmniCommerce API
  version: 1.0.0
  license:
    name: Proprietary
    url: https://omnicommerce.sg/terms
  description: >-
    OmniCommerce API surface for agents and developer integrations. Includes
    public endpoints (merchant discovery, product search, compare, catalog, ACO
    retrieval) and authenticated endpoints (product management via API key
    Bearer tokens).
servers:
  - url: https://omnicommerce.sg
    description: Production
  - url: http://localhost:3000
    description: Local development
security: []
tags:
  - name: agentic-checkout
    description: Merchant-fulfilled agentic checkout
    x-group: Agentic Checkout
  - name: agents
    description: agents
    x-group: Agents
  - name: analytics
    description: Sales performance across marketplaces
    x-group: Analytics
  - name: aops
    description: Agent operating procedures
    x-group: AOPs
  - name: branding
    description: branding
    x-group: Branding
  - name: campaigns
    description: Campaign briefs, offer windows, and marketplace runs
    x-group: Campaigns
  - name: developer-platform
    description: Authenticated developer platform APIs
    x-group: Developer Platform
  - name: documents
    description: Knowledge base document uploads
    x-group: Knowledge Base
  - name: inventory
    description: Inventory quantities, planning signals, and marketplace listing absence
    x-group: Inventory
  - name: looks
    description: AI-styled product looks
    x-group: Looks
  - name: oauth
    description: OAuth token endpoints
    x-group: OAuth
  - name: orders
    description: Workspace and agentic orders
    x-group: Orders
  - name: organizations
    description: Organization management
    x-group: Organizations
  - name: price-books
    description: Marketplace list-price markup rules
    x-group: Price Books
  - name: products
    description: Product CRUD, bulk import, enrichment, publish, and delist
    x-group: Products
  - name: promotions
    description: Central promotions and marketplace sync
    x-group: Promotions
  - name: public-agent
    description: Public agent discovery and catalog APIs
    x-group: Public Agent
  - name: returns
    description: returns
    x-group: Returns
  - name: reviews
    description: Marketplace product reviews and seller replies
    x-group: Reviews
  - name: settlements
    description: settlements
    x-group: Settlements
  - name: ucp
    description: Universal Commerce Protocol
    x-group: UCP
paths:
  /api/v1/inventory:
    get:
      tags:
        - inventory
      summary: List Inventory Groups
      description: >-
        Read active inventory using the same canonical quantities, filters and
        grouping as the inventory assistant. Requires catalog:read and
        inventory.read permission. Organization scope comes only from the
        credential.


        ### Stock and listing absence


        status=in_stock means positive available stock (on hand minus locked),
        with variants rolled up for product groups. unlistedMarketplaces checks
        every organization store and the entire saved catalog, including
        product/variant identities, exact catalog SKUs, and historical listings.
        Source marketplace/country/storeIds filters do not restrict absence
        evidence. All supported marketplaces are accepted.


        listingPresence reports saved-catalog evidence and unknown missing-SKU
        families. It does not establish fresh live marketplace absence. Stock
        quantities from duplicate SKU records must not be added as independent
        physical inventory.


        ### Pagination


        Groups are one page, maximum 30. totalGroups is the full matching count.
        Continue with nextOffset and identical filters until hasMore=false.
      operationId: get_v1_inventory
      parameters:
        - name: productIds
          in: query
          required: false
          style: form
          explode: true
          schema:
            description: >-
              Optional product IDs to scope the inventory summary. Parent
              product IDs include their variants.
            maxItems: 50
            type: array
            items:
              type: string
              minLength: 1
        - name: query
          in: query
          required: false
          style: form
          explode: true
          schema:
            description: Optional keyword filter for product name or SKU before grouping.
            type: string
            maxLength: 200
        - name: marketplace
          in: query
          required: false
          style: form
          explode: true
          schema:
            description: >-
              Optional marketplace filter (e.g. shopee, lazada, tiktok, shopify,
              zalora, amazon, ebay). When used with storeIds, both must match.
            maxItems: 10
            type: array
            items:
              type: string
              minLength: 1
              maxLength: 80
        - name: country
          in: query
          required: false
          style: form
          explode: true
          schema:
            description: >-
              Optional country filters (ISO code or name, e.g. sg, singapore).
              Country is not unique per store — use storeIds when multiple shops
              share a country.
            maxItems: 20
            type: array
            items:
              type: string
              minLength: 1
              maxLength: 80
        - name: storeIds
          in: query
          required: false
          style: form
          explode: true
          schema:
            description: >-
              Optional connected store IDs to scope results. Prefer this when
              multiple stores exist for the same marketplace/country (e.g. two
              Lazada shops in SG). Matches product marketplace storeId / order
              account_id. Omit for all stores.
            maxItems: 50
            type: array
            items:
              type: string
              minLength: 1
              maxLength: 200
        - name: unlistedMarketplaces
          in: query
          required: false
          style: form
          explode: true
          schema:
            description: >-
              Return only product families with no saved listing identity on ANY
              of these marketplaces, across every organization store. Checks
              product/variant identities and exact catalog SKUs across the
              entire catalog, including disabled and historical listings. This
              absence check is independent of the source
              marketplace/country/store filters. Saved-catalog evidence, not
              fresh live verification; missing-SKU families are reported as
              unknown, not confirmed absent.
            minItems: 1
            maxItems: 8
            type: array
            items:
              type: string
              enum:
                - shopee
                - lazada
                - tiktok
                - shopify
                - whatsapp
                - zalora
                - amazon
                - ebay
        - name: groupBy
          in: query
          required: false
          style: form
          explode: true
          schema:
            description: How to group summary rows. Defaults to product.
            type: string
            enum:
              - product
              - marketplace
              - country
        - name: status
          in: query
          required: false
          style: form
          explode: true
          schema:
            description: >-
              Inventory status subset to summarize. in_stock requires positive
              canonical available stock (on hand minus locked); product groups
              include all variants when their total is positive. Defaults to
              all.
            type: string
            enum:
              - all
              - in_stock
              - low_stock
              - out_of_stock
        - name: offset
          in: query
          required: false
          style: form
          explode: true
          schema:
            description: >-
              Grouped-row offset, default 0. Continue with nextOffset and the
              same filters until hasMore=false to retrieve the complete list.
            type: integer
            minimum: 0
            maximum: 9007199254740991
        - name: limit
          in: query
          required: false
          style: form
          explode: true
          schema:
            description: >-
              Maximum grouped inventory rows per page (default: 20, max: 30).
              Use offset/nextOffset for the complete list.
            type: integer
            minimum: 1
            maximum: 30
      responses:
        '200':
          description: >-
            One inventory page, matching count, continuation and listing
            evidence.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    enum:
                      - true
                  groupBy:
                    type: string
                    enum:
                      - product
                      - marketplace
                      - country
                  status:
                    type: string
                    enum:
                      - all
                      - in_stock
                      - low_stock
                      - out_of_stock
                  stats:
                    type: object
                    properties:
                      totalSKUs:
                        type: integer
                        minimum: 0
                        maximum: 9007199254740991
                      lowStockCount:
                        type: integer
                        minimum: 0
                        maximum: 9007199254740991
                      outOfStockCount:
                        type: integer
                        minimum: 0
                        maximum: 9007199254740991
                      trackableCount:
                        type: integer
                        minimum: 0
                        maximum: 9007199254740991
                      lastUpdatedAt:
                        type:
                          - string
                          - 'null'
                    required:
                      - totalSKUs
                      - lowStockCount
                      - outOfStockCount
                      - trackableCount
                      - lastUpdatedAt
                    additionalProperties: false
                  groups:
                    type: array
                    items:
                      type: object
                      properties:
                        key:
                          type: string
                          minLength: 1
                        label:
                          type: string
                          minLength: 1
                        skuCount:
                          type: integer
                          minimum: 0
                          maximum: 9007199254740991
                        trackableCount:
                          type: integer
                          minimum: 0
                          maximum: 9007199254740991
                        lowStockCount:
                          type: integer
                          minimum: 0
                          maximum: 9007199254740991
                        outOfStockCount:
                          type: integer
                          minimum: 0
                          maximum: 9007199254740991
                        totalQuantity:
                          type: number
                        lastUpdatedAt:
                          type:
                            - string
                            - 'null'
                        productId:
                          type: string
                        sku:
                          type:
                            - string
                            - 'null'
                        marketplaces:
                          type: array
                          items:
                            type: string
                        countries:
                          type: array
                          items:
                            type: string
                        hasVariants:
                          type: boolean
                        forecast:
                          type: object
                          properties:
                            signalCount:
                              type: integer
                              minimum: 0
                              maximum: 9007199254740991
                            salesHistoryUnits:
                              default: 0
                              description: >-
                                Sales-history demand units used by the forecast.
                                This can include out-of-stock demand imputation.
                              type: number
                              minimum: 0
                            salesHistoryPoints:
                              default: 0
                              description: >-
                                Maximum daily history-point count across the
                                included forecast series.
                              type: integer
                              minimum: 0
                              maximum: 9007199254740991
                            historyStartDate:
                              default: null
                              type:
                                - string
                                - 'null'
                            historyEndDate:
                              default: null
                              type:
                                - string
                                - 'null'
                            lastSaleDate:
                              default: null
                              type:
                                - string
                                - 'null'
                            countryScopes:
                              default: []
                              description: >-
                                Canonical country scopes for the included
                                forecast series; global is an aggregate
                                connection scope.
                              type: array
                              items:
                                type: string
                            expectedSalesUnits:
                              type: number
                              minimum: 0
                            suggestedReorderQuantity:
                              type: integer
                              minimum: 0
                              maximum: 9007199254740991
                            highRiskCount:
                              type: integer
                              minimum: 0
                              maximum: 9007199254740991
                            mediumRiskCount:
                              type: integer
                              minimum: 0
                              maximum: 9007199254740991
                            stockoutRisk:
                              type: string
                              enum:
                                - low
                                - medium
                                - high
                                - unknown
                            reorderUrgency:
                              type: string
                              enum:
                                - none
                                - low
                                - medium
                                - high
                                - critical
                            confidenceLabel:
                              type:
                                - string
                                - 'null'
                              enum:
                                - low
                                - medium
                                - high
                            forecastWindowDays:
                              type:
                                - integer
                                - 'null'
                              minimum: 1
                              maximum: 9007199254740991
                            forecastStartDate:
                              type:
                                - string
                                - 'null'
                            forecastEndDate:
                              type:
                                - string
                                - 'null'
                            stockoutDate:
                              type:
                                - string
                                - 'null'
                            reorderByDate:
                              type:
                                - string
                                - 'null'
                            generatedAt:
                              type:
                                - string
                                - 'null'
                          required:
                            - signalCount
                            - salesHistoryUnits
                            - salesHistoryPoints
                            - historyStartDate
                            - historyEndDate
                            - lastSaleDate
                            - countryScopes
                            - expectedSalesUnits
                            - suggestedReorderQuantity
                            - highRiskCount
                            - mediumRiskCount
                            - stockoutRisk
                            - reorderUrgency
                            - confidenceLabel
                            - forecastWindowDays
                            - forecastStartDate
                            - forecastEndDate
                            - stockoutDate
                            - reorderByDate
                            - generatedAt
                          additionalProperties: false
                      required:
                        - key
                        - label
                        - skuCount
                        - trackableCount
                        - lowStockCount
                        - outOfStockCount
                        - totalQuantity
                        - lastUpdatedAt
                      additionalProperties: false
                  forecast:
                    type: object
                    properties:
                      signalCount:
                        type: integer
                        minimum: 0
                        maximum: 9007199254740991
                      salesHistoryUnits:
                        default: 0
                        description: >-
                          Sales-history demand units used by the forecast. This
                          can include out-of-stock demand imputation.
                        type: number
                        minimum: 0
                      salesHistoryPoints:
                        default: 0
                        description: >-
                          Maximum daily history-point count across the included
                          forecast series.
                        type: integer
                        minimum: 0
                        maximum: 9007199254740991
                      historyStartDate:
                        default: null
                        type:
                          - string
                          - 'null'
                      historyEndDate:
                        default: null
                        type:
                          - string
                          - 'null'
                      lastSaleDate:
                        default: null
                        type:
                          - string
                          - 'null'
                      countryScopes:
                        default: []
                        description: >-
                          Canonical country scopes for the included forecast
                          series; global is an aggregate connection scope.
                        type: array
                        items:
                          type: string
                      expectedSalesUnits:
                        type: number
                        minimum: 0
                      suggestedReorderQuantity:
                        type: integer
                        minimum: 0
                        maximum: 9007199254740991
                      highRiskCount:
                        type: integer
                        minimum: 0
                        maximum: 9007199254740991
                      mediumRiskCount:
                        type: integer
                        minimum: 0
                        maximum: 9007199254740991
                      stockoutRisk:
                        type: string
                        enum:
                          - low
                          - medium
                          - high
                          - unknown
                      reorderUrgency:
                        type: string
                        enum:
                          - none
                          - low
                          - medium
                          - high
                          - critical
                      confidenceLabel:
                        type:
                          - string
                          - 'null'
                        enum:
                          - low
                          - medium
                          - high
                      forecastWindowDays:
                        type:
                          - integer
                          - 'null'
                        minimum: 1
                        maximum: 9007199254740991
                      forecastStartDate:
                        type:
                          - string
                          - 'null'
                      forecastEndDate:
                        type:
                          - string
                          - 'null'
                      stockoutDate:
                        type:
                          - string
                          - 'null'
                      reorderByDate:
                        type:
                          - string
                          - 'null'
                      generatedAt:
                        type:
                          - string
                          - 'null'
                    required:
                      - signalCount
                      - salesHistoryUnits
                      - salesHistoryPoints
                      - historyStartDate
                      - historyEndDate
                      - lastSaleDate
                      - countryScopes
                      - expectedSalesUnits
                      - suggestedReorderQuantity
                      - highRiskCount
                      - mediumRiskCount
                      - stockoutRisk
                      - reorderUrgency
                      - confidenceLabel
                      - forecastWindowDays
                      - forecastStartDate
                      - forecastEndDate
                      - stockoutDate
                      - reorderByDate
                      - generatedAt
                    additionalProperties: false
                  count:
                    type: integer
                    minimum: 0
                    maximum: 9007199254740991
                  totalGroups:
                    type: integer
                    minimum: 0
                    maximum: 9007199254740991
                  returnedGroups:
                    type: integer
                    minimum: 0
                    maximum: 9007199254740991
                  truncated:
                    type: boolean
                  offset:
                    type: integer
                    minimum: 0
                    maximum: 9007199254740991
                  hasMore:
                    type: boolean
                  nextOffset:
                    type:
                      - integer
                      - 'null'
                    minimum: 0
                    maximum: 9007199254740991
                  listingPresence:
                    type: object
                    properties:
                      source:
                        type: string
                        enum:
                          - saved_catalog
                      marketplaces:
                        type: array
                        items:
                          type: string
                          enum:
                            - shopee
                            - lazada
                            - tiktok
                            - shopify
                            - whatsapp
                            - zalora
                            - amazon
                            - ebay
                      unknownProductCount:
                        type: integer
                        minimum: 0
                        maximum: 9007199254740991
                      complete:
                        type: boolean
                    required:
                      - source
                      - marketplaces
                      - unknownProductCount
                      - complete
                    additionalProperties: false
                required:
                  - success
                  - groupBy
                  - status
                  - stats
                  - groups
                  - count
                  - totalGroups
                  - returnedGroups
                  - truncated
                  - offset
                  - hasMore
                  - nextOffset
                additionalProperties: false
        '400':
          description: Invalid inventory filters.
        '401':
          description: Missing or invalid credentials.
        '403':
          description: Missing catalog:read, inventory permission or organization access.
        '429':
          description: Rate limited.
        '500':
          description: Inventory query failed. An error is not an empty inventory list.
      security:
        - bearerAuth: []
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key
      description: >-
        Bearer API key for server-to-server access. Session auth is also
        supported in first-party UI flows.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.