Skip to main content

General Integration Flow

This section outlines the standard end-to-end integration flow for implementing Loyalty API. It defines the sequence of API calls required to manage member identity, apply benefits, process transactions, and handle loyalty-related operations.

The diagram below shows the core steps in a typical loyalty transaction flow:​

  1. The member is identified using their phone number or registered if new.
  2. The transaction (basket) is prepared with items, prices, and metadata.
  3. Benefits are optionally previewed in real time using the transaction data.
  4. Loyalty payment is applied using points, credits, or redeemable assets.
  5. The transaction is submitted to finalize the sale and trigger loyalty processing.

1. Member Identification​

Existing Members​

  • Use the /member/details endpoint to fetch member status, profile, balances, and available benefits.
  • To retrieve benefit calculation results, include a transaction in the request body and set the x-return-benefits: true header.

New Members​

  • Use the /member/register endpoint to enroll a new member with the necessary contact and consent fields.
  • If needed, verify the member using /member/shortCode through a secure one-time code.

Updating Member Information​

  • Use /member/update to modify member details such as communication preferences or profile information.

2. Transaction Setup​

  • Prepare the basket using the transaction object structure.
  • Define all purchased items with required metadata such as department information, gross and net amounts, and tags.
  • This data may optionally be sent to /member/details to calculate real-time benefits before finalizing the transaction.

3. Loyalty Payment (Optional)​

  • Use the /payment endpoint with action: "pay" to apply points or credit to the purchase.
  • The payment object must include the amount. The type of asset (e.g., points or credit) is determined automatically based on business' configuration.
  • If applicable, loyalty assets (e.g., gifts) can be included using the usedAssets array.

4. Submit Transaction​

  • Finalize the transaction using the /transaction endpoint.
  • This ensures the loyalty engine processes:
    • Points awarding
    • Segmentation logic
    • Asset consumption
    • Promotion tracking
info

This step is mandatory regardless of member identification to maintain consistent reporting and analytics.

5. Cancellations and Post-Transaction Events​

Cancel Payment​

  • To reverse a loyalty payment, use /payment with action: "cancel" and provide the original confirmationCode.

Cancel Transaction​

  • To cancel a submitted transaction, re-send the same structure to /transaction using the original transactionId.

External Events​

  • Use the /event endpoint to log behavioral or milestone events, such as app usage or referrals.
  • Events are associated with members and can trigger automated campaigns or segmentation logic.

Integration Sequence Summary​

StepEndpointRequiredNotes
Member Verification/member/detailsYesAlways used if member is identified
Member Registration/member/registerNoUsed for first-time member creation
Benefit Preview/member/detailsNoRequires transaction object and x-return-benefits
Loyalty Payment/paymentNoOptional partial or full redemption
Submit Transaction/transactionYesLogs the sale and triggers loyalty engine
Cancel Payment/paymentNoRequires confirmationCode from original payment
Cancel Transaction/transactionNoUse same transactionId to indicate cancellation
External Event Logging/eventNoFor behavioral triggers and marketing segmentation

Best Practices​

  • Use HTTPS and include all required headers for each request.
  • Ensure transactionId is unique per transaction and idempotent.
  • Match total payment amount with the transaction’s totalAmount.
  • Avoid sending null or empty fields in member or payment objects.
  • Consistently apply department codes and tags for analytics and rule targeting.

By following this structure, your application ensures a secure, consistent, and real-time integration with the loyalty infrastructure, allowing for accurate benefit evaluation, behavior tracking, and customer engagement.