Developer guide · E-commerce
Connect e-commerce orders to loyalty with clear ownership.
Start from the store, payment state, customer identity, and reward experience. Then choose the supported native integration or the API path your team can operate.
- Order owner
- Commerce system
- Loyalty owner
- Reward Loyalty ledger
- Custom path
- Server-side Agent API
Short answer
Choose the store path before the endpoint.
Reward Loyalty supports native integration paths for Shopify and WooCommerce where those early-access features are enabled. A custom store can use server-side Agent API middleware, with a member key for personal reads and a partner key for writes after captured payment. Reward Loyalty does not provide a connector for every commerce product, a WordPress loyalty plugin, or a generic hosted loyalty API.
Decision criteria
Keep order and loyalty ownership explicit.
The store owns payment and order state. Reward Loyalty owns the loyalty ledger. The integration translates committed commerce facts between them.
Commerce product
Use a current native integration only when the store, feature access, and documented order lifecycle match. Use custom middleware for another HTTPS-capable store.
Payment trigger
Choose the store state that proves value is captured and define what a void, cancellation, full refund, or partial refund does to loyalty value.
Customer experience
Decide where members join, inspect balance, choose a reward, receive a code, and get help when commerce and loyalty records disagree.
Supported paths
Choose native integration or custom middleware.
A broad e-commerce label hides material differences in credentials, customer experience, and refund handling.
Shopify
The native integration uses OAuth, signed store webhooks, order and refund processing, and a storefront widget when the feature is enabled and configured.
WooCommerce
The native integration uses store REST credentials, a signed order-update webhook, and single-use coupon creation. It is not a WordPress plugin and does not ship the Shopify widget.
Custom storefront
Use the Agent API from trusted server middleware. The store owns checkout; the middleware reads member state and submits supported loyalty writes.
Brand and source control
White-label relevance: Supporting. Store and loyalty presentation can share a brand, while source changes, custom storefront work, and release maintenance remain the buyer’s responsibility.
Order and identity
Join the records without surrendering payment authority.
A stable mapping is more important than copying the whole order into another database.
Source transaction
The commerce system owns cart, tax, payment, capture, order status, cancellation, refund, and fulfilment.
Native identity
The native paths use the store customer or billing email to find or create the loyalty member under the documented rules. Missing identity can prevent earning.
Custom identity
Resolve a verified member and retain stable Reward Loyalty identifiers. Keep personal wallet access tied to that member rather than a broad partner credential.
Tenant boundary
Native integration settings belong to one business and store. Agent API keys also belong to an owner and enforce their scopes and business boundary.
Loyalty actions
Separate reads, writes, and notifications.
Each direction needs a clear caller and a recovery rule.
Member reads
A member key can read that member’s balance and eligible loyalty data for a custom storefront. Do not send a partner key to the browser.
Purchase writes
After captured payment, trusted server middleware can use the partner key and required scope to record the supported purchase action.
Reward use
Validate the benefit before checkout, apply it in the store, and commit the Reward Loyalty redemption at the documented point. Native coupon flows have their own ordering and expiry rules.
Events and refunds
Native store webhooks drive their documented order lifecycle. Reward Loyalty outbound webhooks can notify other systems after loyalty events. Full and partial refund behavior has current documented limits that require test coverage.
Production controls
Test the ambiguous states before launch.
Commerce retries, API timeouts, and store webhook duplicates can turn a simple points rule into a reconciliation problem.
-
1
Enable and configure one path
Follow the current setup guide, use public HTTPS, store credentials outside client code, and grant only the permissions the integration needs.
-
2
Prove identity and consent
Test a known member, a new customer, guest checkout without usable identity, marketing preferences, and a customer shared across stores or businesses.
-
3
Prove native duplicate handling
The native processors create a webhook receipt and suppress a repeated platform delivery ID before applying the same store event twice. The commerce provider owns its delivery and provider retry policy.
-
4
Exercise the order lifecycle
Test eligible payment, excluded status, duplicate store webhook, cancellation, full refund, partial refund, reward creation, expiry, and a failed downstream call.
-
5
Monitor and reconcile
Native processing can run in the request or use configured queued processing. Monitor queue health only when that mode is enabled, plus receipts, activity records, loyalty transactions, commerce references, and unmatched orders.
Product and operating limits
Publish only the commerce path that exists.
- Shopify and WooCommerce are early-access integrations with separate setup and customer experiences. Confirm current availability and limits in the maintained documentation.
- The native integrations do not imply support for every store, theme, checkout, refund shape, coupon policy, or historical-order backfill.
- Custom Agent API purchase and redemption writes are non-idempotent. The integrator must reconcile an uncertain response before retrying a command.
Implementation guides
Use current documentation for changing details.
Requirements, interfaces, settings, limits, and release behavior belong in the maintained product documentation.