Shopify Integration

Tapidu for Shopify connects Shopify orders to the same loyalty account customers use in store.

Use it when a store wants customers to earn Tapidu points from fulfilled Shopify orders, preview earning potential on the storefront, and keep online activity visible beside NFC, QR, and reward activity.

What It Does

• Connects one Shopify store to one Tapidu store.
• Awards points when eligible Shopify orders are fulfilled.
• Reverses awarded points when a synced order is cancelled or refunded.
• Matches customers by email address.
• Keeps a guest point balance by email when the shopper does not yet have a Tapidu app account.
• Shows estimated points on product and cart pages through Shopify theme blocks.
• Lets signed-in Shopify customers claim eligible online/global Tapidu rewards from the cart.
• Adds a cart drawer embed so customers can see points and claimable rewards before they go straight to checkout.
• Adds customer account reward surfaces for points, active claims, and available online rewards.
• Creates one-use Shopify discount codes for claimed Tapidu rewards.
• Keeps point earning rules in the Tapidu Shopify app instead of duplicating them in each theme block.
• Lets merchants set default Tapidu block colours and text size from the Shopify app setup page.
• Logs recent Shopify webhook deliveries in the setup page so store teams can confirm whether Shopify sent an event.
• Sends Shopify order activity back to Tapidu so customers and staff can see it in Tapidu activity views.

Shopify reward claims work from the cart, cart drawer, and customer account reward surfaces for signed-in customers.

Before You Start

You need:

• A Tapidu store created in admin.
• Access to that store’s Integrations tab in Tapidu admin.
• A Shopify store where the Tapidu app is installed.
• Permission in Shopify to manage apps and theme blocks.
• Shopify app proxy configured for /apps/tapidu/rewards when using cart or classic customer-account theme blocks.
• A customer email on Shopify orders, because Tapidu matches customers by email.

Customers are matched by email address. If the Shopify email already belongs to a Tapidu app account, points attach to that account immediately. If not, Tapidu keeps a guest balance for that email so the customer can later attach the points by signing up in the app with the same email.

Setup Overview

There are two sides to configure:

1. Tapidu admin generates the store code and API access key.
2. Shopify stores that connection and the point earning rules.

The basic flow is:

1. Open the store in Tapidu admin.
2. Go to the store Integrations tab.
3. Generate or copy the shared Commerce API access key.
4. Open Shopify admin and open the Tapidu app.
5. Paste the Tapidu store code and API access key.
6. Configure order earning rules.
7. Save the Tapidu Shopify settings.
8. Add the Tapidu product/cart points blocks from Shopify’s theme editor.
9. If the store uses new customer accounts, add the Tapidu customer rewards UI extension from the customer account editor.
10. Enable the Tapidu cart drawer app embed if the theme uses a slide-out cart.
11. Sign in as a Shopify customer, open the cart, cart drawer, or customer account rewards page, and test reward claiming.
12. Fulfil a test order and confirm it appears in Recent webhook deliveries.

Shopify App Setup

In Shopify admin, open the Tapidu app.

Fill in:

• Tapidu store code
• Tapidu Commerce API key
• Award Tapidu points for Shopify orders
• Points per currency unit spent
• Flat points per order
• Minimum order subtotal
• Product point rules
• Collection/category rules
• Storefront primary colour
• Storefront text colour
• Storefront surface colour
• Storefront block text size

Leave the API key field blank when saving later if you want to keep the existing saved key. The same Commerce API key can be used by supported ecommerce integrations for that Tapidu store.

Tapidu connection endpoints are loaded automatically. Store owners do not need to paste technical platform URLs.

The storefront appearance settings are published with the earning rules so product, cart, and account blocks can share one brand treatment.

The setup page also includes:

• a non-destructive Tapidu connection test
• remote config status, including whether the app is using remote config or bundled fallback config
• endpoint readiness checks for order points and reward claims
• a storefront checklist for theme blocks and customer account extensions

