Purchase rewards
What your app shows when a Shopify order pays out, the three rule types, and why a purchase might pay nothing.
A fan buys something in your Shopify store and FanBase pays them for it: points, XP or an item. Nobody is in the loop, and none of it is your code.
How it works
- A community admin connects the store and writes a reward rule in the Hub
- A fan checks out in your Shopify store, the normal way
- Shopify tells FanBase about the order
- FanBase finds the fan by the order's email, checks the order against the rules, and pays what matches
Your app comes in after step 4, to show the fan what they now have.
Steps 1 and 2 happen in the Hub, not in code. Reward rules in the Hub docs walks an admin through connecting the store and writing a rule, field by field.
What you build
One thing: the balance.
import { useSpendableResources } from '@xborglabs/fanbase-react'
function RewardsBalance() {
const { data: rows = [], refetch } = useSpendableResources()
return (
<div>
<ul>
{rows.map((row) => (
<li key={row.resource.resourceTypeId}>
{row.balance} {row.resource.name}
</li>
))}
</ul>
<button type="button" onClick={() => void refetch()}>Refresh</button>
</div>
)
}Each row is { balance, resource }. The number is row.balance. The name, icon and id of the points are one level down, on row.resource.
useSpendableResources works anywhere inside FanbaseProvider, for a signed-in fan. It does not need the store provider around it. XP is separate: read it with useCommunityXP().
The reward arrives a moment later
FanBase pays after Shopify reports the order, which is after checkout. There is no push to your app when it lands. So:
- Call
refetch()when the fan comes back to your page from the store - Say that a reward can take a moment
- Never add the reward to the number yourself
That last one matters. A balance you adjusted by hand is wrong the moment a rule did not match.
The two rules that decide everything
The rule has to exist before the order. FanBase checks an order against the rules once, when it arrives. An order placed before a rule was written is never looked at again. Past orders are not paid.
The checkout email has to be the fan's FanBase email. It is the only thing connecting an order to a fan. Capital letters and stray spaces do not matter. A different address does.
Rule types
Rules are written in the Hub. Knowing what each one matches helps when a fan asks why they were, or were not, paid.
| Rule | Pays when | Notes |
|---|---|---|
| Any purchase | Every order | |
| Tagged purchase | The order contains a product with the tag | Product tags, not order tags. Set to match any one tag, or every tag across the order. |
| Amount spent | Every order, scaled by the total | Rate multiplied by the order total, rounded down, in the store's currency. Pays points only. |
More than one rule can match an order, and each one pays. A rule is recurring unless it is set to pay each fan once.
When a purchase pays nothing
FanBase checks seven things for every order, in this order, and stops at the first that fails. When a fan says they bought something and got nothing, walk down the list.
- OK
- OK
- Stops here
- Not reached
- Not reached
- Not reached
- Not reached
| # | Check | How to tell | Who fixes it |
|---|---|---|---|
| 1 | The store is connected to this community | The Hub shows Shopify as connected | A community admin |
| 2 | The order was a normal checkout | It was not bought with points in the FanBase store | The fan |
| 3 | A FanBase account has the checkout email | Same email on the order and on the fan's profile | The fan |
| 4 | A rule existed when the order arrived | The rule was created before the order | A community admin |
| 5 | The rule matches the order | For a tag rule, the tags on the products in the order | A community admin |
| 6 | The rule has a reward attached | The rule shows its reward in the Hub | A community admin |
| 7 | The reward reached the fan | The balance moved | FanBase support |
Two more reasons, both rarer: a one-time rule that already paid this fan, and an order with no email on it at all.
If all seven look right and nothing was paid, ask your FanBase contact to trace the order.
Things that do not change the outcome
- A refund or cancellation does not take the reward back. Plan campaigns with that in mind.
- An order bought with points never earns. See Spending is not earning.
Testing it
Place a real order in the connected store, through the normal checkout, with the email of a FanBase account. A low-priced product is fine.
Do not test with the SDK's buy button. Store.Purchase spends points. It is the opposite of what you are checking.
Then watch the balance. It moves by the rule's reward, or you can name the step above where it stopped.
For your agent
If an agent is doing the integration, tell it this up front. It is the part agents most often get wrong:
Shopify purchase rewards are paid by FanBase on its own servers, from rules a
person creates in the FanBase admin. There is no SDK function, hook or endpoint
that awards points for a purchase. Do not build a webhook server.
The only code is showing the balance with useSpendableResources() and calling
refetch() when the fan returns from the store.
Store.Purchase spends points. It never earns them.Checklist
- The balance comes from
useSpendableResources, and each row is read asrow.balanceandrow.resource - The balance is refreshed when the fan returns from the store
- The page says a reward can take a moment
- Nothing in your code adds a reward to the balance
- There is no webhook server and no call to an "award" endpoint
- A fan who was not paid can be walked down the seven checks