Skip to content
Last updated

Branded reward lifecycle

Earned merchant value may become spendable later and can be reduced by spending, expiry or clawbacks. Use the grant states, timing rules and spending order below to show cardholders what they can use and explain changes to their balance.

Earning and grants

The reward lifecycle covers authorization estimates and the awarded settlement amount. Reward grants represent earned branded value. Each grant records its availability, expiry and amounts spent or removed so your wallet can explain the remaining balance.

Grant amountMeaning
originalAmountMinorOriginal earned amount.
earnedUnavailableAmountMinorEarned value that cannot yet be spent.
availableAmountMinorValue eligible to spend, subject to merchant rules.
spentAmountMinorValue already consumed.
clawedBackAmountMinorValue reversed by a supported branded clawback.
expiredAmountMinorValue that expired before spending.
remainingAmountMinorUnspent, unexpired value remaining after applicable reversals.

A qualifying settlement earns merchant value. It becomes available at its configured availability time and eligible merchant purchases can spend it. Partial spending returns the remainder to available balance. Eligible purchases consume the next-expiring grant first. Earned value can be clawed back before or after availability. Unspent value can expire.

How Spending Branded Balance Changes New Earnings

Branded balance spent on a purchase is deducted from the amount used to calculate new branded rewards. Only value applied to that purchase is deducted. A balance that is merely available does not reduce the earning amount.

For a qualifying $105 purchase with $5 of branded balance applied and a 10% earn rate:

CalculationAmount
Purchase amount$105.00
Branded balance actually spent$5.00
Amount eligible for new rewards$105.00 − $5.00 = $100.00
Earn rate10% (1000 basis points)
New branded reward$100.00 × 10% = $10.00

This example assumes the purchase meets the offer's terms and no earn cap reduces the reward. The $5 spent and the $10 newly earned are separate outcomes.

Settlement Webhook for This Example

The corresponding qualified_settlement reports the $5 spent and the $10 newly earned separately. Amounts use minor units: spend.amountMinor: 500 is $5.00 and reward.amountMinor: 1000 is $10.00. The rate is 1000 basis points (10%), and maxEarnAmountMinor: null means no earn cap applies.

{
  "webhookId": "evt_eeeeeeee-eeee-4eee-8eee-eeeeeeeeeeee",
  "type": "qualified_settlement",
  "data": {
    "source": {
      "externalId": "issuer-txn-105",
      "percentsId": "txn_88888888-8888-4888-8888-888888888888"
    },
    "cardholderGroupId": "chg_22222222-2222-4222-8222-222222222222",
    "reward": {
      "merchantId": "mp_55555555-5555-4555-8555-555555555555",
      "offerId": "mpo_66666666-6666-4666-8666-666666666666",
      "currency": "usd",
      "amountMinor": 1000,
      "maxEarnAmountMinor": null,
      "rewardProductType": "branded_balance",
      "cardholderEarnRate": {
        "kind": "basis_points",
        "basisPoints": 1000
      }
    },
    "spend": {
      "merchantId": "mp_55555555-5555-4555-8555-555555555555",
      "currency": "usd",
      "amountMinor": 500
    }
  }
}

Use data.spend.amountMinor for the $5 customer statement credit and data.reward.amountMinor for the $10 newly earned merchant value. The new reward follows its own availability rules. It is not another statement credit for this purchase. Follow the branded webhook guide for handling these outcomes.

At authorization, Percents estimates new earnings from the authorization amount minus tentative branded spending. At settlement, it calculates the actual reward from the settlement amount minus branded balance actually spent. If either the purchase amount or spending changes, the reward can change too. See earning and spending in webhooks for the fields to use in customer messaging.

Availability and expiry

availableAt is the grant's availability time. Branded value can have a delay between earning and spending:

  • A configured zero delay permits immediate availability, subject to other eligibility rules.
  • Issuer and merchant minimum delays can both apply, and the greater minimum governs.

With a minimum issuer delay of two days and minimum merchant delay of five days, value becomes eligible for spending after five days. Reversals, spending and expiry can still reduce what remains.

Eligibility can report issuer_delay_not_satisfied or merchant_delay_not_satisfied. Do not display unavailable value as spendable. expiresAt, when returned, identifies when the remaining grant expires. A merchant offer's end date and the expiry of already earned branded value are different dates.

Spending

Check spend eligibility. A purchase at the participating merchant can consume available branded balance partially or fully, even when it earns no new reward. Available balance must meet the merchant's minBalanceRequiredForSpend, default 100 ($1 USD), which can vary by merchant. Use available balance, not net balance. Remaining value can still expire or be reversed later.

Eligible branded grants are consumed in order of expiry: the grant that expires soonest is used first. The order in which grants were earned does not determine spending priority.

EventSpending and statement credit
Authorization webhookCan include a tentative data.spend calculation. Authorization does not consume balance, and you must not apply a statement credit from the estimate.
Settlement webhookReports the amount actually consumed in data.spend.amountMinor, even when the purchase earns no new reward. The issuer represents that amount as a statement credit on the customer account.

Tie that account action to the source transaction, reward event and webhook, and deduplicate it. A Percents reward notification does not confirm that your institution completed the statement action.

Authorization time and delayed settlement

Spending uses the purchase's authorization time from the linked authorization or the settlement's authTimestamp. If that time falls within the grant's valid availability and expiry window, the purchase can spend that value even when settlement arrives or is processed after expiry. Send externalAuthId to link an existing authorization, or authTimestamp to supply the time even if the separate authorization event has not arrived. Only when neither provides an authorization time does eligibility use the settlement purchase time, createdAt.

For example, a grant expiring at July 2, 00:00 UTC can fund a purchase authorized on July 1 at 23:50 UTC and settled on July 3. A purchase authorized after expiry cannot spend that grant. Settlement determines the actual consumed amount. An earlier estimate must not create another credit.

Supported branded reversals

When a refund claws back earned value, the webhook reports how much was removed from the cardholder's branded balance and how much becomes an issuer debit because previously spent value could not be clawed back.

That issuer debit may be applied against the issuer's next payment or a later reward earned by the cardholder at the same merchant. Each issuer chooses how to handle its cost: a statement debit, absorbing it, or another approach. We recommend a statement debit but do not require it.

Expiry does not create this shortfall from spent value. For a $2.50 clawback:

Existing valueBalance removedIssuer debit from spent value
$2.50 unspent$2.50$0
$0.50 unspent and $2 already spent$0.50$2
$0.50 unspent and $2 expired$0.50$0

The clawback webhook separates the balance removed from the issuer debit in shortfallAmountMinor. Use the reported outcome and record any chosen customer account action once. Current transaction detail also exposes the issuer debit when one exists.

Read purchase and balance lookup for current outcomes and webhook delivery for signatures and deduplication.