WooCommerce Integration

The Tapidu plugin connects online orders, checkout rewards, and in-store loyalty activity into one customer history.

Use it when a store wants customers to earn points from online purchases, spend Tapidu rewards during checkout, and keep WooCommerce activity visible in Tapidu admin and the mobile app.

What It Does

• Syncs Tapidu point balances into WooCommerce customer accounts.
• Shows point previews on product pages, cart, and checkout.
• Shows claimable checkout rewards in the cart before falling back to estimated points earned.
• Shows the customer's current store balance and online reward availability in WooCommerce My Account.
• Shows points earned and rewards used on WooCommerce My Account order details.
• Lets merchants adjust the colours of customer-facing Tapidu storefront sections with a live preview.
• Awards points for eligible WooCommerce orders using discounted merchandise subtotals.
• Supports order-level, spend-based, product-level, and variation-level point rules.
• Reverses awarded points when a synced order is cancelled or refunded.
• Lets customers claim eligible checkout rewards from WooCommerce My Account.
• Accepts TAPIDU- reward claim codes through the normal WooCommerce coupon field.
• Shows Tapidu sync status, breakdowns, errors, and retry actions on WooCommerce orders.
• Sends online order and reward activity back to Tapidu so it appears in admin reporting and the mobile app.

Before You Start

You need:

• A Tapidu store created in admin.
• Access to that store’s Integrations tab in Tapidu admin.
• WooCommerce installed and active.
• The Tapidu plugin installed and active in WordPress.
• A customer account in WooCommerce with a reachable email address.

Customers are matched by email address. If the WooCommerce email already exists in Tapidu, points attach to the app account immediately. If not, Tapidu keeps a WooCommerce guest balance for that email so the customer can claim online rewards and later attach the remaining balance by signing up in the app with the same email.

Setup Overview

There are two sides to configure:

1. Tapidu admin stores the WooCommerce connection details for the store.
2. WordPress stores the Tapidu API access key and plugin earning rules.

The basic copy-and-paste flow is:

1. Open the store in Tapidu admin.
2. Go to the store Integrations tab.
3. Generate a WooCommerce API access key.
4. Open WordPress admin, then go to Tapidu in the dashboard sidebar.
5. Paste the Tapidu store code and API access key into the plugin.
6. Copy the WooCommerce sync URL from the plugin.
7. Paste the WooCommerce sync URL back into Tapidu admin.
8. Save both screens.
9. Run a test tap and a test order.

Tapidu Admin Setup

In Tapidu admin, open the store that owns the WooCommerce shop.

Use the store Integrations tab to find or configure:

• Store code
• WooCommerce sync URL
• WooCommerce API access key
• Integration status

The API access key is used in both directions:

• Tapidu uses it to send point-balance updates to WooCommerce.
• WooCommerce uses it to send online order awards, reversals, and claim-code events back to Tapidu.

Treat the API access key like a password. If it is exposed, rotate it in Tapidu admin and update the plugin settings.

WordPress Plugin Setup

In WordPress admin, go to Tapidu in the dashboard sidebar.

Quick Setup

Fill in:

• Store code from Tapidu
• API access key

Tapidu platform endpoints are loaded automatically. Store owners do not need to paste platform URLs or function endpoints.

The plugin also shows a WooCommerce sync URL. Copy that URL into Tapidu admin.

The sync URL usually looks like:

https://example.com/wp-json/tapidu/v1/points/sync

Opening this URL in a browser returns an unauthorized response. Detailed setup checks and actual point sync require authenticated requests using the Tapidu API access key.

The plugin settings page also includes a Support tab with common setup checks, details to include when asking for help, and quick fixes for reward, earning, and checkout-code issues.

Platform Endpoint Config

The plugin loads its outbound endpoint config from Tapidu. By default it requests:

https://admin.tapidu.com/integrations/woocommerce.json

If the remote config cannot be reached, the plugin uses its bundled fallback config and any optional constants defined in wp-config.php.

Reward Checkout Codes

Tapidu points are not store credit and are not converted directly into money. Customers use points by claiming an eligible Tapidu reward. Online and global reward claims generate a TAPIDU- code that can be pasted into the normal WooCommerce coupon field.

Settings:

• Allow Tapidu reward claim codes in the WooCommerce coupon field
• Show claimable rewards in the cart
• Show claimable rewards at checkout
• Configure online/global rewards in Tapidu admin
• Use fixed or percentage reward discount types for WooCommerce checkout

