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

# List products with stock

> Returns the catalog of one store with the current stock of every product. Each product
carries an aggregate `stock` breakdown (available, reserved, damaged, lost, expired, on hold,
sell-ahead buckets, and per-source splits of damaged and lost units), an optional per-unit
`units` detail and an optional per-lot `lots` detail. Use it to sync your catalog and stock
levels; use `GET /lots` when you need one product's lots filtered or paginated.
- Results are paginated and ordered by product creation date, newest first. Default page size is 10, maximum 200.
- Pass `skus[]` to restrict the page to products that carry any of the given SKUs (exact match on the SKU).
- `units` is present only when the product has something to report: unit-code (IMEI/serial) products list every active, reserved, damaged and lost unit with its unit code; other products list only their damaged and lost units, without a unit code.
- `lots` is present only on products that have at least one lot. Lots are listed in creation order, not by expiration date.
- `kit_childs` lists the components of a kit (bundle) with their quantity and the component product's id, name and SKUs. It is an empty array for non-kit products.
- The response is read from a replica, so very recent movements can lag a few seconds.




## OpenAPI

````yaml /openapi.yaml get /inventory
openapi: 3.1.0
info:
  title: Cubbo Clients API
  version: '1.0'
  summary: >-
    Orders, inventory, replenishments, returns, shipping and webhooks for Cubbo
    fulfillment.
  description: >
    The Cubbo Clients API connects your store, ERP or marketplace with Cubbo's
    fulfillment network.

    All endpoints except `POST /auth/token` require a bearer token; see the
    Authentication guide.

    Request and response bodies are JSON. Errors are JSON objects with an
    `error` key.
  contact:
    name: Cubbo integrations
    email: integraciones@cubbo.com
servers:
  - url: https://api.cubbo.com/v1
    description: Production
security:
  - bearerAuth: []
tags:
  - name: Authentication
    description: Exchange client credentials for a bearer token.
  - name: Orders
    description: Create, update, hold, cancel and read sales orders.
  - name: Shipping labels
    description: Read the shipping labels generated for an order.
  - name: Inventory
    description: Products and stock per store.
  - name: Lots
    description: Lot-level inventory for products with expiration or batch tracking.
  - name: Reports
    description: Bulk reports for reconciliation.
  - name: Replenishments
    description: Inbound shipments to the warehouse.
  - name: Returns
    description: Returns and exchanges.
  - name: Stores
    description: Store provisioning and settings.
  - name: Shipping methods
    description: Available shipping methods, coverage and quotes.
  - name: Click and collect
    description: Pickup points and in-store pickup orders.
