Click Below to Get the Code

Browse, clone, and build from real-world templates powered by Harper.
Architecture
GitHub Logo

Promo Code and Reward Redemption

Honor each single-use benefit once, keep eligibility and redemption history together, and extend loyalty experiences without adding another backend stack.
Personalization
Architecture
Personalization

Promo Code and Reward Redemption

Aleks Haugom
Senior Manager of GTM
at Harper
November 16, 2026
Aleks Haugom
Senior Manager of GTM
at Harper
November 16, 2026
Aleks Haugom
Senior Manager of GTM
at Harper
November 16, 2026
November 16, 2026
Connect eligibility checks and recorded claims so rewards stay consistent across customer touchpoints and regions.
Honor each single-use benefit once, keep eligibility and redemption history together, and extend loyalty experiences without adding another backend stack.
Aleks Haugom
Senior Manager of GTM

A customer redeems a reward in an app while the same benefit is presented at checkout. A repeated tap or delayed response can look like another claim. The business needs to honor the reward once and give the customer a clear result, without turning an ordinary retry into either a second discount or an unexplained rejection.

How Harper records one claim for a benefit

This architecture runs redemption handlers and entitlement records on multiple Harper nodes across locations, managed by Harper Fabric. An app and a checkout can reach different nodes, while Harper 5.4 cluster-wide record locks coordinate their competing claims on the same benefit. The application acquires the lock, checks eligibility and expiry, and saves the redemption identity and outcome. A request arriving through another node must use the same coordination path, allowing it to distinguish a new claim from a retry of the original one.

The record key expresses what “once” means. A unique voucher can have one global claim. A reusable campaign code may allow one claim per customer, so the protected record represents that customer's entitlement rather than the shared text of the code. Campaign-wide budgets and limited reward pools introduce additional shared records that must be coordinated with the claim.

When Harper owns the entitlement, it can make the claim decision directly. When an external loyalty or commerce system owns it, that system's redemption API remains authoritative. The application can record a pending claim, send a stable request identity to the fulfillment provider, and reconcile the result before showing the reward as delivered. A saved claim and an externally delivered discount are distinct steps.

One claim, with a tracked fulfillment outcomeOne claim, with a tracked fulfillment outcome. Multi-region · Harper 5.4: App and checkout, Redemption rules, Entitlements and claims, Reward provider. MULTI-REGION · HARPER 5.4App and checkoutRedemption rulesApplication logicEntitlements and claimsReplicated recordsReward providerOne claim, with a tracked fulfillment outcomeMultiple Harper nodes serve different locations. Cluster-wide locks coordinate competing record changes.HARPER FABRICHARPER · REGIONAL NODESCluster lockFulfill + resultRegional request CLIENT COMPUTE DATABASE EXTERNAL IN-PROCESS CALL

Alternatively, use a redemption service and PostgreSQL

A redemption application can use PostgreSQL transactions and unique constraints to enforce the relevant claim identity. It checks the entitlement, records the outcome, and integrates the checkout or reward provider. A unique constraint may be sufficient for simple insert-once claims, while row locks support more involved state transitions. This is a small, credible baseline. Authentication, campaign rules, and external fulfillment recovery are shared responsibilities.

A redemption service with PostgreSQLA redemption service with PostgreSQL. Conventional architecture: App and checkout, Redemption service, PostgreSQL claims, Reward provider. CONVENTIONAL ARCHITECTUREApp and checkoutRedemption servicePostgreSQL claimsReward providerA redemption service with PostgreSQLA redemption service records claims through database transactions and constraints.Redeem / outcomeRow transactionFulfill + result CLIENT COMPUTE DATABASE EXTERNAL

Where a claimed reward is not yet delivered

The claim may be saved before a checkout integration times out. Immediately releasing it could allow another redemption even though the discount was applied. Keeping it pending without recovery frustrates the customer. Both designs need reconciliation. Harper brings eligibility logic and claim records together, reducing backend handoffs while keeping the external provider's outcome separate and visible.

Why Harper matters

  • A useful answer to a repeated request. The application can return the original redemption outcome rather than treating every retry as a new claim.
  • Campaign rules beside entitlement records. Eligibility checks, ownership decisions, and operational state can share Harper.
  • Clearer support investigations. A stable redemption identity connects the customer's claim to the provider's fulfillment result.

Define the claim identity and fulfillment boundary

Use supported RocksDB storage and configured cluster record locking on the Harper 5.4 build. All claim, cancellation, and restoration paths must honor the same protocol. Refuse or retry when the exclusive decision cannot be made. Check expiration using server time and evaluate customer permissions under the application's rules.

Separate single-use vouchers, once-per-customer promotions, and reusable discounts. A code string alone may not identify the protected entitlement. If a claim also consumes a campaign budget or reward inventory, coordinate those records with an appropriate transaction or recoverable reservation workflow. One lock does not enforce several independent limits.

Give each redemption a stable request identity and keep pending outcomes durable. Use the provider's idempotency support where available. Reconcile uncertain fulfillment before restoring a benefit or sending it again. Define refund, cancellation, and fraud-review policies explicitly. Record locking prevents competing participating claims, but does not replace authentication or abuse controls.

Related resources

Start with one reward type

Pilot a single-use entitlement with a clear fulfillment outcome. Redeem it simultaneously through two channels, repeat the original request, and interrupt the provider response after delivery. Verify that the customer receives one benefit and that support can explain every pending case. Track duplicate delivery, rejected valid claims, and reconciliation time. Bring the campaign rules to a Harper architecture discussion.

‍