Cardholders need to know both which merchant rewards they can earn and whether an existing balance is ready to spend. Use general and targeted offers to present the terms, activation to enable earning when required, and spend eligibility to check available merchant value.
Earning a new reward and spending an existing balance are separate checks. A purchase can spend branded balance without earning a new reward.
General offers provide broadly available baseline terms. Once registration or lazy provisioning gives you a cardholder group ID, use targeted offers to show the same or better terms for that customer.
Read GET /api/v2/offers and select rewardProductType: branded_balance. General offers are available before the cardholder group exists. The Offers guide explains live and scheduled offers and pagination.
To read one definition, use GET /api/v2/offer/{offerId}. The current definition includes the earn rate, restrictions and configured availability and expiry periods. It does not evaluate a customer.
Once registration or lazy provisioning creates the cardholder group, GET /api/v2/chg/{chgId}/offers returns targeted offers for it. These can include offers omitted from general discovery, with the same or better terms for that customer than the general baseline. To see one merchant's live offers and the group's qualification and activation, call:
GET <env-host>/api/v2/chg/{chgId}/merchant/{merchantId}/eligibility?scope=brandedThe required scope=branded selects branded rewards. Each live offer includes chgQualified and activated. The eligibility response explains the values. Branded scope also includes canSpend for the existing balance. Earning still requires a qualifying purchase, while spending depends on available balance and merchant rules.
ONE_TIME offers use merchant activation at participating merchants. Confirm support before presenting the activation action.
GET /api/v2/chg/{chgId}/merchant/{merchantId}/activation returns branded merchant activation state. PUT /api/v2/chg/{chgId}/merchant/{merchantId}/activation records activation for the group. Use this route for ONE_TIME offers. VIEW and CLICK branded offers use the user activity stream.
curl --fail-with-body -X PUT 'https://sandbox.percents.com/api/v2/chg/chg_22222222-2222-4222-8222-222222222222/merchant/mp_55555555-5555-4555-8555-555555555555/activation' \
-H 'Authorization: token tok_11111111-1111-4111-8111-111111111111:api_test_secret' \
-H 'Content-Type: application/json' \
--data-binary @- <<'JSON'
{
"presentedOfferId": "mpo_bbbbbbbb-bbbb-4bbb-8bbb-bbbbbbbbbbbb",
"idempotencyKey": "branded-activation-001"
}
JSONThe example uses a separate sample branded offer. Replace presentedOfferId with an actual enabled branded offer returned for that merchant. Activation applies to the merchant for the cardholder group. It can remain valid after the presented branded offer ends and apply to future eligible branded offers unless the group or activation is deactivated. Activation does not itself earn or spend value.
Only branded balance is spendable at its participating merchant. Check GET /api/v2/chg/{chgId}/merchant/{merchantId}/spend-eligibility and the merchant balance before presenting spendable value:
curl --fail-with-body -X GET 'https://sandbox.percents.com/api/v2/chg/chg_22222222-2222-4222-8222-222222222222/merchant/mp_55555555-5555-4555-8555-555555555555/spend-eligibility' \
-H 'Authorization: token tok_11111111-1111-4111-8111-111111111111:api_test_secret'Branded merchants expose minBalanceRequiredForSpend in minor currency units. Its default is 100 ($1 USD), but the configured value varies by merchant. Compare it with available balance, not net balance: with a minimum of 100, available balance of 99 is insufficient even if more value has been earned but is unavailable.
Spending does not require earning a new reward. Lack of available balance, an unmet minBalanceRequiredForSpend or issuer or merchant availability delays that have not elapsed can prevent spending. The greater applicable minimum delay governs. Handle restriction reasons explicitly and tolerate additional public values.
Qualifying purchases earn value restricted to that merchant. Later eligible purchases can spend an available balance. See the branded lifecycle for more details.
Use the eligibility lookup across merchants with scope=branded to check branded offers across all merchants for a cardholder group in one call.