Reward Claim Codes

Tapidu reward claims can be configured in admin as:

• In-store only
• Online only
• In-store + online

Online and global claims can be used in WooCommerce checkout. In-store-only claims should be processed from the Tapidu admin Checkout page.

Tapidu points are not money or store credit. A customer must claim an eligible reward before a checkout discount exists.

The customer flow is:

1. Customer opens the Tapidu app.
2. Customer claims an online or global reward in the Tapidu app or WooCommerce My Account.
3. Tapidu shows a TAPIDU- claim code. WooCommerce My Account can apply it to the current cart automatically.
4. Customer can also enter the code manually in the WooCommerce coupon field.
5. Plugin validates the code with Tapidu.
6. WooCommerce applies a virtual coupon.
7. When the order is paid or processed, the plugin marks the claim as applied in Tapidu.

The plugin only checks Tapidu for coupon codes that start with TAPIDU. Normal WooCommerce coupons remain local to WooCommerce. Tapidu virtual coupons are individual-use and should not stack with other coupons.

Claim validation checks:

• Code format
• Store ownership
• Claim status
• Claim expiry
• Online/global channel
• Customer ownership by checkout email

If a customer removes the Tapidu coupon from the cart, the plugin clears the stored claim session for that cart.

Pending checkout claims expire after one hour. Customers can cancel an unused pending claim from WooCommerce My Account. In both cases, Tapidu returns the points spent on that claim to the customer's account; an expired or cancelled checkout code does not burn points. The plugin removes that code from the current cart when possible.

My Account Loyalty Panel

Signed-in customers see a Tapidu loyalty panel in WooCommerce My Account.

The panel shows:

• Their current synced point balance for this connected store.
• Online and in-store + online rewards available from this store.
• Which rewards are ready now and how many more points are needed for locked rewards.
• Active pending checkout codes, their one-hour expiry countdown, copy action, and cancel action.
• Clear reassurance that expired or cancelled pending checkout claims return the spent points.

Customers can claim eligible checkout rewards directly in WooCommerce My Account or use a code generated in the Tapidu app.

Customer Order Details

WooCommerce My Account order detail pages include a Tapidu loyalty summary when the order earned points or used a Tapidu reward.

Customers can see:

• Points earned for the order.
• Point breakdown.
• Whether points were added, reversed after cancellation/refund, waiting to sync, or calculated but not yet confirmed by Tapidu.
• Tapidu reward claim codes used on that order.

Order Earning Rules

Enable Calculate Tapidu points for WooCommerce orders when the store is ready to award online purchase points.

Main settings:

• Only registered WooCommerce customers can earn order points
• Flat points per order
• Points per currency unit spent
• Minimum order subtotal
• Eligible WooCommerce order statuses

Recommended starting setup:

Only registered customers: on
Flat points per order: 0
Points per currency unit spent: 1
Minimum order subtotal: 0
Award when order reaches: Completed

For stores that fulfil before payment capture, include Processing only if the store understands that points may be awarded earlier.

Product And Variation Rules

The plugin adds a Tapidu tab to the WooCommerce product editor.

Product earning behavior:

• Inherit global order rule
• Add bonus points per unit
• Use fixed points per unit
• No points for this product

Use cases:

• Inherit for normal products.
• Bonus for short campaigns or high-margin items.
• Fixed for bundles, gift boxes, or products where spend-based points are not ideal.
• No points for excluded products, fees, samples, or restricted items.

For variable products, variation-level settings can override the parent product. This is useful when one size, color, package, or subscription option should earn differently.

The WooCommerce product list includes a Tapidu points column so store owners can review configured product rules quickly.

Customer-Facing Cart Prompts

When a signed-in customer has a ready online/global reward, the cart and checkout prompt them to claim a checkout code first. If no checkout reward is currently claimable, the same area falls back to the estimated Tapidu points they will earn from the order.

If a Tapidu reward code is applied, the estimate updates to show the points earned after discounts. A fully discounted order can earn zero spend-based points.

Store owners can control the customer-facing display independently:

• Show claimable rewards in the cart
• Show claimable rewards at checkout
• Show estimated points in the cart
• Show estimated points at checkout

All four display options are enabled by default. If reward prompts and point previews are both enabled, claimable rewards take priority and include the estimated after-discount points inside the prompt.

When order earning is enabled, customers can see estimated Tapidu points:

• On product pages
• In the cart
• During checkout

If Only registered WooCommerce customers can earn order points is enabled, guest customers will not see eligible earning previews.

