Loyalty Points in a Customer App: When Are They Earned, Held and Spent?

Define the points lifecycle before adding a balance to the customer account. A promised reward, available points and points already committed to a checkout are different things. The app must explain those differences and record the events behind them.

This is planning guidance for a loyalty feature, not a recommendation to subscribe to a particular provider or a promise of more repeat sales. Programme terms, expiry, privacy, consumer rights and accounting treatment need appropriate review. Do not describe promotional points as withdrawable money unless your actual programme supports that meaning and has been reviewed accordingly.

Choose the event that earns points

Does the customer earn points when an order is created, paid, collected or otherwise completed? Pick an event that matches your programme. An unpaid abandoned basket should not become a completed qualifying purchase merely because its estimated points were displayed.

Also define the basis: eligible spend, qualifying visits or particular items. State how discounts, taxes, tips and excluded products affect the calculation. These are business rules, not details the developer should guess from a points-per-purchase label.

Square's official Loyalty API overview distinguishes calculating prospective points from accumulating them in an account. Its calculation operation can show what a buyer would earn while building an order; its accumulation operation adds earned purchase points. That distinction is useful even if you choose a different system. A preview is not a balance change.

Give each balance change a reason

Ask for a history that explains earning, reward commitments, completed redemption, released commitments and manual corrections. Link a purchase-related entry to its order and retain the recorded outcome. If the customer asks why the balance changed, staff should not need to reconstruct it from email.

The Square overview documents a search operation for events that changed the loyalty balance. In a custom app, define the equivalent evidence you need and who may view it. A single editable total is not an adequate explanation of past rewards.

Repeated payment notifications or a retried staff action must not award points twice. Give each intended award an identity and make the points operation safe to retry. If it involves an external provider and the response is uncertain, reconcile the recorded operation with that provider before issuing a new award. Do not treat a missing response as proof that no change occurred.

Reserve a reward separately from spending it

A customer choosing a reward may abandon the checkout. Decide whether selection temporarily commits the required points, how long that commitment lasts and what releases it. The same available points should not support two simultaneous reward claims.

Square offers a concrete lifecycle example. Creating a loyalty reward removes the required points from the available balance and holds them in reserve until redemption or deletion. Its redemption operation permanently removes those points. Deletion applies to an issued but unredeemed reward. These are Square-specific operations, not universal expiry or cancellation rules.

For your app, show what happened in customer language: reward selected, applied to this order, or released back. Specify how a failed payment, cancelled checkout or reopened basket is handled. A button saying “use points” is incomplete without these later outcomes.

Refunds need an explicit programme rule

A returned item may affect points earned from the original purchase and a reward used to buy it. Those are separate questions. Define what is reversed, what is restored, and what happens if the earned points were already spent before the return.

Do not let a points shortage silently block a refund or remedy that the customer is otherwise entitled to. Have the programme terms and customer-rights interaction reviewed. The software should apply that reviewed policy rather than invent a debt or a refusal.

The Square overview says its order integration adjusts loyalty points for refunds depending on programme and refund type. It also describes adding or removing points outside the normal purchase flow through an adjustment operation. That does not establish one universal refund policy or guarantee that every custom integration handles it automatically.

Manual corrections and account mistakes

Limit who can adjust points, require a reason and preserve the before-and-after effect. A correction should be a visible operation, not an unexplained edit that erases earlier activity.

Also decide how a purchase is associated with the intended loyalty account. Do not award another person's points simply because a staff member selected a similar name. Account merging and identity checks need their own reviewed process; transferring a balance is not a harmless spelling correction.

Test the unsuccessful journeys too

Use synthetic accounts for the acceptance tests in a customer-app project:

• An order preview does not award spendable points.
• The qualifying purchase event awards them once, including after a retry.
• Two concurrent checkouts cannot redeem the same available balance twice.
• Abandonment or failed payment follows the agreed reward-release rule.
• A completed redemption remains distinguishable from a temporary commitment.
• Full and partial refunds follow the reviewed earned-points and used-reward policies.
• A manual adjustment has an authorised person, reason and traceable effect.
• Staff can explain a customer's balance from recorded events.

Keep the programme simple enough that customers can understand what they have and what they may use. More reward rules do not compensate for an unexplained balance.

Source boundary

The cited Square overview supports the calculation-versus-accrual distinction, reward reservation and redemption lifecycle, balance-event search and scoped refund/adjustment examples. Retry reconciliation, concurrent-use controls, customer wording and rights safeguards above are requirements to commission and test, not independently verified features of every loyalty provider.