Merchants + Offer Activation and Earn/Spend Eligibility

Merchants and offers determine where a cardholder group can earn cashback or branded balance. Activation is required before earning either cashback or branded balance.

Use merchant and offer endpoints to build issuer-side presentation:

• GET /api/v2/chg/{chgId}/merchants
• GET /api/v2/chg/{chgId}/merchant/{merchantId}
• GET /api/v2/chg/{chgId}/offers
• GET /api/v2/chg/{chgId}/offer/{offerId}
• GET /api/v2/chg/{chgId}/merchant/{merchantId}/offers
• GET /api/v2/chg/{chgId}/merchant/{merchantId}/offer/{offerId}

Offers can describe cashback, branded balance, or both. Reward rates use basis points. Money thresholds use minor units.

Activation records the cardholder intent to participate with a merchant. The cardholder usually activates from a specific offer presentation, but Percents stores the activation at the merchant level for that cardholder group.

• GET /api/v2/chg/{chgId}/merchant/{merchantId}/activation returns current activation state.
• PUT /api/v2/chg/{chgId}/merchant/{merchantId}/activation activates a merchant for the cardholder group.

When an activation request includes presentedOfferId, that offer is the offer through which the cardholder activated. The resulting activation remains valid for the merchant even after that underlying offer ends. Future eligible offers for the same merchant can use the existing merchant activation unless the cardholder group or merchant activation is deactivated.

Activation does not by itself create cashback or branded balance. Rewards are created only when an ingested transaction qualifies and the resulting event is posted.

Earn eligibility is based on merchant activation, active offers, cardholder group state, merchant rules, and transaction attributes. Spend eligibility is based on merchant, cardholder group, available branded balance, merchant rules, and availability timing.

Use:

• GET /api/v2/chg/{chgId}/merchant/{merchantId}/eligibility
• GET /api/v2/chg/{chgId}/merchant/{merchantId}/spend-eligibility

Common spend restriction reasons include no available balance, merchant minimums, issuer minimum availability delay, and merchant minimum availability delay.

Percents may expand spendRestrictionReasons over time and will provide notice before adding public enum values.