Shopify

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

  1. A community admin connects the store and writes a reward rule in the Hub
  2. A fan checks out in your Shopify store, the normal way
  3. Shopify tells FanBase about the order
  4. 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.

RulePays whenNotes
Any purchaseEvery order
Tagged purchaseThe order contains a product with the tagProduct tags, not order tags. Set to match any one tag, or every tag across the order.
Amount spentEvery order, scaled by the totalRate 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.

Why did this purchase pay nothing?Try it
  1. OK
  2. OK
  3. Stops here
  4. Not reached
  5. Not reached
  6. Not reached
  7. Not reached
No reward. It stopped at step 3. Who fixes it: The fan: shop with the email they play with.
Press a step to break or fix it. Only the first failure matters: nothing after it is checked.
#CheckHow to tellWho fixes it
1The store is connected to this communityThe Hub shows Shopify as connectedA community admin
2The order was a normal checkoutIt was not bought with points in the FanBase storeThe fan
3A FanBase account has the checkout emailSame email on the order and on the fan's profileThe fan
4A rule existed when the order arrivedThe rule was created before the orderA community admin
5The rule matches the orderFor a tag rule, the tags on the products in the orderA community admin
6The rule has a reward attachedThe rule shows its reward in the HubA community admin
7The reward reached the fanThe balance movedFanBase 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 as row.balance and row.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

On this page