Documentation

RedeemWise has four moving parts: a discount function, the storefront box (two cart blocks and a cart drawer embed), three Flow actions, and a reconciliation job that runs on order webhooks. This page covers how they fit together.

Setup order

1. Install the app. The points metafield definition is created for you.
2. Open Settings and choose your exchange rate, minimum redemption and at least one eligible collection. Nothing applies until an eligible collection is set. Redemption uses your store's currency.
3. Create the redemption discount from the setup checklist. This is a deliberate button rather than something that happens on install, so you can see what was created.
4. In the theme editor, open the cart template and add the Points redemption block to the section that holds your subtotal and checkout button — just above the checkout button is where customers decide.
5. If your store opens a cart drawer, switch on Points redemption in cart drawer under Theme settings → App embeds and save. The setup checklist links straight to it. It places the redemption box just above the drawer's checkout button on any theme, including the many whose drawer cannot hold app blocks.
6. Wire Credit Points into whatever Flow already awards your points.
7. If you have existing balances elsewhere, run the one-time import from Settings.

Wiring the Flow action

Your earning rules stay yours. A typical workflow ends with our action instead of an Update customer metafield step:

Order paid
  └─ Run code            (your rules: XP, rates, tiers, whatever)
       └─ [RedeemWise] Credit Points
            customer  →  the order's customer
            points    →  the number your code returned

Credit Points adds to the balance. Debit Points removes from it, clamping at zero — use it for support corrections and clawbacks, not for redemption spending, which the app deducts itself. Set Points Balance writes an absolute value; it is the right tool for reconciling against an external system and the wrong tool for routine earning, because it will clobber a concurrent credit.

Migrating existing balances

A discount function's input query fixes its metafield namespace at build time, so RedeemWise cannot read an arbitrary per-shop namespace at runtime. It owns its own balance metafield instead, and Settings offers a one-time bulk import from whatever namespace and key you use today.

After the import, RedeemWise's metafield is authoritative. Switch your Flow to the Credit Points action in the same maintenance window, or the two will drift.

How the discount decides

On every cart calculation the function applies a discount only if all of these hold, and silently applies nothing otherwise:

1. The customer is logged in. Guests cannot redeem.
2. No discount code is on the cart — unless you turned that rule off.
3. The requested amount is at least your configured minimum.
4. The requested amount is within the customer's balance.
5. At least one cart line is in an eligible collection and in no excluded one.
6. The cart's presentment currency is your store's currency.
7. After capping to the eligible subtotal, the discount is still at least the minimum.
8. Your store has an active plan — see Plan and pricing.

The function is the source of truth. The storefront blocks mirror these rules for good UX, but a bad value getting through the UI results in no discount, not a wrong one.

Storefront contract

If you are building your own cart UI instead of using our blocks, this is the entire interface:

• Cart attribute key: _redeemwise_redeem
• Value: the number of points, as a string. Empty string clears it.
• Write it with POST /cart/update.js and { attributes: { _redeemwise_redeem: "500" } }, then re-render your cart totals.
• The balance is the customer metafield RedeemWise points balance (key balance, in RedeemWise's reserved app namespace — the definition under Settings → Custom data → Customers shows it in full). It is readable on the storefront, including through the Storefront API.
• The redemption rules are stored as RedeemWise's own app data, which only RedeemWise's blocks can read. A custom UI should use the rate, minimum and step you set in Settings.

How spending is reconciled

Nothing moves when the discount is applied — a cart is not a sale. When the order is placed (orders/create), RedeemWise re-reads it, confirms its own discount is actually on it, and reserves exactly the points that discount was worth, taking them from the balance. When the order is paid (orders/paid), the reservation is confirmed and the balance does not move again. If the function declined, or capped the amount to a smaller eligible subtotal, the customer is charged only for what was actually applied.

Reserving at checkout matters for payment methods that settle later, such as cash on delivery: otherwise the same points could be spent again on further orders before the first is paid. If you would rather leave the balance untouched until payment, Settings lets you take points when the order is paid instead. The points are thenheld: they stay in the balance, but the customer cannot spend them on another order until the first is paid (they are taken) or cancelled (they are released).

Each order can be deducted once. The audit record is keyed on the order ID with a uniqueness constraint, so repeated webhook deliveries — which are normal — cannot double-charge.

Refunds and cancellations

• Cancelled order — the full redemption is credited back.
• Refunds follow the items. Points are spent on the eligible items in the cart, so a refund is judged on those items only. Shipping, tax and products outside your eligible collections never make a refund partial and never return points.
• Every discounted item refunded — the full redemption is credited back, whether or not shipping was refunded.
• Some of them refunded — your choice. Points stay spent (default) leaves them spent. Credit back the refunded share returns the share of the points that the refunded items carried: refund one of three identical items and a third comes back.
• Order placed but never paid — the points stay reserved until the order is cancelled, which returns them. These orders are marked Reserved on the Redemptions page so you can find them. If you take points at payment instead, nothing is taken until the order is paid, but the points stay held and the customer cannot spend them. These orders are marked Awaiting payment, with how long they have waited. Cancel refused or abandoned orders to release their points.
• Balance couldn't cover the redemption — this can happen with two checkouts at the same moment, or when the balance is lowered while an order waits for payment. The customer keeps the discount, the balance stops at 0, and the Redemptions page marks the order with the points that were missing. A later cancellation or refund credits back only the points that were actually taken.

Plan and pricing

RedeemWise has one plan, Standard: $5 a month after a 7-day free trial, with every feature included. Each billing cycle includes 50 redemptions, and each one after that is billed through Shopify at $0.05. Redemption never pauses because of volume.

There is no free plan. The first time you open RedeemWise, it takes you to Shopify's plan page. Until a plan is active, the discount does not apply and the cart blocks show customers a notice instead of the redemption control. Balances are never affected.

A redemption counts once its order is paid, and one that is fully credited back does not count. The Plan section on the RedeemWise home page shows how many of this billing cycle's included redemptions have been used, as Shopify counts them, and links to the plan page.

Languages

The cart blocks come in English, Greek, German, French, Spanish and Italian, and follow the language your storefront is shown in. Any other language falls back to English. The balance label in Settings replaces the word "points" in every language; the heading is set separately.

Known limitations

• Checkout discount line. At checkout the discount is labelled with your heading from Settings, or "Points redemption" if you have not set one — the same text in every language. In your Discounts list the discount itself is always called "RedeemWise points redemption", and there is only ever one: changing the heading relabels it, it does not create another.
• B2B buyers. Customers buying for a company can't redeem points: the box isn't shown and the discount doesn't apply to a company's cart. A company location set to submit orders for review turns checkout into a draft order, which Shopify recalculates without the cart's redemption request, so the discount would disappear before the order is placed. RedeemWise can't tell which locations work that way, so this applies to all B2B buyers.
• Multi-currency. Redemption uses your store's currency. Carts in other currencies show an explanatory message instead of a discount. Conversion is not supported.
• Post-purchase order edits. If eligible items are removed from an order after it was paid, the redemption is not recalculated.
• Cart drawers. The cart drawer embed finds the drawer's checkout button and places itself just above it. After every change the box reads the cart back from Shopify and says what it actually got — for example "200 points applied (2.00 EUR off)", or that the points are not applied — so customers see the truth on any theme. Whether the drawer's own totals update in place depends on the theme: Dawn and Horizon do; on themes that do not, the totals catch up on the next page and at checkout, and the drawer stays open meanwhile. If the box lands somewhere awkward on your theme, enter a CSS selector in the embed's Placement setting and it goes just before that element instead. Theme developers can add an element with data-redeemwise-mount to place it exactly.
• Previewing the box. It only appears for a logged-in customer with a balance, so the theme editor preview shows nothing. To see it, log in to your store as a customer who has points.

Support

dev@mal-vi.com — include your shop domain and, if it is about a specific redemption, the order number.