Quickstart

Use this quickstart to validate a first Loyal Guru runtime integration from a POS, e-commerce checkout, app, kiosk, or middleware. The goal is to send a cart to Loyal Guru, let the Promo Engine evaluate it, and apply the returned effects in your system.

What you will learn

• How to prepare API credentials and a sandbox Company.
• How to confirm that Customer and master data are available for evaluation.
• How to configure a simple discount campaign in the Owner App.
• How to send a cart simulation.
• How to read effects[] from the response and apply them in checkout.

Prerequisites

Before starting, make sure you have:

Requirement	Why it matters
Owner App access	Used by the Loyal Guru team or the retailer's loyalty manager to configure campaigns, audiences, coupons, and rewards.
Runtime API credentials	X-Api-Key, X-Api-Secret, and X-Api-Version are required on authenticated API calls. See API Keys.
A sandbox Company	Use a non-production Company while validating payloads and campaign behavior.
A test Customer	The cart should reference the same Customer identity used for vouchers, points, rewards, games, and challenges.
Product and location identifiers	Campaign rules can depend on product, taxonomy, location, country, or store context.

For HTTP behavior, authentication, errors, and idempotency, see HTTP API.

Step 1 - Prepare Customer and master data

The Promo Engine evaluates the cart using Customer state, Company data, and campaign configuration. Before testing checkout, confirm that your integration can send or resolve the data used by rules:

Data	Typical endpoints
Customer identity	POST /customers, GET /customers/{value}, PATCH /customers/{value}
Products	POST /products, PATCH /products/{id}
Locations	POST /locations, PATCH /locations/{value}
Cart history or runtime carts	POST /carts/simulate, POST /carts/realtime

Endpoint schemas are listed in the OpenAPI endpoint catalog.

Step 2 - Configure a test campaign

In the Owner App, create a simple discount campaign for sandbox testing:

1. Create a discount campaign in the current Loyalty and Promotional Engine.
2. Add a clear condition, such as a minimum cart amount, a product condition, or a test coupon code.
3. Configure the effect, for example a percentage or fixed amount discount.
4. Activate the campaign in the sandbox Company.
5. Confirm whether Loyal Guru calculates the discount (apply_discounts: true) or your system calculates it (apply_discounts: false).

For a first quickstart, use apply_discounts: true so Loyal Guru returns calculated effects that your system can apply directly.

Step 3 - Send a cart simulation

Use POST /carts/simulate to preview the result without committing the cart or consuming vouchers. Replace identifiers and amounts with values from your sandbox setup.

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": 20260717001,
    "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
      }
    ],
    "coupons_desired": ["SUMMER10"]
  }'

Use POST /carts/realtime only when the purchase is confirmed and the cart should be persisted.

Step 4 - Read the effects

The most important part of the response is the effects list. It tells your system which benefits Loyal Guru evaluated for this cart.

{
  "effects": [
    {
      "rule_id": 101,
      "type": "discount",
      "effectType": "percentage",
      "distribution_type": "individual_items",
      "discount_value": 4.5,
      "line": 0
    }
  ],
  "total_discount": 4.5,
  "points_earned": 45
}

In this example:

• effects[] contains the applied rule effect.
• discount_value is the calculated discount amount for the referenced line.
• total_discount is the total discount applied to the cart.
• points_earned shows the points or wallet value earned when points evaluation is active.

The exact response depends on Company configuration and enabled modules. Use the cart endpoints reference for endpoint-level details.

Step 5 - Apply the result in your system

After receiving the response:

1. Apply each returned discount effect to the corresponding cart line or total.
2. Show coupon or voucher validation feedback to the Customer when relevant.
3. Show earned points or wallet value if the checkout experience includes loyalty feedback.
4. Keep the same cart ID and use Idempotency-Key for retryable confirmed requests.
5. Use POST /carts/realtime when the transaction is paid and must be persisted.

If the payment fails or the order is cancelled after confirmation, use the cancellation or rollback flow agreed for the integration.

Next steps

Need	Go to
Customer identity, merge, cards, and associations	Customer Data
Products, stores, categories, and taxonomies	Company Data
Discount integration model selection	Loyalty and Promotional Engine
Loyal Guru calculates discount effects	New Engine Promo Engine
POS calculates final prices locally	New Engine Coupon Server
Games and challenges in digital channels	Gamified Campaigns

Troubleshooting

Symptom	What to check
403 Forbidden	Check X-Api-Key, X-Api-Secret, and X-Api-Version.
No discount appears in effects[]	Check campaign activation, date window, Customer eligibility, product/location scope, coupon code, and cart totals.
Coupon is rejected	Check coupons_desired, voucher ownership, status, redemption window, and whether the coupon belongs to the active campaign.
Simulate works but realtime does not	Check idempotency, duplicate cart ID, payment confirmation timing, and whether realtime persistence is enabled for the Company.
POS totals differ from Loyal Guru effects	Confirm whether the integration is using Promo Engine mode (apply_discounts: true) or Coupon Server mode (apply_discounts: false).