Promotions

The Promotions API provides live read access to offer performance 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.

Native promotions only — external loyalty discounts are not attributed here

This report reflects the store's RORC-native promotions — the Offer, Premium, and Discount records configured in the RORC back office (for example, via Hostcom file authoring). RORC's own promotion engine applies these at the lane and rolls them up by offer code, which is what this endpoint returns.

When a store runs an external loyalty service (such as EngageHQ or a third-party loyalty provider) connected through the RORC two-way interface, that service decides awards in real time at the lane, and the discount is applied to the basket as a generic store coupon — it is not written into RORC's native offer catalog. As a result:

• Externally driven loyalty discounts are generally not represented in this offer-performance rollup, and any coupon activity that does surface carries no attribution to the external provider or its specific offers.
• The savings are still reflected in each transaction's discounted item prices and totals — they simply are not attributable as offers here. Coupon-bearing transactions can be isolated with the has_coupon filter on Sales › Transactions, but again without provider or offer attribution.

Guidance: Treat this endpoint as authoritative for RORC-native promotion performance. For stores on an external loyalty service, expect promotional activity to be under-represented here; obtain offer-level performance from the loyalty platform's own reporting (for example, the EngageHQ API) instead.

---

Offer Performance

Aggregate performance metrics for offers, grouped by offer code or by offer code and business day.

GET /v1/promotions/offers/performance

Authentication: OAuth Token (service_account or user)

Permission: rorcex:promotions.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.
offer_codes	string	No	CSV list of offer codes to filter by. Maximum 1024 characters total.
business_day_from	string	No	Start of a business day range (Y-m-d), inclusive.
business_day_to	string	No	End of a business day range (Y-m-d), inclusive.
group_by	string	No	Grouping dimension. One of: offer (default), offerAndDay.
metric	string	No	Primary metric to rank by when top is specified. One of: redemptions, sales, units, baskets. Defaults to redemptions.
top	integer	No	Limit results to the top N offers by the chosen metric. Must be between 1 and 1000.

Response

{
  "store_org_id": "org_00000k1L2m3N4o5",
  "data": [
    {
      "offerCode": 2001,
      "offerDescription": "COFFEE DONUT SPCL",
      "businessDayDate": null,
      "redemptionCount": 109,
      "redemptionAmount": -31.61,
      "transactionCount": 2956,
      "transactionAmount": 67201.88,
      "fromDate": "2025-12-11T00:00:00",
      "toDate": "2026-03-11T00:00:00"
    }
  ]
}

When group_by=offerAndDay, businessDayDate is populated and each offer is broken out per day (it is null when group_by=offer):

{
  "store_org_id": "org_00000k1L2m3N4o5",
  "data": [
    {
      "offerCode": 2001,
      "offerDescription": "COFFEE DONUT SPCL",
      "businessDayDate": "2026-06-10",
      "redemptionCount": 12,
      "redemptionAmount": -3.48,
      "transactionCount": 318,
      "transactionAmount": 7240.11,
      "fromDate": "2026-06-10T00:00:00",
      "toDate": "2026-06-10T00:00:00"
    }
  ]
}

Status: 200 OK

Row fields are returned as received from the RORC lane (camelCase for this endpoint). offerCode is RORC's native, integer offer-catalog code and offerDescription its configured name; redemptionCount is how many times the offer was redeemed and redemptionAmount the total discount given (a negative value); transactionCount / transactionAmount cover the transactions that included the offer. businessDayDate is null unless group_by=offerAndDay.

Errors

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

---

Changelog

Date	Change
2026-06-11	Initial publication.