Offers describe the commercial terms available through the authenticated issuer's channel-partner network.
GET /api/v1/omni/offerreturns offers that are current or upcoming for the issuer.GET /api/v1/omni/offer/{offerId}returns one issuer-scoped offer by UUID and supports historical lookup after an offer has ended.
The list is ordered by start date and then offer ID. Treat ordering as a convenience, not an incremental synchronization cursor.
An offer is immutable after creation except for endDate. Percents can extend, shorten, or end an offer by changing that field. A change to any other published commercial term is represented by a new offer with a new id.
Consumers should therefore:
- key records by offer
id; - allow
endDateto change during synchronization; - never overwrite the historical terms of one offer ID with terms from another; and
- retain ended offers when reconciliation requires historical lookup.
| Field | Meaning |
|---|---|
id | Stable Omni offer UUID |
merchantId | Omni merchant UUID used by merchant lookup |
spatialCondition | online, offline, or onlineAndOffline |
cardholderRate | Cardholder reward rate in basis points when rateIsPercent is true; otherwise a minor-unit amount |
publisherRate | Publisher/channel-partner rate in basis points |
startDate | Inclusive ISO 8601 start timestamp |
endDate | Inclusive ISO 8601 end timestamp, or null when represented as open-ended |
minSpend | Minimum eligible transaction amount in minor currency units, or null |
maxEarn | Maximum cardholder reward per qualifying transaction in minor currency units, or null |
maxTransactionValue | Maximum eligible transaction amount in minor currency units, or null |
maxRedemptions | Maximum qualifying redemptions per cardholder, or null |
segmentIdType | Segment lifecycle classification: new, existing, lapsed, or null |
segmentIdSubstrings | Partner-relevant substrings used to associate external segment identifiers, or null |
description | Reserved description field; currently null |
rateIsPercent | Whether cardholderRate is a percentage rate rather than a fixed amount |
Amounts are integers in the currency's minor unit. For USD, 500 means $5.00. A rate of 1250 basis points means 12.50%.
A transaction must satisfy every applicable constraint, including date, spatial condition, minimum spend, maximum transaction value, segment requirements, and redemption count. Do not display an unconstrained offer by discarding nullable constraint fields; null means the specific constraint is not set.