These previews are estimates. The final award is calculated from the order when it reaches an eligible status.

Tapidu storefront assets load only on product, cart, checkout, and My Account pages. Unrelated pages do not receive the Tapidu frontend stylesheet or scripts.

Order Sync And Reversals

When an order reaches an eligible status, the plugin:

1. Calculates the award.
2. Saves the point breakdown on the order.
3. Sends the award to Tapidu.
4. Records the sync status in the Tapidu loyalty order box.

The payload includes:

• Order ID and order number
• Customer email
• Currency, discounted subtotal, and original subtotal
• Award cycle
• Source
• Point breakdown for base, spend, product bonus, fixed product points, and per-item details

If a confirmed-synced order is later cancelled or refunded, the plugin sends a reversal to Tapidu with negative points.

Important: reversals are only sent automatically when the original award was successfully synced. If the award never reached Tapidu, there is nothing to reverse.

WooCommerce Order Metabox

Each WooCommerce order has a Tapidu loyalty box.

Use it to check:

• Points awarded
• Sync status
• Last sync error
• Point breakdown
• Claim-code status
• Retry award sync
• Retry reversal sync

Retry buttons run without leaving the order page.

Testing Checklist

After setup, test in this order:

1. Open the WooCommerce sync URL in a browser and confirm it returns JSON.
2. In Tapidu admin, save the store integration with the sync URL and API key.
3. In WordPress, save the plugin with the same store code and API key.
4. Tap a TapiCube or add points in Tapidu admin for a customer who also exists in WooCommerce.
5. Confirm the customer’s WooCommerce point balance updates.
6. Enable WooCommerce order earning.
7. Place a small test order as a registered WooCommerce customer.
8. Move the order to an eligible status.
9. Confirm the order metabox shows a successful Tapidu sync.
10. Confirm the Tapidu mobile app Activity screen shows the online order with the store name.
11. Cancel or refund the order and confirm the reversal appears in Tapidu.
12. Claim an online reward in WooCommerce My Account and confirm the code is applied to the cart.
13. Cancel a pending claim before checkout and confirm the points return.
14. Claim an online reward in the app and use the TAPIDU- code in checkout.

Troubleshooting

Sync URL Returns 404

Check that:

• The plugin is active.
• WordPress permalinks are enabled.
• WooCommerce is active.
• The URL uses /wp-json/tapidu/v1/points/sync.

Re-save WordPress permalinks if needed.

Point Sync Returns Unauthorized

The API access key does not match.

Check:

• Tapidu admin store integration key
• Plugin API access key
• Any TAPIDU_SYNC_SECRET constant in wp-config.php

If unsure, rotate the key in Tapidu admin and paste the new value into WordPress.

WooCommerce Guest Balance

If the WooCommerce email does not match an existing Tapidu app account, Tapidu stores order points in a WooCommerce guest balance for that email instead of failing the sync.

Check:

• WooCommerce billing email
• WooCommerce user email
• Whether the customer has already registered in the Tapidu app with the same email

Customers can use eligible online rewards from the WooCommerce guest balance. Remaining points attach to the app account when they later sign up with the same email.

Orders Calculate Points But Do Not Sync

Check:

• Calculate Tapidu points for WooCommerce orders is enabled.
• Tapidu platform endpoint config can be loaded.
• API access key is set.
• Store code is set.
• The order reached an eligible status.
• The order has a billing email.
• The Tapidu loyalty order box last error.

Tapidu Claim Code Does Not Work

Check:

• Code starts with TAPIDU-.
• Claim is online or global, not in-store only.
• Claim has not expired.
• Claim is still pending.
• Checkout billing email matches the Tapidu customer that owns the claim.
• Allow Tapidu reward claim codes in the WooCommerce coupon field is enabled.
• The code is not being combined with another coupon.

Expired or cancelled checkout claims cannot be used, but the points spent on them are returned to the customer's Tapidu account automatically.

Refund Did Not Remove Points

Check:

• The original award sync was successful.
• The order status is Cancelled or Refunded.
• The order metabox does not already show a reversal.
• The reversal retry button if the first reversal failed.

Operational Notes

• Keep the first earning rules simple while the store is testing.
• Prefer registered WooCommerce customers for online point awards.
• Use online-only reward tiers for ecommerce-specific discounts.
• Use global reward tiers only when the same reward can safely be redeemed in-store and online.
• Review Tapidu admin Activity after test orders to confirm store names and point sources are clear.