Documentation

RedeemWise has four moving parts: a discount function, two storefront blocks, 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, currency, and at least one eligible collection. Nothing applies until an eligible collection is set.
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. Add the Points redemption block to your cart page, and the drawer variant to your cart drawer, in the theme editor.
5. Wire Credit Points into whatever Flow already awards your points.
6. 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 matches your configured currency.
7. After capping to the eligible subtotal, the discount is still at least the minimum.

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.
• Read the rules from the shop metafield $app.storefront_config and the balance from the customer metafield $app.balance.

How spending is reconciled

Nothing is deducted when the discount is applied — a cart is not a sale. On orders/paid, RedeemWise re-reads the order, confirms its own discount is actually on it, and deducts exactly the points that discount was worth. If the function declined, or capped the amount to a smaller eligible subtotal, the customer is charged only for what was actually applied.

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.
• Full refund — the full redemption is credited back.
• Partial refund — your choice. No credit-back (default) leaves the points spent, on the reasoning that they were spent on the order rather than on an item. Pro-rata returns the same share of the redemption as the share of the order value refunded.
• Payment fails after the order is created — nothing is deducted; only paid orders are.

Known limitations

• Multi-currency. One configured currency per shop. 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. An app block needs a host section that accepts app blocks. Most cart pages do; some themes' cart drawers do not, and those need a one-line theme edit to accept them.

Support

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