paths:
  /inventory:
    get:
      tags:
        - Inventory
      summary: List products with stock
      description: >
        Returns the catalog of one store with the current stock of every
        product. Each product

        carries an aggregate `stock` breakdown (available, reserved, damaged,
        lost, expired, on hold,

        sell-ahead buckets, and per-source splits of damaged and lost units), an
        optional per-unit

        `units` detail and an optional per-lot `lots` detail. Use it to sync
        your catalog and stock

        levels; use `GET /lots` when you need one product's lots filtered or
        paginated.

        - Results are paginated and ordered by product creation date, newest
        first. Default page size is 10, maximum 200.

        - Pass `skus[]` to restrict the page to products that carry any of the
        given SKUs (exact match on the SKU).

        - `units` is present only when the product has something to report:
        unit-code (IMEI/serial) products list every active, reserved, damaged
        and lost unit with its unit code; other products list only their damaged
        and lost units, without a unit code.

        - `lots` is present only on products that have at least one lot. Lots
        are listed in creation order, not by expiration date.

        - `kit_childs` lists the components of a kit (bundle) with their
        quantity and the component product's id, name and SKUs. It is an empty
        array for non-kit products.

        - The response is read from a replica, so very recent movements can lag
        a few seconds.
      operationId: listInventory
      parameters:
        - name: store_id
          in: query
          required: true
          description: >-
            Store whose inventory you want. Your token must have access to this
            store.
          schema:
            type: integer
          example: 1234
        - name: skus[]
          in: query
          required: false
          description: >-
            Only return products that carry one of these SKUs (exact match).
            Repeat the parameter for several SKUs. Omit to return the whole
            catalog.
          schema:
            type: array
            items:
              type: string
          style: form
          explode: true
          example:
            - SKU-RED-M
            - SKU-RED-L
        - name: page
          in: query
          required: false
          description: Page number, starting at 1.
          schema:
            type: integer
            default: 1
          example: 1
        - name: per_page
          in: query
          required: false
          description: Products per page. Maximum 200.
          schema:
            type: integer
            default: 10
            maximum: 200
          example: 50
      responses:
        '200':
          description: One page of products with their stock.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InventoryResponse'
              example:
                products:
                  - id: 12345
                    name: Widget Pro Black
                    billing_name: Widget Pro - Black Edition
                    description: <p>A professional-grade widget.</p>
                    has_imei: false
                    is_fragile: false
                    is_kit: false
                    bar_code: '7501234567890'
                    is_dropshipping: false
                    has_expiration: true
                    freshness: 180
                    is_scannable: true
                    price: '99.99'
                    weight: 2.5
                    weight_unit: kg
                    length: '10.0'
                    width: '8.0'
                    height: '5.0'
                    dimension_unit: cm
                    stock:
                      IN_WAREHOUSE: 250
                      AVAILABLE: 188
                      AVAILABLE_NOT_EXTERNALLY_CONFIRMED: 0
                      AVAILABLE_EXTERNALLY_CONFIRMED: 188
                      UNAVAILABLE: 22
                      RECEPTION-INCOMING-SELL-AHEAD: 0
                      INCOMING-SELL-AHEAD: 0
                      RESERVED-RECEPTION-INCOMING-SELL-AHEAD: 0
                      RESERVED-INCOMING-SELL-AHEAD: 0
                      DAMAGED: 2
                      RECEPTION: 0
                      OUT_OF_STOCK: 0
                      RESERVED: 40
                      RESERVED_BY_ORDERS: 40
                      RESERVED_BY_RETURNS: 0
                      ACTIVE: 188
                      RESERVED-WITHOUT-SELL-AHEAD: 40
                      EXPIRED: 20
                      HOLDED: 20
                      BUFFER_STOCK: 0
                      LOST: 1
                      DAMAGED_BY_SOURCE:
                        STORAGE: 2
                      LOST_BY_SOURCE:
                        RETURN: 1
                    units:
                      - status: DAMAGED
                        damaged_source: STORAGE
                      - status: DAMAGED
                        damaged_source: STORAGE
                      - status: LOST
                        lost_source: RETURN
                    lots:
                      - unique_code: SKU-RED-M-L2026-04
                        expiration_date: '2026-12-31'
                        status: ACTIVE
                        quantities:
                          ACTIVE: 120
                          RESERVED: 30
                          DAMAGED: 2
                      - unique_code: SKU-RED-M-L2026-02
                        expiration_date: '2026-06-30'
                        status: HOLDED
                        quantities:
                          HOLDED: 20
                    store:
                      id: 1234
                      name: Example Store
                    product_codes:
                      - id: 9001
                        sku: SKU-RED-M
                    kit_childs: []
                  - id: 33000
                    name: Starter Bundle
                    billing_name: null
                    description: null
                    has_imei: false
                    is_fragile: false
                    is_kit: true
                    bar_code: '7508888888888'
                    is_dropshipping: false
                    has_expiration: false
                    freshness: null
                    is_scannable: true
                    price: '149.00'
                    weight: null
                    weight_unit: null
                    length: null
                    width: null
                    height: null
                    dimension_unit: cm
                    stock:
                      IN_WAREHOUSE: 0
                      AVAILABLE: 10
                      AVAILABLE_NOT_EXTERNALLY_CONFIRMED: 0
                      AVAILABLE_EXTERNALLY_CONFIRMED: 10
                      UNAVAILABLE: 0
                      RECEPTION-INCOMING-SELL-AHEAD: 0
                      INCOMING-SELL-AHEAD: 0
                      RESERVED-RECEPTION-INCOMING-SELL-AHEAD: 0
                      RESERVED-INCOMING-SELL-AHEAD: 0
                      DAMAGED: 0
                      RECEPTION: 0
                      OUT_OF_STOCK: 0
                      RESERVED: 0
                      RESERVED_BY_ORDERS: 0
                      RESERVED_BY_RETURNS: 0
                      ACTIVE: 10
                      RESERVED-WITHOUT-SELL-AHEAD: 0
                      EXPIRED: 0
                      HOLDED: 0
                      BUFFER_STOCK: 0
                      LOST: 0
                      DAMAGED_BY_SOURCE: {}
                      LOST_BY_SOURCE: {}
                    store:
                      id: 1234
                      name: Example Store
                    product_codes:
                      - id: 9300
                        sku: SKU-BUNDLE-01
                    kit_childs:
                      - id: 501
                        quantity: 2
                        price_per_item: '49.50'
                        kit_product:
                          id: 12345
                          name: Widget Pro Black
                          product_codes:
                            - id: 9001
                              sku: SKU-RED-M
                meta:
                  current_page: 1
                  next_page: 2
                  prev_page: null
                  total_pages: 12
                  first_page: true
                  last_page: false
                  per_page: 10
                  total_count: 118
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          description: Invalid parameters.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                missingStoreId:
                  value:
                    error: Parameter store_id is required
                perPageTooLarge:
                  value:
                    error: Parameter per_page cannot be greater than 200
                pageNotInteger:
                  value:
                    error: '''abc'' is not a valid Integer'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - bearerAuth: []
components:
  schemas:
    InventoryResponse:
      type: object
      description: One page of the store catalog with stock.
      properties:
        products:
          type: array
          description: Products on this page.
          items:
            $ref: '#/components/schemas/Product'
        meta:
          $ref: '#/components/schemas/PaginationMeta'
      required:
        - products
        - meta
    Error:
      type: object
      description: Error body returned by every failed request.
      required:
        - error
      properties:
        error:
          type: string
          description: >-
            Human-readable description of the failure. For `401` responses it is
            always `Unauthorized`.
          example: Parameter store_id is required
        message:
          type: string
          description: >-
            Present on `401` responses only; the reason the request was
            rejected.
          example: invalid token
        code:
          type:
            - string
            - 'null'
          description: >-
            Stable machine-readable code, present on some order, return and
            replenishment errors.
          example: ORDER_ALREADY_EXISTS
        context:
          type:
            - object
            - 'null'
          description: >-
            Extra data about the failure when available, for example the id of
            the conflicting order.
          additionalProperties: true
          example:
            order_id: 987654
    Product:
      type: object
      description: >-
        A product as returned by `GET /inventory`, with its aggregate stock and
        optional unit and lot detail.
      properties:
        id:
          type: integer
          description: Cubbo product id.
          example: 12345
        name:
          type: string
          description: Product display name.
          example: Widget Pro Black
        billing_name:
          type:
            - string
            - 'null'
          description: Name printed on invoices, when different from `name`.
          example: Widget Pro - Black Edition
        description:
          type:
            - string
            - 'null'
          description: Product description (may contain HTML).
          example: <p>A professional-grade widget.</p>
        has_imei:
          type: boolean
          description: Each unit is identified by an IMEI.
          example: false
        is_fragile:
          type: boolean
          description: Requires fragile handling.
          example: false
        is_kit:
          type: boolean
          description: The product is a kit (bundle) of other products; see `kit_childs`.
          example: false
        bar_code:
          type:
            - string
            - 'null'
          description: Barcode (UPC/EAN).
          example: '7501234567890'
        is_dropshipping:
          type: boolean
          description: Fulfilled by dropshipping; Cubbo does not hold stock for it.
          example: false
        has_expiration:
          type:
            - boolean
            - 'null'
          description: Stock is tracked by lot with an expiration date.
          example: true
        freshness:
          type:
            - integer
            - 'null'
          description: >-
            Minimum shelf life in days a lot must have when received, for
            expirable products.
          example: 180
        is_scannable:
          type: boolean
          description: >-
            Units can be scanned at picking. False for marketing inserts that
            are identified by image.
          example: true
        price:
          type:
            - string
            - 'null'
          description: Unit price, as a decimal string.
          example: '99.99'
        weight:
          type:
            - number
            - 'null'
          description: >-
            Unit weight in `weight_unit` (stored in kilograms when created
            through the API).
          example: 2.5
        weight_unit:
          type:
            - string
            - 'null'
          description: Unit of `weight`, for example `kg`.
          example: kg
        length:
          type:
            - string
            - 'null'
          description: Package length in `dimension_unit`, as a decimal string.
          example: '10.0'
        width:
          type:
            - string
            - 'null'
          description: Package width in `dimension_unit`, as a decimal string.
          example: '8.0'
        height:
          type:
            - string
            - 'null'
          description: Package height in `dimension_unit`, as a decimal string.
          example: '5.0'
        dimension_unit:
          type: string
          description: Unit of the dimensions.
          enum:
            - cm
            - mm
            - in
            - m
          example: cm
        stock:
          oneOf:
            - $ref: '#/components/schemas/ProductStock'
            - type: 'null'
          description: >-
            Aggregate stock across all lots and locations. Null for a product
            that has never had stock computed.
        units:
          type: array
          description: >-
            Per-unit detail. Present only when there is something to report (see
            endpoint description).
          items:
            $ref: '#/components/schemas/StockUnitDetail'
        lots:
          type: array
          description: Per-lot detail. Present only on products that have lots.
          items:
            $ref: '#/components/schemas/ProductLotDetail'
        store:
          type: object
          description: Store that owns the product.
          properties:
            id:
              type: integer
              description: Store id.
              example: 1234
            name:
              type: string
              description: Store name.
              example: Example Store
        product_codes:
          type: array
          description: SKUs registered for the product.
          items:
            $ref: '#/components/schemas/ProductCode'
        kit_childs:
          type: array
          description: Components of the kit. Empty unless `is_kit` is true.
          items:
            $ref: '#/components/schemas/ProductKitComponent'
      required:
        - id
        - name
        - is_kit
        - stock
        - store
        - product_codes
        - kit_childs
    PaginationMeta:
      type: object
      description: Paging information returned next to list results.
      properties:
        current_page:
          type: integer
          example: 1
        next_page:
          type:
            - integer
            - 'null'
          example: 2
        prev_page:
          type:
            - integer
            - 'null'
          example: null
        total_pages:
          type: integer
          example: 7
        first_page:
          type: boolean
          example: true
        last_page:
          type: boolean
          example: false
        per_page:
          type: integer
          example: 50
        total_count:
          type: integer
          example: 312
    ProductStock:
      type: object
      description: >-
        Aggregate stock counts of a product. All counts are units. Keys with a
        dash are returned exactly as written.
      properties:
        IN_WAREHOUSE:
          type: integer
          description: Units physically in the warehouse, in any status.
          example: 250
        AVAILABLE:
          type: integer
          description: >-
            Units you can sell now (active units minus buffer stock, plus
            sell-ahead units).
          example: 188
        AVAILABLE_NOT_EXTERNALLY_CONFIRMED:
          type: integer
          description: >-
            Available units from replenishments not yet confirmed by your system
            (relevant when your store only sells confirmed stock).
          example: 0
        AVAILABLE_EXTERNALLY_CONFIRMED:
          type: integer
          description: >-
            Available units from confirmed replenishments, plus sell-ahead
            units.
          example: 188
        UNAVAILABLE:
          type: integer
          description: >-
            Units present but not sellable (on hold, expired, damaged, in
            reception).
          example: 22
        RECEPTION-INCOMING-SELL-AHEAD:
          type: integer
          description: Sell-ahead units that arrived and are being received.
          example: 0
        INCOMING-SELL-AHEAD:
          type: integer
          description: Sell-ahead units still inbound.
          example: 0
        RESERVED-RECEPTION-INCOMING-SELL-AHEAD:
          type: integer
          description: Sell-ahead units in reception already reserved by orders.
          example: 0
        RESERVED-INCOMING-SELL-AHEAD:
          type: integer
          description: Inbound sell-ahead units already reserved by orders.
          example: 0
        DAMAGED:
          type: integer
          description: Units marked as damaged.
          example: 2
        RECEPTION:
          type: integer
          description: Units in the reception process, not yet put away.
          example: 0
        OUT_OF_STOCK:
          type: integer
          description: >-
            Units requested by orders that could not be reserved for lack of
            stock.
          example: 0
        RESERVED:
          type: integer
          description: Units reserved, by orders and by inbound returns.
          example: 40
        RESERVED_BY_ORDERS:
          type: integer
          description: Units reserved by open orders.
          example: 40
        RESERVED_BY_RETURNS:
          type: integer
          description: Units reserved by inbound returns.
          example: 0
        ACTIVE:
          type: integer
          description: Active (sellable, unreserved) units on the shelf.
          example: 188
        RESERVED-WITHOUT-SELL-AHEAD:
          type: integer
          description: Units reserved by orders, excluding sell-ahead reservations.
          example: 40
        EXPIRED:
          type: integer
          description: Units in expired lots.
          example: 20
        HOLDED:
          type: integer
          description: Units in lots on hold.
          example: 20
        BUFFER_STOCK:
          type: integer
          description: Safety stock configured for the product, excluded from `AVAILABLE`.
          example: 0
        LOST:
          type: integer
          description: Units marked as lost.
          example: 1
        DAMAGED_BY_SOURCE:
          type: object
          description: >-
            `DAMAGED` split by where the damage was found. Keys are
            `REPLENISHMENT`, `RETURN`, `STORAGE` or `UNKNOWN`; only sources with
            units appear.
          additionalProperties:
            type: integer
          example:
            STORAGE: 2
        LOST_BY_SOURCE:
          type: object
          description: >-
            `LOST` split by where the loss happened. Keys are `REPLENISHMENT`,
            `RETURN`, `STORAGE`, `DELIVERY` or `UNKNOWN`; only sources with
            units appear.
          additionalProperties:
            type: integer
          example:
            RETURN: 1
    StockUnitDetail:
      type: object
      description: >-
        One stock unit of a product. Unit-code products carry `unit_code`; other
        products only list damaged and lost units, without a code.
      properties:
        unit_code:
          type: string
          description: >-
            The unit's unique code (IMEI or serial). Present only for unit-code
            products.
          example: '356789100000001'
        status:
          type: string
          description: Unit status.
          enum:
            - ACTIVE
            - RESERVED
            - DAMAGED
            - LOST
          example: DAMAGED
        damaged_source:
          type:
            - string
            - 'null'
          description: Where the damage was found. Present only on `DAMAGED` units.
          enum:
            - REPLENISHMENT
            - RETURN
            - STORAGE
            - null
          example: STORAGE
        lost_source:
          type: string
          description: Where the loss happened. Present only when set, on `LOST` units.
          enum:
            - REPLENISHMENT
            - RETURN
            - STORAGE
            - DELIVERY
          example: RETURN
      required:
        - status
    ProductLotDetail:
      type: object
      description: >-
        A lot of the product with its unit counts, as embedded in `GET
        /inventory`.
      properties:
        unique_code:
          type: string
          description: Lot code, unique within the store.
          example: SKU-RED-M-L2026-04
        expiration_date:
          type:
            - string
            - 'null'
          format: date
          description: Expiration date (`YYYY-MM-DD`), or null when the lot has none.
          example: '2026-12-31'
        status:
          type: string
          description: Lot status.
          enum:
            - ACTIVE
            - HOLDED
            - DAMAGED
            - EXPIRED
          example: ACTIVE
        quantities:
          type: object
          description: >-
            The lot's units counted by unit status (for example `ACTIVE`,
            `RESERVED`, `DAMAGED`, `HOLDED`, `EXPIRED`, `SHIPPED`). Only
            statuses with at least one unit appear; empty object for a lot
            without units.
          additionalProperties:
            type: integer
          example:
            ACTIVE: 120
            RESERVED: 30
            DAMAGED: 2
      required:
        - unique_code
        - expiration_date
        - status
        - quantities
    ProductCode:
      type: object
      description: A SKU registered for a product.
      properties:
        id:
          type: integer
          description: SKU record id.
          example: 9001
        sku:
          type: string
          description: The SKU.
          example: SKU-RED-M
      required:
        - id
        - sku
    ProductKitComponent:
      type: object
      description: One component line of a kit (bundle).
      properties:
        id:
          type: integer
          description: Kit component line id.
          example: 501
        quantity:
          type: integer
          description: Units of the component in one kit.
          example: 2
        price_per_item:
          type:
            - string
            - 'null'
          description: >-
            Price assigned to each component unit when the kit is sold, as a
            decimal string.
          example: '49.50'
        kit_product:
          type:
            - object
            - 'null'
          description: >-
            The component product. Null when the component product has been
            removed from the catalog.
          properties:
            id:
              type: integer
              description: Component product id.
              example: 12345
            name:
              type: string
              description: Component product name.
              example: Widget Pro Black
            product_codes:
              type: array
              description: SKUs of the component product.
              items:
                $ref: '#/components/schemas/ProductCode'
      required:
        - id
        - quantity
        - kit_product
  responses:
    Unauthorized:
      description: >-
        Missing or invalid token, wrong credentials, or no access to the
        requested store.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            invalidToken:
              value:
                error: Unauthorized
                message: invalid token
            noHeader:
              value:
                error: Unauthorized
                message: no authorization header found
            storeNotAllowed:
              value:
                error: Unauthorized
                message: not allowed to show? this Store
    InternalServerError:
      description: >-
        Unexpected error. Retry with backoff; if it persists, send the timestamp
        to Cubbo support.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: 'unexpected error, timestamp: 1760000000'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: >-
        Token returned by `POST /auth/token`, sent as `Authorization: Bearer
        <token>`.

````

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