docs
/
AI skills

Store credit, reward points and wallets

Give customers store credit and reward points, let products earn points or be bought with them, set what a point is worth, spend credit and points at checkout or the till, adjust a balance with a reason, turn points into a gift card, gift them from an automation, and read every movement in the ledger. Store credit and points are spent, never paid out.

Each customer has one wallet (wallet, owner = the customer record). It holds three separate balances (appengine finance/customer-wallet-rules.ts, customer-wallet.service.ts):

BalanceFieldCan be spentCan be paid out
EarningsbalanceNoYes, see Payouts
Store creditstoreCreditAt checkout and the tillNever
Reward pointsrewardPointsAt checkout and the till, at the redemption rateNever

Every change to store credit or points is one wallet_transaction line, with a reason, the balance after, and a key that stops it happening twice. A balance never goes below zero. A frozen wallet can't change.

Ledger reasons: return_refund, order_payment, order_refund, earned, redeemed, converted_to_giftcard, adjustment, reversal, promotion.

Where credit and points come from, and the page that covers each:

SourcePage
A refund or return settled to store credit or pointsRefund, cancel or return an order
A store_credit or reward_points discount, credited when the order is paidDiscount codes
Points earned by products (step 2)this page
Staff adjustments (step 3)this page
An automation (step 7)this page

Ask first

  • Which customer? Their email. Read their balances back before changing anything.
  • Store credit or points? And how much. Points are whole numbers.
  • Why? Every adjustment needs a reason. It stays on the ledger, and the customer can see the line.
  • What is a point worth? The default is 100 points = 1.00.
  • Which products earn points, and how many? Which can be bought with points, and for how many?

Steps

1. Settings: what a point is worth

rewardPoints.redemptionRate on the business settings (Studio Settings at /settings, record base-setting; sdk setting.ts 519, "Points per 1.00 when spent"). Default 100, smallest 1.

Points spent are worth points ÷ rate, rounded down to the cent. Points needed for an amount are rounded up.

Stop: this changes what every customer's points are worth. Show the old and new rate.

Check: a customer's points show the new value in their wallet (step 3).

2. Products: earn points, or pay with points

On the product (and on each variation, which overrides it; sdk sf-product.ts):

FieldOn screenWhat it does
rewardPointsContributionReward points earnedPoints per unit, given when the order is fully paid.
rewardPointsPricePrice in reward pointsLets the product be bought with points: the shopper ticks Pay with N points on the product page (base-app PayWithPoints.tsx), and the line goes in the cart with payWithPoints: true.

Earning (earnForOrder, customer-wallet.service.ts 387):

  • happens once, when the order becomes paid or overpaid (checkout, a payment staff record later, or the till);
  • counts rewardPointsContribution × quantity on each line;
  • skips gift card lines, refund lines and lines paid with points;
  • skips rentals.

A refund takes the earned points (and any promotion gift) back in proportion to what was refunded, and all of it when the order is cancelled (reverseForOrder, 448). It never takes more than the customer has left: points already spent stay spent.

Tested: a line with payWithPoints on a product with no points price is refused: "… cannot be bought with points."

Hands on: the product SKU. Check: after a test order is paid, the customer's ledger shows an earned line keyed earn:<order number>.

3. Finance › Wallets: open a wallet and adjust it

Studio: Finance (/finance), tab Wallets. Open a customer's wallet finds or opens one. Opening the wallet (/finance?openWallet=<sk>) shows store credit and points, "Spent at checkout or the till; never paid out", and the buttons Adjust store credit, Adjust reward points and Convert points to a gift card (websitemint wallet-credit-points.tsx).

With call_appengine (all staff only, finance/customer-wallet.controller.ts):

CallBodyWhat it does
GET finance/customer-wallets/lookup?customerId=<customer sk>found: false until one is opened (tested).
POST finance/customer-wallets/open{ customerId }Finds or opens the wallet.
GET finance/customer-wallets/<walletId>Balances, and what the points are worth.
POST finance/customer-wallets/<walletId>/adjust{ balanceType: store_credit | reward_points, change, reason, operationKey? }change is signed: +25 adds, −25 takes away.
GET finance/customer-wallets/<walletId>/ledger?balanceType=Every movement, newest first.

Stop: an adjustment changes what the customer can spend. Show the customer, the balance, the change and the reason, and wait for yes.

