Custom SDK

The Tapidu SDK is a private TypeScript package for custom commerce integrations.

Use it when a store is not using the Tapidu WooCommerce plugin or Shopify app, but still needs Tapidu points, online reward claims, and order activity in the same loyalty account.

The package currently lives inside the Tapidu monorepo at plugins/npm/tapidu.

What It Helps With

• Show estimated Tapidu points on product, cart, or checkout pages.
• Calculate points from discounted merchandise subtotals.
• Format point labels consistently.
• Detect TAPIDU- reward claim codes.
• Filter available rewards down to the ones the current customer can claim.
• Show pending claim countdown labels.
• Generate stable idempotency keys for award and reversal events.
• Let a custom backend list online/global rewards for an authenticated customer.
• Create and cancel pending reward claims.
• Apply a reward claim after checkout.
• Award points for accepted orders.
• Reverse points after refunds or cancellations.

Store Setup

Each custom integration still needs a Tapidu store and a store API access key.

In Tapidu admin:

1. Open the store.
2. Open the commerce/integrations area.
3. Generate or copy the store API access key.
4. Keep the key in the custom backend environment.
5. Never expose the key in frontend JavaScript.

Browser Usage

Browser code should only display estimated points or call a merchant-owned backend proxy.

It must not call Tapidu platform functions directly with the store API key.

Example frontend responsibilities:

• calculate an estimated point preview
• show available rewards returned by the backend
• send a claim request to the backend

Server Usage

The backend owns the secure work:

• authenticate the customer
• verify the customer email
• call Tapidu with the store API key
• use stable idempotency keys for order awards and reversals
• apply reward claims only when the order is genuinely accepted

Reward Claims

Custom integrations should follow the same claim lifecycle as WooCommerce and Shopify:

1. Customer chooses an eligible online or global reward.
2. Tapidu creates a short-lived TAPIDU- claim code.
3. The custom checkout reserves or applies that claim.
4. If the claim expires or is cancelled before use, Tapidu returns the points to the customer.
5. Applied claims appear in Tapidu activity.

Points should not be treated as automatic money balance. Customers spend points by claiming a reward tier.

Order Points

Award points from the final eligible merchandise subtotal after discounts.

Do not award points for tax, shipping, or refunded amounts unless the store has a deliberate rule for that.

If an order is cancelled or refunded after points were awarded, send a reversal for the original awarded points. Use the same order identifier and a stable reversal idempotency key.

Current Status

The SDK scaffold builds ESM, CommonJS, and TypeScript declarations. It is private until Tapidu is ready to publish it as a public package.

Run the package checks from the monorepo:

cd plugins/npm/tapidu
npm run check