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

# Get a bounded product-by-store inventory matrix

> Returns the Cartesian matrix for 1-25 exact products and up to 25 stores from one
publication revision. Identify products with either `product_ids` or `skus`. Identify stores
with `store_ids`, `inventory_store_codes`, or `lat`/`lng`; these selector groups are mutually exclusive.
A coordinate request chooses the nearest published consumer stores within `radius_m`, capped by `store_limit`.
Products and stores are emitted once, while observations reference their IDs.

The matrix is dense: every requested product-store pair has an observation row. A pair
with no qualifying stored observation is `unchecked`, never an inferred zero. Input order
is preserved. The request reads stored data and never triggers a Utah DABS refresh.




## OpenAPI

````yaml /openapi/v1.yaml get /inventory
openapi: 3.1.0
info:
  title: Independent Utah DABS API
  version: 1.0.0
  summary: Database-backed product, store, and reported-inventory reads
  description: >
    Version 1 pilot contract. All requests read a locally published database
    revision;

    no public request waits for or triggers Utah DABS. Reported quantities are

    observations, not purchase guarantees. This service is independent and is
    not

    affiliated with or endorsed by Utah DABS. The current local seed contains

    historical inventory fixtures; clients must inspect response warnings and

    coverage metadata.
servers:
  - url: http://127.0.0.1:5185/v1
    description: Local development only; set MINTLIFY_API_BASE_URL before publishing
security: []
tags:
  - name: Products
  - name: Search
  - name: Brands
  - name: Product families
  - name: Changes
  - name: Exports
  - name: Stores
  - name: Availability
  - name: Metadata
