Skip to content
Last updated

Offers

Your wallet needs offers it can show before registration and offers selected for a known customer afterward. Use general discovery, targeted discovery and eligibility lookups to present the rate and terms and show whether the cardholder group can use an offer. A cardholder group holds rewards for one or more cardholders.

General offers

Call GET /api/v2/offers without a cardholder group. Results contain live and scheduled baseline offers broadly available to your customers. Customer-specific offers with a higher rate are returned only with the appropriate customer context. Purchase requirements and activation still apply.

Use rewardProductType to select the product your experience presents. Pages include data, page, pageSize, totalCount and hasNextPage. Defaults are page 1 and 25 items, with a maximum page size of 100. Continue until hasNextPage is false.

Targeted offers

For segmented offers, purchase history can determine which merchant offer a cardholder group qualifies for. See Offer Segments and Purchase History for backfilling and how matching works when history is missing.

Use general offers for the initial display before cardholder accounts exist. Once registration or lazy provisioning gives you a cardholder group, call GET /api/v2/chg/{chgId}/offers with its returned ID (chgId). Targeted discovery can include offers omitted from general discovery, with the same or better terms for that customer than the general baseline.

  • Display the returned offer IDs, rates and terms.
  • Offers that still need activation remain visible. Check when offers need to be activated again to distinguish activation scope from the total redemption limit.
  • Offers that have reached their redemption limit also remain visible. Explain why they cannot be used.

To narrow discovery to a merchant, call GET /api/v2/chg/{chgId}/merchant/{merchantId}/offers. For a complete view of that merchant's live offers and the group's eligibility and activation, use the eligibility lookup below.

Offer definition by ID

Call GET /api/v2/offer/{offerId} to read an offer's current terms, rate, limits and dates. You do not need a merchant or cardholder group in the path. Your issuer credential still determines access. An unknown or inaccessible offer returns 404.

GET <env-host>/api/v2/offer/mpo_66666666-6666-4666-8666-666666666666

This read returns the offer's current definition. Percents may preserve activation across related offers. Use the offer’s current activation status from the eligibility response to determine whether the cardholder needs to activate again.

Merchant eligibility

Call GET /api/v2/chg/{chgId}/merchant/{merchantId}/eligibility with the required query parameter scope=cashback or scope=branded.

The response includes:

  • Live offers selected for the cardholder group at that merchant and scope. Scheduled and ended offers are excluded.
  • segmentSource, explaining how customer context was determined.
  • chgQualified, showing the offer's current qualification.
  • activated, showing activation independently of other qualification restrictions.
activatedMeaning
trueThe current activation covers the next redemption.
falseActivation is required.
nullThe offer needs no activation.
chgQualifiedWhat to do
yesThe group passes offer-level checks. A qualifying purchase is still required.
notActivatedRecord the required activation before expecting an earned reward.
redemptionLimitReachedExplain that the group's redemption limit has been reached.

Percents selects the customer's offers, checks redemption limits and then activation. A failed evaluation returns an error.

Branded responses also return canSpend, which says whether the group can spend its existing balance. This is separate from earning a new reward. Read the offer's limit fields and termsAndConditionsText for the purchase requirements.

The Offer Segments and Purchase History guide explains how history supports offer selection. Money, dates and limits explains rate representations and purchase restrictions.

Group-wide eligibility

To check offers across all merchants for a cardholder group, call GET /api/v2/chg/{chgId}/offer/eligibility with the required scope=cashback or scope=branded. Choose one product per request. Use this to load offers from several merchants with one request.

GET <env-host>/api/v2/chg/{chgId}/offer/eligibility?scope=cashback

The response is a list of the merchant results described above. It covers all merchants with live offers available to your issuer for the selected product.

  • Each result includes the merchant ID and the group's eligibility and activation status.
  • An empty list means no live offers are visible.
  • Both eligibility lookups require an existing cardholder group. An unknown or inaccessible group returns 404.