Send an operationKey (for example adjust:<customer>:<date>:<what>). The same key again changes nothing and answers replayed: true (tested).

Tested refusals:

  • no reason: "Say why the balance is being adjusted."
  • half a point: "Reward points are whole numbers."
  • taking away more than there is: "Only 25.00 store credit is available."

Tested: +1,550 points showed as worth $15.50 at 100 a dollar.

Hands on: the wallet id. Check: the ledger shows the line with reason adjustment, the balance after and who made it. The customer sees it as "Adjusted by the store".

4. Checkout: spend credit and points

A signed-in customer with a balance sees Store credit & points at checkout, with Use store credit, Use reward points and Apply (base-app CheckoutStoreCredit.tsx). The screen says: "Nothing comes off your store credit or points until you place the order."

The quote (POST storefront/discounts/calculate) and the order take wallet: { storeCredit: "max" | <amount>, points: "max" | <points> }. Store credit is used first, then points (allocate). Tested: $25 credit and 1,550 points, both max, took $40.50 off.

A shopper who isn't signed in gets no wallet. A staff member's own session is never the buyer's wallet (storefront.order.service.ts 1971): for an order taken for a customer, spend at the till (step 5) and pay with gateway wallet; see Phone order for a customer.

When an order paid this way is refunded or cancelled, the store credit and points go back to the wallet.

Check: the order's payments include the wallet, and the ledger shows order_payment / redeemed lines with the order number.

5. Point of sale: spend at the till

POST finance/customer-wallets/spend with { customerId or walletId, balanceType, amount (store credit) or points, reference, idempotencyKey }. The key is 8 to 160 characters. It answers a transactionNumber. Settle the till's tab with gateway wallet and that number.

Tested: $5 of store credit gave a transaction number, and sending the same key again spent nothing more. 50 points paid $0.50.

Stop: the spend comes off the customer's balance at once.

Check: the ledger line, with the till's reference.

6. Convert points to a gift card

Convert points to a gift card in the wallet, or POST finance/customer-wallets/<walletId>/convert with { points, operationKey? }. The customer can do it themselves from their account (POST client/finance/rewards/convert).

It takes the points off, issues an active digital gift card for their value (booked as given away), and emails it to the customer. If the card can't be issued, the points are put back. See Gift cards. (Code only, not tested.)

Stop: this emails the customer a gift card code. Show the points, the card value and the email.

Check: the ledger line converted_to_giftcard references the gift card serial.

7. Automations: gift credit or points

The automation action Gift Reward Points / Store Credit (gift_wallet_reward, appengine automation/actions/gift-wallet-reward.action.ts) takes { balanceType: reward_points | store_credit, amount, reason }. It gives to the order's customer, or to the customer behind a customer, contact or lead record, once per run and record. It is recorded as a promotion. Build it with create_automation; see Automation when a record changes.

Stop: turning it on gives value to every customer it matches. Show the trigger and the amount.

Check: a test run gives one promotion line, and a second run of the same record gives nothing more.

8. The customer's view

My Account › Store credit (base-app my-account/StoreCredit.tsx, GET client/finance/rewards) shows the balances, what the points are worth, the history and a convert button. See Customer account portal.

Asked to cash it out

Store credit and points can only be spent. A payout asks for earnings only. Tested: a wallet with only store credit was refused: "Only 0.00 of earnings can be paid out. Store credit and reward points can only be spent…" Give the money back as a refund on the original order instead, if the owner agrees.

When it's done

  • The balance reads what the owner asked for, with a ledger line and a reason for each change.
  • Products that should earn or cost points have the fields, and a test order shows it.
  • Checkout offers credit and points to signed-in customers with a balance.

What it can't do yet

  • No store-wide "points per dollar spent": points come only from the product fields, discounts, adjustments and automations.
  • Rentals don't earn points.
  • No expiry on store credit or points.
  • A wallet can be deleted while it still holds store credit or points; the delete check looks only at earnings (wallet-delete-check.ts 8–15). Don't delete a customer's wallet.

Don'ts

  • Don't adjust a balance without a reason and a yes.
  • Don't adjust without an operationKey: a retry could add it twice.
  • Don't promise a customer cash for store credit or points.
  • Don't change the redemption rate without telling the owner it changes every balance's worth.
  • Don't delete a wallet.