paths:
  /inventory:
    get:
      tags:
        - Availability
      summary: Get a bounded product-by-store inventory matrix
      description: >
        Returns the Cartesian matrix for 1-25 exact products and up to 25 stores
        from one

        publication revision. Identify products with either `product_ids` or
        `skus`. Identify stores

        with `store_ids`, `inventory_store_codes`, or `lat`/`lng`; these
        selector groups are mutually exclusive.

        A coordinate request chooses the nearest published consumer stores
        within `radius_m`, capped by `store_limit`.

        Products and stores are emitted once, while observations reference their
        IDs.


        The matrix is dense: every requested product-store pair has an
        observation row. A pair

        with no qualifying stored observation is `unchecked`, never an inferred
        zero. Input order

        is preserved. The request reads stored data and never triggers a Utah
        DABS refresh.
      operationId: getInventoryMatrix
      parameters:
        - $ref: '#/components/parameters/MatrixProductIds'
        - $ref: '#/components/parameters/MatrixSkus'
        - $ref: '#/components/parameters/MatrixStoreIds'
        - $ref: '#/components/parameters/MatrixStoreCodes'
        - $ref: '#/components/parameters/Latitude'
        - $ref: '#/components/parameters/Longitude'
        - $ref: '#/components/parameters/RadiusMeters'
        - $ref: '#/components/parameters/MatrixStoreLimit'
        - $ref: '#/components/parameters/InventoryAge'
        - $ref: '#/components/parameters/IfNoneMatch'
        - $ref: '#/components/parameters/IfModifiedSince'
      responses:
        '200':
          description: Dense inventory matrix from one immutable publication revision.
          headers:
            ETag:
              $ref: '#/components/headers/ETag'
            Last-Modified:
              $ref: '#/components/headers/LastModified'
            Cache-Control:
              $ref: '#/components/headers/InventoryCacheControl'
            X-Publication-Revision:
              $ref: '#/components/headers/PublicationRevision'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InventoryMatrixResponse'
        '304':
          $ref: '#/components/responses/NotModified'
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/Unavailable'
components:
  parameters:
    MatrixProductIds:
      name: product_ids
      in: query
      style: form
      explode: false
      description: >-
        One to 25 stable product UUIDs. Required unless `skus` is supplied;
        order is preserved.
      schema:
        type: array
        minItems: 1
        maxItems: 25
        uniqueItems: true
        items:
          type: string
          format: uuid
    MatrixSkus:
      name: skus
      in: query
      style: form
      explode: false
      description: >-
        One to 25 current or unambiguous historical six-digit DABS SKUs.
        Required unless `product_ids` is supplied; leading zeros and order are
        preserved.
      schema:
        type: array
        minItems: 1
        maxItems: 25
        uniqueItems: true
        items:
          $ref: '#/components/schemas/DabsSku'
    MatrixStoreIds:
      name: store_ids
      in: query
      style: form
      explode: false
      description: >-
        One to 25 stable store UUIDs. Required unless `inventory_store_codes` is
        supplied; order is preserved.
      schema:
        type: array
        minItems: 1
        maxItems: 25
        uniqueItems: true
        items:
          type: string
          format: uuid
    MatrixStoreCodes:
      name: inventory_store_codes
      in: query
      style: form
      explode: false
      description: >-
        One to 25 four-digit inventory store codes. Required unless `store_ids`
        is supplied; leading zeros and order are preserved.
      schema:
        type: array
        minItems: 1
        maxItems: 25
        uniqueItems: true
        items:
          $ref: '#/components/schemas/StoreInventoryCode'
    Latitude:
      name: lat
      in: query
      description: WGS84 latitude; must be paired with `lng`.
      schema:
        type: number
        format: double
        minimum: -90
        maximum: 90
    Longitude:
      name: lng
      in: query
      description: WGS84 longitude; must be paired with `lat`.
      schema:
        type: number
        format: double
        minimum: -180
        maximum: 180
    RadiusMeters:
      name: radius_m
      in: query
      description: Radius in meters; valid only with coordinates.
      schema:
        type: integer
        minimum: 1
        maximum: 500000
        default: 50000
    MatrixStoreLimit:
      name: store_limit
      in: query
      description: >-
        Maximum number of nearest stores selected for a coordinate-scoped
        matrix. Valid only with coordinates.
      schema:
        type: integer
        minimum: 1
        maximum: 25
        default: 25
    InventoryAge:
      name: inventory_age
      in: query
      description: Whether inventory predicates require the current retrieval-age policy.
      schema:
        type: string
        enum:
          - within_policy
          - any_age
        default: within_policy
    IfNoneMatch:
      name: If-None-Match
      in: header
      description: Strong entity tag from an earlier response.
      schema:
        type: string
    IfModifiedSince:
      name: If-Modified-Since
      in: header
      description: HTTP-date fallback validator. ETag takes precedence.
      schema:
        type: string
  headers:
    ETag:
      description: >-
        Strong validator for the response representation. A new publication may
        retain the validator when this response is unchanged.
      schema:
        type: string
      example: '"v1-018f2fd0-a3d4-7d20-9c11-9482722f6b26-a91c"'
    LastModified:
      description: >-
        Newest relevant publication time in HTTP-date format; not an upstream
        update time.
      schema:
        type: string
      example: Tue, 15 Sep 2026 16:31:00 GMT
    InventoryCacheControl:
      schema:
        type: string
      example: public, max-age=30, stale-while-revalidate=120
    PublicationRevision:
      description: Immutable API publication revision used for this representation.
      schema:
        type: string
        format: uuid
    RetryAfter:
      description: Seconds until retry or an HTTP-date.
      schema:
        type: string
    RequestId:
      description: >-
        Server-generated identifier for correlating a response with private
        operational logs.
      schema:
        type: string
        format: uuid
  schemas:
    InventoryMatrixResponse:
      type: object
      additionalProperties: false
      required:
        - data
        - meta
      properties:
        data:
          $ref: '#/components/schemas/InventoryMatrixData'
        meta:
          $ref: '#/components/schemas/InventoryMatrixMeta'
    DabsSku:
      type: string
      pattern: ^[0-9]{6}$
      examples:
        - '347210'
        - '004190'
    StoreInventoryCode:
      type: string
      pattern: ^[0-9]{4}$
      examples:
        - '0002'
    InventoryMatrixData:
      type: object
      additionalProperties: false
      required:
        - products
        - stores
        - observations
      properties:
        products:
          type: array
          minItems: 1
          maxItems: 25
          items:
            $ref: '#/components/schemas/AvailabilityComparisonProduct'
        stores:
          type: array
          minItems: 0
          maxItems: 25
          items:
            $ref: '#/components/schemas/StoreSummary'
        observations:
          type: array
          minItems: 0
          maxItems: 625
          description: Product-major, store-minor dense matrix in request order.
          items:
            $ref: '#/components/schemas/InventoryMatrixObservation'
    InventoryMatrixMeta:
      type: object
      additionalProperties: false
      required:
        - coverage
        - warnings
      properties:
        coverage:
          $ref: '#/components/schemas/InventoryMatrixCoverage'
        warnings:
          type: array
          items:
            $ref: '#/components/schemas/Warning'
    Problem:
      type: object
      additionalProperties: false
      required:
        - type
        - title
        - status
        - detail
        - instance
        - code
        - request_id
      properties:
        type:
          type: string
          format: uri
        title:
          type: string
        status:
          type: integer
          minimum: 400
          maximum: 599
        detail:
          type: string
        instance:
          type: string
          format: uri-reference
        code:
          type: string
        request_id:
          type: string
          format: uuid
        invalid_params:
          type: array
          items:
            $ref: '#/components/schemas/InvalidParameter'
    AvailabilityComparisonProduct:
      type: object
      additionalProperties: false
      required:
        - id
        - source_ids
        - name
        - brand
        - brand_id
        - package_size
        - price
        - status
      properties:
        id:
          type: string
          format: uuid
        source_ids:
          $ref: '#/components/schemas/SourceProductIds'
        name:
          type: string
          description: >-
            Consumer display title without the resolved brand or structured
            package dimensions.
        brand:
          type:
            - string
            - 'null'
        brand_id:
          type:
            - string
            - 'null'
          format: uuid
        package_size:
          $ref: '#/components/schemas/PackageSize'
        price:
          oneOf:
            - $ref: '#/components/schemas/MoneyObservation'
            - type: 'null'
        status:
          $ref: '#/components/schemas/ProductStatus'
    StoreSummary:
      type: object
      additionalProperties: false
      required:
        - id
        - source_ids
        - name
        - address
        - phone
        - contact_links
        - location
        - distance_m
        - access_type
        - operational_status
        - services
        - regular_hours_available
        - directory_presence
        - details_times
      properties:
        id:
          type: string
          format: uuid
        source_ids:
          $ref: '#/components/schemas/StoreSourceIds'
        name:
          type: string
        address:
          $ref: '#/components/schemas/PostalAddress'
        phone:
          type:
            - string
            - 'null'
          description: E.164 when normalization is verified.
        contact_links:
          $ref: '#/components/schemas/ContactLinks'
        location:
          oneOf:
            - $ref: '#/components/schemas/GeoPoint'
            - type: 'null'
        distance_m:
          type:
            - integer
            - 'null'
          minimum: 0
        access_type:
          $ref: '#/components/schemas/StoreAccessType'
        operational_status:
          $ref: '#/components/schemas/StoreOperationalStatus'
        services:
          type: array
          uniqueItems: true
          items:
            type: string
            enum:
              - refrigerated_beer
              - wine_store
              - high_end_product_room
              - curbside_pickup
              - accessible_entrance
              - parking
        regular_hours_available:
          type: boolean
        directory_presence:
          oneOf:
            - $ref: '#/components/schemas/SourcePresenceSummary'
            - type: 'null'
        details_times:
          $ref: '#/components/schemas/ObservationTimes'
    InventoryMatrixObservation:
      type: object
      additionalProperties: false
      required:
        - product_id
        - store_id
        - observation_state
        - quantity_reported
        - quantity_semantics
        - purchase_eligibility
        - eligibility_reason_code
        - retrieval_policy_id
        - meets_retrieval_policy
        - upstream_age_known
        - times
      properties:
        product_id:
          type: string
          format: uuid
        store_id:
          type: string
          format: uuid
        observation_state:
          $ref: '#/components/schemas/ObservationState'
        quantity_reported:
          type:
            - integer
            - 'null'
          minimum: 0
        quantity_semantics:
          type: string
          const: dabs_reported_unverified
        purchase_eligibility:
          $ref: '#/components/schemas/PublishedPurchaseEligibility'
        eligibility_reason_code:
          type: string
        retrieval_policy_id:
          type: string
          const: standard-6h
        meets_retrieval_policy:
          type: boolean
        upstream_age_known:
          type: boolean
          const: false
        times:
          $ref: '#/components/schemas/NullableObservationTimes'
    InventoryMatrixCoverage:
      type: object
      additionalProperties: false
      required:
        - status
        - scope
        - expected_pair_count
        - checked_pair_count
        - unchecked_pair_count
        - reported_positive_pair_count
        - reported_zero_pair_count
        - row_absent_pair_count
        - retrieved_at_min
        - retrieved_at_max
        - retrieval_policy_id
        - upstream_age_known
        - denominator_definition
      properties:
        status:
          type: string
          enum:
            - complete_for_retrieval_policy
            - partial
            - none
        scope:
          oneOf:
            - type: object
              additionalProperties: false
              required:
                - type
              properties:
                type:
                  type: string
                  const: store_set
            - type: object
              additionalProperties: false
              required:
                - type
                - origin
                - radius_m
                - store_limit
              properties:
                type:
                  type: string
                  const: radius
                origin:
                  $ref: '#/components/schemas/GeoPoint'
                radius_m:
                  type: integer
                  minimum: 1
                  maximum: 500000
                store_limit:
                  type: integer
                  minimum: 1
                  maximum: 25
        expected_pair_count:
          type: integer
          minimum: 0
          maximum: 625
        checked_pair_count:
          type: integer
          minimum: 0
          maximum: 625
        unchecked_pair_count:
          type: integer
          minimum: 0
          maximum: 625
        reported_positive_pair_count:
          type: integer
          minimum: 0
        reported_zero_pair_count:
          type: integer
          minimum: 0
        row_absent_pair_count:
          type: integer
          minimum: 0
        retrieved_at_min:
          type:
            - string
            - 'null'
          format: date-time
        retrieved_at_max:
          type:
            - string
            - 'null'
          format: date-time
        retrieval_policy_id:
          type: string
          const: standard-6h
        upstream_age_known:
          type: boolean
          const: false
        denominator_definition:
          type: string
          enum:
            - requested_published_products_x_requested_published_stores
            - >-
              requested_published_products_x_nearest_published_consumer_stores_within_radius_up_to_store_limit
    Warning:
      type: object
      additionalProperties: false
      description: >-
        Machine-readable data qualification. Current codes include FIXTURE_DATA,
        INVENTORY_COVERAGE_PARTIAL, SOURCE_REFRESH_DELAYED,
        UPSTREAM_PRODUCT_UNAVAILABLE, SOURCE_SCHEMA_QUARANTINED, and
        CATALOG_BATCH_OLD.
      required:
        - code
      properties:
        code:
          type: string
          examples:
            - INVENTORY_COVERAGE_PARTIAL
    InvalidParameter:
      type: object
      additionalProperties: false
      required:
        - name
        - reason
      properties:
        name:
          type: string
        reason:
          type: string
    SourceProductIds:
      type: object
      additionalProperties: false
      required:
        - utah_dabs_sku
      properties:
        utah_dabs_sku:
          $ref: '#/components/schemas/DabsSku'
    PackageSize:
      type: object
      additionalProperties: false
      description: >-
        Parsed package dimensions. `milliliters` preserves the legacy normalized
        DABS size value and can describe either a container or a complete
        package; new integrations should use the explicit unit and total fields
        together with `interpretation`. Null means the dimension was not
        established.
      required:
        - milliliters
        - container_count
        - unit_milliliters
        - total_milliliters
        - display
        - interpretation
        - basis
        - normalization_state
      properties:
        milliliters:
          type:
            - integer
            - 'null'
          minimum: 1
          deprecated: true
          description: >-
            Legacy normalized source value with historically ambiguous multipack
            semantics.
        container_count:
          type:
            - integer
            - 'null'
          minimum: 1
        unit_milliliters:
          type:
            - integer
            - 'null'
          minimum: 1
          description: Volume of one container when established.
        total_milliliters:
          type:
            - integer
            - 'null'
          minimum: 1
          description: Calculated total package volume when established.
        display:
          type:
            - string
            - 'null'
          examples:
            - 8 × 355 mL
        interpretation:
          type: string
          enum:
            - single_container
            - multi_container
            - ambiguous
            - missing
        basis:
          type: string
          enum:
            - normalized_source_size
            - explicit_source_name_and_pack_count
            - corroborated_source_name_and_total
            - pack_count_with_ambiguous_source_size
            - none
        normalization_state:
          type: string
          enum:
            - normalized
            - unconfirmed
            - missing
    MoneyObservation:
      type: object
      additionalProperties: false
      required:
        - amount_minor
        - currency
        - display
        - source
        - times
      properties:
        amount_minor:
          type: integer
          format: int64
          minimum: 0
        currency:
          type: string
          const: USD
        display:
          type: string
          examples:
            - $19.99
        source:
          type: string
          enum:
            - utah_dabs_workbook
            - utah_dabs_locator
        times:
          $ref: '#/components/schemas/ObservationTimes'
    ProductStatus:
      type: object
      additionalProperties: false
      required:
        - code
        - label
        - lifecycle
        - source_raw
      properties:
        code:
          type: string
          examples:
            - '1'
        label:
          type: string
          examples:
            - General distribution
        lifecycle:
          type: string
          enum:
            - active
            - discontinued
            - restricted
            - unavailable
            - unknown
        source_raw:
          type: string
    StoreSourceIds:
      type: object
      additionalProperties: false
      required:
        - inventory_store_code
        - directory_id
      properties:
        inventory_store_code:
          oneOf:
            - $ref: '#/components/schemas/StoreInventoryCode'
            - type: 'null'
        directory_id:
          type:
            - string
            - 'null'
    PostalAddress:
      type: object
      additionalProperties: false
      required:
        - line1
        - line2
        - city
        - region
        - postal_code
        - country
      properties:
        line1:
          type: string
        line2:
          type:
            - string
            - 'null'
        city:
          type: string
        region:
          type: string
          examples:
            - UT
        postal_code:
          type: string
        country:
          type: string
          const: US
    ContactLinks:
      type: object
      additionalProperties: false
      required:
        - telephone_uri
        - geo_uri
      properties:
        telephone_uri:
          type:
            - string
            - 'null'
          description: Neutral `tel:` URI, present only when the phone was normalized.
        geo_uri:
          type:
            - string
            - 'null'
          description: Neutral RFC 5870 `geo:` URI derived from published coordinates.
    GeoPoint:
      type: object
      additionalProperties: false
      required:
        - latitude
        - longitude
      properties:
        latitude:
          type: number
          format: double
          minimum: -90
          maximum: 90
        longitude:
          type: number
          format: double
          minimum: -180
          maximum: 180
    StoreAccessType:
      type: string
      enum:
        - consumer_state_store
        - licensee_only
        - package_agency
        - unknown
    StoreOperationalStatus:
      type: object
      additionalProperties: false
      required:
        - state
        - note
        - source
      properties:
        state:
          type: string
          enum:
            - open
            - temporarily_closed
            - permanently_closed
            - unknown
        note:
          type:
            - string
            - 'null'
        source:
          type: string
          enum:
            - reviewed_editorial
            - unknown
    SourcePresenceSummary:
      type: object
      additionalProperties: false
      description: Compact presence state for collection rows.
      required:
        - state
        - last_seen_at
      properties:
        state:
          type: string
          enum:
            - present
            - suspect_missing
            - retirement_review_required
            - reviewed_retired
        last_seen_at:
          type:
            - string
            - 'null'
          format: date-time
    ObservationTimes:
      type: object
      additionalProperties: false
      required:
        - source_updated_at
        - retrieved_at
        - published_at
      properties:
        source_updated_at:
          type:
            - string
            - 'null'
          format: date-time
          description: Null when the source supplies no update timestamp.
        retrieved_at:
          type: string
          format: date-time
        published_at:
          type: string
          format: date-time
    ObservationState:
      type: string
      enum:
        - reported_positive
        - reported_zero
        - row_absent
        - unchecked
    PublishedPurchaseEligibility:
      type: string
      enum:
        - eligible
        - restricted
        - unavailable
        - unknown
    NullableObservationTimes:
      type: object
      additionalProperties: false
      required:
        - source_updated_at
        - retrieved_at
        - published_at
      properties:
        source_updated_at:
          type:
            - string
            - 'null'
          format: date-time
        retrieved_at:
          type:
            - string
            - 'null'
          format: date-time
        published_at:
          type:
            - string
            - 'null'
          format: date-time
  responses:
    NotModified:
      description: Representation has not changed for the supplied validator.
      headers:
        ETag:
          $ref: '#/components/headers/ETag'
        Cache-Control:
          description: Cache policy for the validated representation.
          schema:
            type: string
        X-Publication-Revision:
          $ref: '#/components/headers/PublicationRevision'
    BadRequest:
      description: Invalid parameters, incompatible scope, or cursor/query mismatch.
      headers:
        Cache-Control:
          schema:
            type: string
          example: no-store
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
    NotFound:
      description: Published resource or source mapping not found.
      headers:
        Cache-Control:
          schema:
            type: string
          example: no-store
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
    RateLimited:
      description: Public read-rate limit exceeded.
      headers:
        Cache-Control:
          schema:
            type: string
          example: no-store
        Retry-After:
          $ref: '#/components/headers/RetryAfter'
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
    InternalError:
      description: >-
        An unexpected server failure. Details are withheld; report the response
        request identifier.
      headers:
        Cache-Control:
          schema:
            type: string
          example: no-store
        X-Request-ID:
          $ref: '#/components/headers/RequestId'
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
    Unavailable:
      description: No safe published database revision is currently readable.
      headers:
        Cache-Control:
          schema:
            type: string
          example: no-store
        Retry-After:
          $ref: '#/components/headers/RetryAfter'
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'

````