Inventory

The Inventory API provides live read access to stock levels and movement data for a single store, proxied directly from the RORC lane. All endpoints require an active RORCex install for the target store and are subject to lane availability.

---

List Stock

Return a paged list of stock records for a store, optionally filtered to a single product.

GET /v1/inventory/stock

Authentication: OAuth Token (service_account or user)

Permission: rorcex:inventory.view

Request Query Parameters

Field	Type	Required	Description
store_org_id	string	Yes	Target store organization hashkey (org_[A-Za-z0-9]{11}). Must be within the caller's org scope.
product_code	string	No	Filter to a single product code.
offset	integer	No	Pagination offset. Must be ≥ 0. Defaults to 0.
limit	integer	No	Page size. Must be between 1 and 500. Defaults to 100.

Response

{
  "store_org_id": "org_00000k1L2m3N4o5",
  "data": [
    {
      "productCode": "1",
      "productDescription": "GARBAGE TAG CASELLA",
      "totalOnHand": -8322,
      "unitType": "U",
      "lastReceivedDate": "2022-03-09T00:00:00"
    }
  ],
  "total": 52778,
  "offset": null,
  "limit": null
}

Status: 200 OK

Row fields are returned in camelCase as received from the RORC lane. total is the full match count; the lane does not echo pagination cursors, so offset and limit are null even though the request accepts them.

Errors

See Errors for authentication, authorization, upstream proxy, and store_not_found error shapes.

---

Aggregate Inventory Movements

Aggregate inventory movement metrics grouped by a chosen dimension.

GET /v1/inventory/movements/aggregate

Authentication: OAuth Token (service_account or user)

Permission: rorcex:inventory.view

Request Query Parameters

Field	Type	Required	Description
store_org_id	string	Yes	Target store organization hashkey.
group_by	string	Yes	Dimension to group by. One of: businessDayDate, productCode, departmentCode, categoryCode.
metric	string	No	Metric to aggregate. One of: sales, units, transactions. Defaults to sales.
top	integer	No	Limit results to the top N groups. Must be between 1 and 10000.
from	string	No	Start of date range (Y-m-d), inclusive.
to	string	No	End of date range (Y-m-d), inclusive.
product_codes	string	No	CSV list of product codes to filter by.
derived_weights	string	No	Control inclusion of derived-weight items. One of: include (default), exclude, only.

Response

{
  "store_org_id": "org_00000k1L2m3N4o5",
  "data": [
    {
      "key": "20163500000",
      "label": "REG GRND BEEF FP",
      "sales": 22780.12,
      "units": 217.67,
      "transactionCount": 2417,
      "cost": 0,
      "margin": 22780.12,
      "marginPercent": 100,
      "netMarginDollar": 22780.12,
      "netMarginPercent": 100,
      "rowCount": 89,
      "fromDate": "2025-12-12T00:00:00",
      "toDate": "2026-03-11T00:00:00",
      "requestedFrom": null,
      "requestedTo": null
    }
  ]
}

Status: 200 OK

Rows are camelCase, with key / label carrying the group_by value (e.g. the product code and description).

Errors

See Errors for authentication, authorization, upstream proxy, and store_not_found error shapes.

---

Product Movement History

Return bucketed movement history for a single product.

GET /v1/inventory/movements/history/{productCode}

Authentication: OAuth Token (service_account or user)

Permission: rorcex:inventory.view

Path Parameters

Parameter	Type	Description
productCode	string	Product code. Alphanumeric characters and hyphens (-), 1–64 characters.

Request Query Parameters

Field	Type	Required	Description
store_org_id	string	Yes	Target store organization hashkey.
buckets	string	No	CSV list of bucket types to include. Each value must be one of: daily, saleWeek, week53, yearToDate. Defaults to all bucket types.
from	string	No	Start of date range (Y-m-d), inclusive.
to	string	No	End of date range (Y-m-d), inclusive.
include_description	boolean	No	When true, include the product description in the response.
include_department	boolean	No	When true, include the department code and name in the response.
include_category	boolean	No	When true, include the category code and name in the response.

Response

{
  "store_org_id": "org_00000k1L2m3N4o5",
  "history": {
    "productCode": "100",
    "productDescription": "WRAPPED CANDY",
    "departmentCode": null,
    "departmentDescription": null,
    "categoryCode": null,
    "categoryDescription": null,
    "daily": [
      {
        "productCode": "100",
        "businessDayDate": "2026-05-02T00:00:00",
        "retailPrice": 1.29,
        "priceMultiple": 1,
        "priceOverride": false,
        "retailType": "BASE",
        "movementType": "SALE",
        "cost": 0,
        "count": 4,
        "movement": 4,
        "movementTotalSales": 5.16,
        "margin": 5.16,
        "marginPercent": 100,
        "netMarginDollar": 5.16,
        "netMarginPercent": 100,
        "deal": null,
        "premium": null,
        "discount": null
      }
    ],
    "saleWeek": [],
    "week53": [],
    "yearToDate": []
  }
}

Status: 200 OK

history is a single object in camelCase. Each requested bucket — daily, saleWeek, week53, yearToDate — is its own array of movement rows (omitted buckets are returned as empty arrays).

Errors

See Errors for authentication, authorization, upstream proxy, and store_not_found error shapes.

---

Changelog

Date	Change
2026-06-11	Initial publication.