For hosted production, Tapidu stores Shopify app sessions, shop settings, discount mappings, webhook delivery logs, and privacy request logs in server-side Supabase storage. Local JSON files are only a development fallback.

Order Earning

Tapidu awards Shopify order points when Shopify marks the order as fulfilled.

This is intentional. It avoids awarding points too early for orders that are paid but not completed yet.

Points are calculated from Shopify’s discounted merchandise subtotal, before tax and shipping. If the customer used a Tapidu reward or another Shopify discount, they earn from the amount they actually paid for the products.

Recommended starting setup:

Award Tapidu points for Shopify orders: on
Flat points per order: 0
Points per currency unit spent: 1
Minimum order subtotal: 0

If the order is cancelled or refunded after points were awarded, Tapidu reverses the original Shopify award for that order.

Product Rules

Product rules let a store fine-tune earning for specific products.

Add one rule per line:

COFFEE-SKU = bonus:5
123456789 = fixed:20
Gift card = exclude:0

Rule types:

• bonus: adds extra points per quantity on top of spend-based points.
• fixed: uses a fixed number of points per quantity instead of spend-based points.
• exclude: gives no points for the matched product.

Rules can match:

• Shopify product ID
• Shopify variant ID
• SKU
• exact product title

Collection/category rules are captured in the setup page for a later collection-based earning pass. Product rules are the reliable option during the current beta.

Storefront Point Previews

The Shopify theme app extension includes:

• Tapidu product points
• Tapidu cart points
• Tapidu account rewards
• Tapidu cart drawer

Add these blocks from Shopify’s theme editor.

The blocks use the earning rules saved in the Tapidu Shopify app:

• points per currency unit
• flat points per order
• minimum subtotal
• product point rules

Theme editor settings are only for display choices, such as:

• whether the block is shown
• title
• description
• badge label
• fallback colours before the Tapidu app settings have been saved

If the storefront preview does not update after changing settings, save the Tapidu Shopify settings again, then refresh the theme preview.

Default colours and text size are managed from the Tapidu Shopify app setup page. Save that page after changing appearance settings so Shopify publishes the latest values to the theme blocks.

For slide-out carts, enable the Tapidu cart drawer app embed from the theme editor’s App embeds area. It inserts the compact Tapidu panel before the cart drawer subtotal or checkout controls. If a custom theme uses unusual drawer markup, set the embed’s custom drawer selector and subtotal/checkout selector.

Customer Account Rewards

Shopify has two customer account experiences, so Tapidu supports both.

Classic Customer Accounts

Stores using classic theme customer account pages can add the Tapidu account rewards block from Shopify’s theme editor.

The block shows:

• the customer’s Tapidu points for this store
• active one-hour reward claims
• eligible online/global rewards
• claim, apply, and cancel actions

The block uses the same signed app proxy as the cart block, so the customer must be signed in and the Shopify app proxy must be configured.

New Customer Accounts

Stores using Shopify’s new customer accounts should add Tapidu customer rewards for a dedicated rewards page, or Tapidu profile rewards for a compact Profile page block. Shopify requires these to be separate extensions.

The extension reads Tapidu’s public Shopify integration JSON by default and falls back to the hosted Tapidu Shopify app. Production stores should not need to paste any Supabase, function, app, or customer-account URLs.

The new customer account extension uses Shopify session tokens rather than the storefront app proxy. It shows:

• the customer’s Tapidu points for this store
• active one-hour reward claims
• eligible online/global rewards
• claim and cancel actions

Customers can use the generated TAPIDU- code at checkout. If they cancel the claim or the one-hour timer expires, Tapidu returns the points to their account.

Cart Reward Claims

The Tapidu cart block can show eligible online and global rewards for signed-in Shopify customers.

When a customer claims a reward:

1. Tapidu reserves the points for one hour.
2. Shopify creates a one-use discount code using the same TAPIDU- claim code.
3. The customer is sent back to the cart with the discount ready for checkout.
4. When the fulfilled-order webhook arrives, Tapidu marks the claim as applied.

