Get a bounded product-by-store inventory matrix

curl --request GET \
  --url http://127.0.0.1:5185/v1/inventory

{
  "data": {
    "products": [
      {
        "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "source_ids": {
          "utah_dabs_sku": "347210"
        },
        "name": "<string>",
        "brand": "<string>",
        "brand_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "package_size": {
          "milliliters": 2,
          "container_count": 2,
          "unit_milliliters": 2,
          "total_milliliters": 2,
          "display": "8 × 355 mL",
          "interpretation": "single_container",
          "basis": "normalized_source_size",
          "normalization_state": "normalized"
        },
        "price": {
          "amount_minor": 1,
          "currency": "USD",
          "display": "$19.99",
          "source": "utah_dabs_workbook",
          "times": {
            "source_updated_at": "2023-11-07T05:31:56Z",
            "retrieved_at": "2023-11-07T05:31:56Z",
            "published_at": "2023-11-07T05:31:56Z"
          }
        },
        "status": {
          "code": "1",
          "label": "General distribution",
          "lifecycle": "active",
          "source_raw": "<string>"
        }
      }
    ],
    "stores": [
      {
        "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "source_ids": {
          "inventory_store_code": "0002",
          "directory_id": "<string>"
        },
        "name": "<string>",
        "address": {
          "line1": "<string>",
          "line2": "<string>",
          "city": "<string>",
          "region": "UT",
          "postal_code": "<string>",
          "country": "US"
        },
        "phone": "<string>",
        "contact_links": {
          "telephone_uri": "<string>",
          "geo_uri": "<string>"
        },
        "location": {
          "latitude": 0,
          "longitude": 0
        },
        "distance_m": 1,
        "access_type": "consumer_state_store",
        "operational_status": {
          "state": "open",
          "note": "<string>",
          "source": "reviewed_editorial"
        },
        "services": [
          "refrigerated_beer"
        ],
        "regular_hours_available": true,
        "directory_presence": {
          "state": "present",
          "last_seen_at": "2023-11-07T05:31:56Z"
        },
        "details_times": {
          "source_updated_at": "2023-11-07T05:31:56Z",
          "retrieved_at": "2023-11-07T05:31:56Z",
          "published_at": "2023-11-07T05:31:56Z"
        }
      }
    ],
    "observations": [
      {
        "product_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "store_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "observation_state": "reported_positive",
        "quantity_reported": 1,
        "quantity_semantics": "dabs_reported_unverified",
        "purchase_eligibility": "eligible",
        "eligibility_reason_code": "<string>",
        "retrieval_policy_id": "standard-6h",
        "meets_retrieval_policy": true,
        "upstream_age_known": false,
        "times": {
          "source_updated_at": "2023-11-07T05:31:56Z",
          "retrieved_at": "2023-11-07T05:31:56Z",
          "published_at": "2023-11-07T05:31:56Z"
        }
      }
    ]
  },
  "meta": {
    "coverage": {
      "status": "complete_for_retrieval_policy",
      "scope": {
        "type": "store_set"
      },
      "expected_pair_count": 312,
      "checked_pair_count": 312,
      "unchecked_pair_count": 312,
      "reported_positive_pair_count": 1,
      "reported_zero_pair_count": 1,
      "row_absent_pair_count": 1,
      "retrieved_at_min": "2023-11-07T05:31:56Z",
      "retrieved_at_max": "2023-11-07T05:31:56Z",
      "retrieval_policy_id": "standard-6h",
      "upstream_age_known": false,
      "denominator_definition": "requested_published_products_x_requested_published_stores"
    },
    "warnings": [
      {
        "code": "INVENTORY_COVERAGE_PARTIAL"
      }
    ]
  }
}

{
  "type": "<string>",
  "title": "<string>",
  "status": 499,
  "detail": "<string>",
  "instance": "<string>",
  "code": "<string>",
  "request_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "invalid_params": [
    {
      "name": "<string>",
      "reason": "<string>"
    }
  ]
}

