Integration Tutorial

This tutorial walks through a typical Loyal Guru integration for POS, e-commerce, app, kiosk, or middleware teams. It starts with the minimum setup data, then sends a cart simulation, confirms a cart, and optionally listens to outbound webhooks.

Use this tutorial after the Quickstart when you are ready to connect the flow end to end.

Tutorial flow

Step 1 - Prepare setup data

Create or confirm the data that campaign rules need:

Data	Example endpoint
Customer	POST /customers or GET /customers/{value}
Product	POST /products or PATCH /products/{id}
Location	POST /locations or PATCH /locations/{value}

For this tutorial, assume:

• Customer ID: 123456
• Product ID: 10045
• Product code: SKU-10045
• Location ID: 1001
• Country: ES

Use the OpenAPI endpoint catalog for schemas and field definitions.

Step 2 - Configure a campaign

In the Owner App, create a sandbox campaign that is easy to validate:

1. Create a discount campaign in the current Loyalty and Promotional Engine.
2. Set a simple eligibility rule, for example product 10045 or cart total greater than 40.
3. Set the effect, for example 10% discount.
4. Activate the campaign in sandbox.
5. Confirm the integration model:
   • Promo Engine: Loyal Guru calculates and returns discount effects.
   • Coupon Server: Loyal Guru validates eligibility; the external system calculates final price.

This tutorial uses Promo Engine mode with apply_discounts: true.

Step 3 - Simulate the cart

Use simulation first so the checkout can preview benefits without persisting the transaction.

curl --request POST 'https://streaming.loyal.guru/carts/simulate' \
  --header 'X-Api-Key: YOUR_API_KEY' \
  --header 'X-Api-Secret: YOUR_API_SECRET' \
  --header 'X-Api-Version: 1' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "id": 20260717002,
    "customer_id": 123456,
    "apply_discounts": true,
    "country": "ES",
    "location_id": 1001,
    "payment_method": "card",
    "total": 45.00,
    "lines": [
      {
        "product_id": 10045,
        "product_code": "SKU-10045",
        "quantity": 3,
        "unit_price": 15.00,
        "total": 45.00
      }
    ]
  }'

Step 4 - Apply returned effects

Your system should inspect the response and apply each effect according to its scope:

{
  "effects": [
    {
      "rule_id": 101,
      "rule_name": "10% off test campaign",
      "type": "discount",
      "effectType": "percentage",
      "distribution_type": "individual_items",
      "discount_value": 4.5,
      "line": 0
    }
  ],
  "total_discount": 4.5,
  "points_earned": 45
}

Implementation guidance:

• Apply line effects to the referenced line.
• Apply cart-level effects to the cart total.
• Show coupon or voucher feedback if the request used coupons_desired.
• Show points/wallet feedback only if it is part of the checkout experience.
• Keep the original response in logs for support and reconciliation.

Step 5 - Confirm the cart

When the Customer pays and the transaction must be persisted, send the confirmed cart with POST /carts/realtime.

curl --request POST 'https://streaming.loyal.guru/carts/realtime' \
  --header 'X-Api-Key: YOUR_API_KEY' \
  --header 'X-Api-Secret: YOUR_API_SECRET' \
  --header 'X-Api-Version: 1' \
  --header 'Idempotency-Key: 8bcb80d7-4c89-47fe-a4ad-3f667c7e3db7' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "id": 20260717002,
    "customer_id": 123456,
    "apply_discounts": true,
    "country": "ES",
    "location_id": 1001,
    "payment_method": "card",
    "total": 45.00,
    "lines": [
      {
        "product_id": 10045,
        "product_code": "SKU-10045",
        "quantity": 3,
        "unit_price": 15.00,
        "total": 45.00
      }
    ]
  }'

Use the same cart ID only for the same business transaction. Use an idempotency key for safe retries when the same confirmed request may be sent more than once.

Step 6 - Add webhooks when downstream sync is needed

If an external CRM, ESP, fulfillment system, or data platform needs to react to Loyal Guru events, configure a webhook connector.

Typical examples:

• Send Customer create/update/delete events to a CRM.
• Notify an external system when a Customer wins a challenge.
• Trigger downstream processing when a voucher or reward is redeemed.
• Send cart creation events to a data platform.

See Webhooks.

Production readiness

Before launch:

• Run the Integration Checklist.
• Confirm endpoint schemas in API Reference.
• Test sandbox campaigns with eligible and ineligible Customers.
• Test retries, idempotency, duplicate cart IDs, cancellation, and rollback.
• Test webhook success and failure using Webhook Logs.

Troubleshooting

Symptom	What to check
Simulation returns no campaign effects	Campaign status, dates, Customer eligibility, product/location scope, and cart total.
Realtime returns a different result than simulation	Campaign changed between calls, Customer/voucher state changed, or the confirmed payload differs from the simulated payload.
Duplicate cart error	Cart ID was reused for a different transaction, or retry handling is missing Idempotency-Key.
Voucher consumed but payment failed	Run the agreed cancellation or rollback flow and check voucher state.
Webhook delivery failed	Open Webhook Logs, review destination response, JWT validation, payload, attempts, and endpoint availability.