{"templateId":"markdown","versions":[{"version":"2.0","label":"v2.0","link":"/percents-api/branded-rewards/reward-lifecycle","default":true,"active":true,"folderId":"27d36c3a"}],"sharedDataIds":{"sidebar":"sidebar-sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":[]},"type":"markdown"},"seo":{"title":"Reward Lifecycle","llmstxt":{"hide":false,"sections":[{"title":"Table of contents","includeFiles":["**/*"],"excludeFiles":[]}],"excludeFiles":[]}},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"reward-lifecycle","__idx":0},"children":["Reward Lifecycle"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Branded balance and cashback can be earned by the same transaction, but they remain separate products in API responses and reconciliation."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"branded-balance","__idx":1},"children":["Branded Balance"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Branded balance is merchant-scoped. A cardholder can spend a branded balance only with the merchant that created it and only after the balance is available."]},{"$$mdtype":"Tag","name":"Diagram","attributes":{"data-language":"mermaid","diagramType":"mermaid","diagramSource":"stateDiagram-v2\n [*] --> EarnedUnavailable: Qualifying Settlement/Refund\n EarnedUnavailable --> Available: availableAt reached\n Available --> Available: partial eligible merchant spend\n Available --> Spent: full eligible merchant spend\n EarnedUnavailable --> ClawedBack: reversal\n Available --> ClawedBack: unspent balance reversal\n Available --> Expired: remaining balance expires\n Spent --> ClawedBack: spent balance reversal\n","diagramHtml":"

Qualifying Settlement/Refund

availableAt reached

partial eligible merchant spend

full eligible merchant spend

reversal

unspent balance reversal

remaining balance expires

spent balance reversal

EarnedUnavailable

Available

Spent

ClawedBack

Expired

","diagramHtmlDark":"

Qualifying Settlement/Refund

availableAt reached

partial eligible merchant spend

full eligible merchant spend

reversal

unspent balance reversal

remaining balance expires

spent balance reversal

EarnedUnavailable

Available

Spent

ClawedBack

Expired

"},"children":["stateDiagram-v2\n [*] --> EarnedUnavailable: Qualifying Settlement/Refund\n EarnedUnavailable --> Available: availableAt reached\n Available --> Available: partial eligible merchant spend\n Available --> Spent: full eligible merchant spend\n EarnedUnavailable --> ClawedBack: reversal\n Available --> ClawedBack: unspent balance reversal\n Available --> Expired: remaining balance expires\n Spent --> ClawedBack: spent balance reversal\n"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"em","attributes":{},"children":["Visual Brand Reward Lifecycle"]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"rewardgrant-buckets","__idx":2},"children":["RewardGrant Buckets"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Each branded balance earn creates or updates RewardGrant buckets. RewardGrant data is exposed so integrators can audit availability, expiry, and partial consumption."]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Bucket"},"children":["Bucket"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Meaning"},"children":["Meaning"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["originalAmountMinor"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Original earned amount."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["earnedUnavailableAmountMinor"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Earned value that cannot be spent yet."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["availableAmountMinor"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Value currently eligible to spend, subject to merchant rules."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["spentAmountMinor"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Value already consumed."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["clawedBackAmountMinor"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Value reversed by a clawback."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["expiredAmountMinor"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Value expired before spend."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["remainingAmountMinor"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Unspent, unclawed, unexpired value remaining in the grant."]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"availability-timing","__idx":3},"children":["Availability Timing"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Earned branded balance can be held unavailable for a configured availability delay before it is spend eligible. The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["availableAt"]}," timestamp is the time when the earned value becomes eligible to spend, assuming the grant has not expired, been spent, or been clawed back."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Two minimum-availability controls can apply:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Issuer minimum availability delay: the issuer can require branded balance to remain unavailable for a global minimum amount of time after earn."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Merchant minimum availability delay: a merchant can require its branded balance to remain unavailable for a merchant-specific minimum amount of time after earn."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["When both controls apply, the greater delay wins. For example, if the issuer minimum is ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["2"]}," days and the merchant minimum is ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["5"]}," days, the grant uses the merchant delay and becomes available after ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["5"]}," days. If the issuer minimum is ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["7"]}," days and the merchant minimum is ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["3"]}," days, the grant uses the issuer delay and becomes available after ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["7"]}," days."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The issuer minimum availability delay also controls whether the issuer is floating branded balance value before receiving payout to cover that value. If branded balance becomes available before the periodic payout that funds the earned value, the issuer is effectively covering that float. If the issuer minimum availability delay is the same length as, or longer than, the periodic payout window, branded balance does not become spendable before the covering payout is expected, so availability timing does not create issuer float."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The API exposes the resulting ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["availableAt"]}," timestamp on RewardGrant data. Eligibility responses can include ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["issuer_delay_not_satisfied"]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["merchant_delay_not_satisfied"]}," when the relevant minimum availability delay has not elapsed."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["expiresAt"]}," timestamp appears when the grant expires. A grant can be partial when only some value remains or only some value was consumed."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"spend-remaining-balance-and-clawbacks","__idx":4},"children":["Spend, Remaining Balance, and Clawbacks"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["An available branded balance can be partially spent. After a partial spend, the RewardGrant can still have ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["remainingAmountMinor"]},", and that remaining unspent balance can still expire or be clawed back later. A full spend moves the grant into a fully consumed state, but the spent amount remains auditable and can still be reversed by a spent-balance clawback."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["There are two clawback paths:"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Clawback path"},"children":["Clawback path"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Issuer handling"},"children":["Issuer handling"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Unspent balance clawback"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Preferred path. Percents prioritizes clawing back unspent available balance before reversing previously spent balance. No cardholder-level account action is required from the issuer because the cardholder has not received an statement credit for the unspent branded balance."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Spent balance clawback"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Used when there is no unspent balance available to claw back. Percents does not support negative branded balances, so this requires the issuer to post a statement debit against the cardholder account to reverse the earlier branded balance statement credit."]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If one reversal spans both cases, process the unspent balance clawback first and apply cardholder account action only for the spent portion that cannot be covered by remaining unspent branded balance."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"cashback","__idx":5},"children":["Cashback"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Cashback appears in the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["cashback"]}," section of reward summaries. Cashback does not become merchant-scoped branded balance and should not be added to merchant balance totals."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"cardholder-statement-credits","__idx":6},"children":["Cardholder statement Credits"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["When branded balance is spent, the issuer should represent the posted branded balance spend as an statement credit on the cardholder account in the issuer platform. The credit should be tied back to the corresponding transaction, reward event, and webhook so support and reconciliation workflows can explain why the statement credit was created."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"issuer-commissions","__idx":7},"children":["Issuer Commissions"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Cardholder rewards are the consumer-facing amounts shown as branded balance and cashback. Issuer commissions are separate records that may be created from the same qualifying activity when supported by the program."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Public reconciliation uses the related source events, reward events, and RewardGrant buckets."]}]},"headings":[{"value":"Reward Lifecycle","id":"reward-lifecycle","depth":1},{"value":"Branded Balance","id":"branded-balance","depth":2},{"value":"RewardGrant Buckets","id":"rewardgrant-buckets","depth":2},{"value":"Availability Timing","id":"availability-timing","depth":2},{"value":"Spend, Remaining Balance, and Clawbacks","id":"spend-remaining-balance-and-clawbacks","depth":2},{"value":"Cashback","id":"cashback","depth":2},{"value":"Cardholder statement Credits","id":"cardholder-statement-credits","depth":2},{"value":"Issuer Commissions","id":"issuer-commissions","depth":2}],"frontmatter":{"seo":{"title":"Reward Lifecycle"}},"lastModified":"2026-07-21T18:22:26.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/percents-api/branded-rewards/reward-lifecycle","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}