If the customer cancels the claim before checkout, or the claim expires, Tapidu returns the points to the customer account.

Tapidu reward discounts are created as non-stacking, one-use codes.

Customer Experience

Customers can see estimated points on product and cart pages when the store adds the Tapidu theme blocks.

After a fulfilled Shopify order syncs:

• the customer’s Tapidu balance increases
• the activity appears as Shopify order activity
• registered customers can receive a push notification if notifications are enabled
• guest Shopify customers keep points under their email until they create a Tapidu app account with the same email
• signed-in customers can claim eligible cart or customer-account rewards when they have enough points

Testing

Use this test flow:

1. Save the Tapidu Shopify setup page.
2. Place a Shopify test order with a customer email.
3. Fulfil the order.
4. Refresh the Tapidu Shopify setup page.
5. Check Recent webhook deliveries.
6. Confirm the customer’s Tapidu points increased.
7. Claim an eligible reward as a signed-in Shopify customer from the cart or customer account rewards page.
8. Complete checkout and fulfil the order.
9. Confirm the Tapidu claim is marked applied.
10. Refund or cancel the fulfilled order.
11. Confirm the original Shopify points are reversed.

Recent webhook deliveries can show:

• synced: Tapidu accepted the event.
• skipped: Shopify sent the event, but Tapidu did not need to change points.
• failed: Shopify sent the event, but Tapidu rejected it or the connection settings need attention.

Troubleshooting

No points after a test order

Check:

• The order was fulfilled, not just paid.
• Award Tapidu points for Shopify orders is enabled.
• The order has a customer email.
• The Tapidu store code and API key are saved.
• Recent webhook deliveries shows orders/fulfilled.
• The order subtotal is above the minimum subtotal.
• Product rules do not exclude the purchased product.

Refund did not return points

Check:

• The original order earned points before the refund.
• Recent webhook deliveries shows refunds/create.
• The refund belongs to the same Shopify order that earned the original points.

If no original award exists, Tapidu skips the reversal instead of creating a negative balance from an order it never awarded.

Storefront blocks show old point values

Save the Tapidu Shopify settings page again. The storefront blocks read the latest storefront-safe earning settings published by the Tapidu app.

If the block still looks wrong, remove and re-add the Tapidu block in Shopify’s theme editor, then refresh the theme preview.

Connection test fails

Check:

• Tapidu store code is copied from the correct store.
• Commerce API key is generated from the same store Integrations tab.
• The store is active in Tapidu admin.
• Remote config shows both order points and reward claim endpoints as ready.
• The app is not using an old local tunnel URL after deployment.

Cart or customer account rewards do not load

Check:

• The Shopify customer is signed in.
• The customer account has an email address.
• For cart and classic account blocks, the app proxy points /apps/tapidu/rewards to the Tapidu Shopify app.
• For new customer accounts, Shopify network access is approved for the hosted Tapidu Shopify app domain.
• The Tapidu store code and Commerce API key are saved.
• The customer has points at this Tapidu store.
• The reward tier is active and has channel Online or Global.

Shopify app says protected order data is required

Shopify protects order and customer data. The Tapidu Shopify app needs the appropriate Shopify permission before order and refund events can sync.

For development stores, the app owner should enable the required protected customer data access in Shopify Partner Dashboard, then reinstall the app in Shopify admin.

For live stores, this access is part of Shopify’s app review process.

Customer account rewards fail in production

Check that Shopify network access is approved for customer account UI extensions and that Tapidu public config exposes the hosted Shopify app URL.

Security Notes

• Treat the Tapidu API key like a password.
• Rotate the API key in Tapidu admin if it is exposed.
• Customer matching uses email address.
• Tapidu points are loyalty points, not cash or store credit.
• Shopify reward discount codes are one-use and expire with the Tapidu claim.