{
  "type": "<string>",
  "title": "<string>",
  "status": 499,
  "detail": "<string>",
  "instance": "<string>",
  "code": "<string>",
  "request_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "invalid_params": [
    {
      "name": "<string>",
      "reason": "<string>"
    }
  ]
}

{
  "type": "<string>",
  "title": "<string>",
  "status": 499,
  "detail": "<string>",
  "instance": "<string>",
  "code": "<string>",
  "request_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "invalid_params": [
    {
      "name": "<string>",
      "reason": "<string>"
    }
  ]
}

{
  "type": "<string>",
  "title": "<string>",
  "status": 499,
  "detail": "<string>",
  "instance": "<string>",
  "code": "<string>",
  "request_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "invalid_params": [
    {
      "name": "<string>",
      "reason": "<string>"
    }
  ]
}

{
  "type": "<string>",
  "title": "<string>",
  "status": 499,
  "detail": "<string>",
  "instance": "<string>",
  "code": "<string>",
  "request_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "invalid_params": [
    {
      "name": "<string>",
      "reason": "<string>"
    }
  ]
}

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.

curl --request GET \
  --url http://127.0.0.1:5185/v1/inventory

{
  "data": {
    "products": [
      {
        "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "source_ids": {
          "utah_dabs_sku": "347210"
        },
        "name": "<string>",
        "brand": "<string>",
        "brand_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "package_size": {
          "milliliters": 2,
          "container_count": 2,
          "unit_milliliters": 2,
          "total_milliliters": 2,
          "display": "8 × 355 mL",
          "interpretation": "single_container",
          "basis": "normalized_source_size",
          "normalization_state": "normalized"
        },
        "price": {
          "amount_minor": 1,
          "currency": "USD",
          "display": "$19.99",
          "source": "utah_dabs_workbook",
          "times": {
            "source_updated_at": "2023-11-07T05:31:56Z",
            "retrieved_at": "2023-11-07T05:31:56Z",
            "published_at": "2023-11-07T05:31:56Z"
          }
        },
        "status": {
          "code": "1",
          "label": "General distribution",
          "lifecycle": "active",
          "source_raw": "<string>"
        }
      }
    ],
    "stores": [
      {
        "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "source_ids": {
          "inventory_store_code": "0002",
          "directory_id": "<string>"
        },
        "name": "<string>",
        "address": {
          "line1": "<string>",
          "line2": "<string>",
          "city": "<string>",
          "region": "UT",
          "postal_code": "<string>",
          "country": "US"
        },
        "phone": "<string>",
        "contact_links": {
          "telephone_uri": "<string>",
          "geo_uri": "<string>"
        },
        "location": {
          "latitude": 0,
          "longitude": 0
        },
        "distance_m": 1,
        "access_type": "consumer_state_store",
        "operational_status": {
          "state": "open",
          "note": "<string>",
          "source": "reviewed_editorial"
        },
        "services": [
          "refrigerated_beer"
        ],
        "regular_hours_available": true,
        "directory_presence": {
          "state": "present",
          "last_seen_at": "2023-11-07T05:31:56Z"
        },
        "details_times": {
          "source_updated_at": "2023-11-07T05:31:56Z",
          "retrieved_at": "2023-11-07T05:31:56Z",
          "published_at": "2023-11-07T05:31:56Z"
        }
      }
    ],
    "observations": [
      {
        "product_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "store_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "observation_state": "reported_positive",
        "quantity_reported": 1,
        "quantity_semantics": "dabs_reported_unverified",
        "purchase_eligibility": "eligible",
        "eligibility_reason_code": "<string>",
        "retrieval_policy_id": "standard-6h",
        "meets_retrieval_policy": true,
        "upstream_age_known": false,
        "times": {
          "source_updated_at": "2023-11-07T05:31:56Z",
          "retrieved_at": "2023-11-07T05:31:56Z",
          "published_at": "2023-11-07T05:31:56Z"
        }
      }
    ]
  },
  "meta": {
    "coverage": {
      "status": "complete_for_retrieval_policy",
      "scope": {
        "type": "store_set"
      },
      "expected_pair_count": 312,
      "checked_pair_count": 312,
      "unchecked_pair_count": 312,
      "reported_positive_pair_count": 1,
      "reported_zero_pair_count": 1,
      "row_absent_pair_count": 1,
      "retrieved_at_min": "2023-11-07T05:31:56Z",
      "retrieved_at_max": "2023-11-07T05:31:56Z",
      "retrieval_policy_id": "standard-6h",
      "upstream_age_known": false,
      "denominator_definition": "requested_published_products_x_requested_published_stores"
    },
    "warnings": [
      {
        "code": "INVENTORY_COVERAGE_PARTIAL"
      }
    ]
  }
}

