Integration Checklist

Use this checklist before starting implementation and again before launch. It helps align the retailer, Loyal Guru, and any middleware or agency team on identity, data, runtime behavior, campaign scope, observability, and rollback.

1. Define the integration scope

Decision	Confirm
Channels in scope	POS, e-commerce, app, kiosk, middleware, WL App SDK, or CRM.
Runtime model	Promo Engine, Coupon Server, or legacy Coupon Server.
Calculation owner	Loyal Guru calculates final effects, or the external system calculates final price after Loyal Guru validates eligibility.
Environments	Sandbox, staging, production, base URLs, and Company configuration.
Launch type	New launch, migration from legacy, phased rollout, or pilot by store/channel.

2. Prepare access and environments

• Request Runtime API credentials: X-Api-Key, X-Api-Secret, and X-Api-Version. See API Keys.
• Confirm who has Owner App access for campaign setup and validation.
• Confirm sandbox test data and production cutover date.
• Define API credential rotation and secret storage ownership.
• Review HTTP behavior, authentication, idempotency, and errors in HTTP API.

3. Align Customer identity

• Choose the Customer identifier used across channels.
• Decide how POS, e-commerce, app, and CRM will create or update Customers.
• Define duplicate handling: update, merge, soft association, household, or card renewal.
• Require OTP or equivalent verification before merging accounts based on email or phone.
• Confirm how Customer consent fields are collected and updated.

See Customer Data.

4. Sync Company Data

Data	Required checks
Products	IDs, codes, taxonomy, categories, prices if needed by local pricing logic.
Locations	Store IDs, store codes, country, operational status.
Cart events	Historical load, ongoing cart events, cancellation or return behavior.
Attributes and audiences	Fields used by campaigns and personalization must be populated before campaign tests.

See Company Data. Endpoint schemas are in the OpenAPI endpoint catalog.

5. Configure campaigns and evaluation model

• Create sandbox campaigns in the Owner App.
• Confirm whether discounts, points, rewards, vouchers, games, and challenges are in scope.
• Confirm apply_discounts behavior for the Company and per-request override.
• Define coupon and voucher lifecycle: selection, validation, redemption, rollback, and expiration.
• Agree on campaign test cases: eligible Customer, ineligible Customer, expired campaign, wrong store, wrong product, duplicate coupon use.

6. Build runtime requests

• Use POST /carts/simulate for previews that should not persist state.
• Use POST /carts/realtime only when the purchase is confirmed.
• Send stable cart IDs and idempotency keys for retryable confirmed requests.
• Include Customer, location, country, payment method, lines, totals, and desired coupons/vouchers when relevant.
• Log request IDs, cart IDs, Customer IDs, response effects, and business outcome.

7. Apply and reconcile effects

• Map each returned effect to cart line or cart total behavior.
• Display coupon/voucher feedback to the Customer.
• Confirm points or wallet feedback when visible at checkout.
• Reconcile POS/e-commerce totals against Loyal Guru reporting.
• Define cancellation and rollback behavior for failed payments, returns, and order edits.

8. Configure webhooks when needed

• Decide which external systems need outbound events.
• Create webhook connectors and actions in Webhooks & Connectors.
• Choose No Auth or JWT; use JWT for production integrations.
• Make the destination endpoint idempotent and able to handle retries.
• Use Webhook Logs to verify delivery.

See Webhooks.

9. Test before launch

Test area	Examples
Authentication	Missing credentials, wrong credentials, expired/rotated secret.
Customer identity	Existing Customer, new Customer, duplicate Customer, merged Customer, card renewal.
Cart evaluation	Eligible cart, ineligible cart, coupon cart, store/product restrictions, payment method restriction.
Resilience	Network timeout, retry with Idempotency-Key, duplicate cart ID, provider outage.
Webhooks	Success, failure, retry, invalid JWT, duplicate event handling.
Reconciliation	Cart totals, discounts, points, voucher status, webhook logs, external system state.

10. Launch and monitor

• Launch with a small store/channel/customer cohort when possible.
• Monitor API errors, cart response effects, webhook logs, and business KPIs.
• Keep rollback procedures ready for campaign deactivation, API credential rotation, and POS fallback.
• Review the first production day with Loyal Guru and the retailer's technical owner.

Troubleshooting

Symptom	What to check
No effects returned	Campaign active state, date window, Customer eligibility, product/location scope, coupon code, apply_discounts.
Duplicate benefits	Idempotency, cart ID reuse, retry handling, voucher redemption state.
Customer benefits split across accounts	Customer ID mapping, merge flow, association vs household model.
POS and Loyal Guru totals differ	Promo Engine vs Coupon Server model, local pricing rules, tax/rounding, line mapping.
Webhook not received	Connector status, action configuration, destination URL, JWT validation, logs, retries.