{
  "type": "<string>",
  "title": "<string>",
  "status": 499,
  "detail": "<string>",
  "instance": "<string>",
  "code": "<string>",
  "request_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "invalid_params": [
    {
      "name": "<string>",
      "reason": "<string>"
    }
  ]
}

{
  "type": "<string>",
  "title": "<string>",
  "status": 499,
  "detail": "<string>",
  "instance": "<string>",
  "code": "<string>",
  "request_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "invalid_params": [
    {
      "name": "<string>",
      "reason": "<string>"
    }
  ]
}

{
  "type": "<string>",
  "title": "<string>",
  "status": 499,
  "detail": "<string>",
  "instance": "<string>",
  "code": "<string>",
  "request_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "invalid_params": [
    {
      "name": "<string>",
      "reason": "<string>"
    }
  ]
}

{
  "type": "<string>",
  "title": "<string>",
  "status": 499,
  "detail": "<string>",
  "instance": "<string>",
  "code": "<string>",
  "request_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "invalid_params": [
    {
      "name": "<string>",
      "reason": "<string>"
    }
  ]
}

{
  "type": "<string>",
  "title": "<string>",
  "status": 499,
  "detail": "<string>",
  "instance": "<string>",
  "code": "<string>",
  "request_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "invalid_params": [
    {
      "name": "<string>",
      "reason": "<string>"
    }
  ]
}

Headers

If-None-Match

string

Strong entity tag from an earlier response.

If-Modified-Since

string

HTTP-date fallback validator. ETag takes precedence.

Query Parameters

product_ids

string<uuid>[]

One to 25 stable product UUIDs. Required unless skus is supplied; order is preserved.

Required array length: 1 - 25 elements

skus

string[]

One to 25 current or unambiguous historical six-digit DABS SKUs. Required unless product_ids is supplied; leading zeros and order are preserved.

Required array length: 1 - 25 elements

Pattern: ^[0-9]{6}$

store_ids

string<uuid>[]

One to 25 stable store UUIDs. Required unless inventory_store_codes is supplied; order is preserved.

Required array length: 1 - 25 elements

inventory_store_codes

string[]

One to 25 four-digit inventory store codes. Required unless store_ids is supplied; leading zeros and order are preserved.

Required array length: 1 - 25 elements

Pattern: ^[0-9]{4}$

lat

number<double>

WGS84 latitude; must be paired with lng.

Required range: -90 <= x <= 90

lng

number<double>

WGS84 longitude; must be paired with lat.

Required range: -180 <= x <= 180

radius_m

integer

default:50000

Radius in meters; valid only with coordinates.

Required range: 1 <= x <= 500000

store_limit

integer

default:25

Maximum number of nearest stores selected for a coordinate-scoped matrix. Valid only with coordinates.

Required range: 1 <= x <= 25

inventory_age

enum<string>

default:within_policy

Whether inventory predicates require the current retrieval-age policy.

Available options:

within_policy,

any_age

Response

Dense inventory matrix from one immutable publication revision.

data

object

required

Show child attributes

Exports

Changes

Availability

Products

Search

Brands

Product families

Stores

Metadata

Get a bounded product-by-store inventory matrix

Headers

Query Parameters

Response