Cart Events

Cart events are the primary commerce signal in Loyal Guru. Every time a customer completes or previews a checkout, the cart can be sent to the Streaming API to evaluate promotions, award points, redeem cashback, update customer history, and feed analytics.

What Is a Cart Event?

A cart event represents a completed purchase transaction containing:

• Customer identifier — links the transaction to a loyalty member
• Purchase lines — individual products with SKU, quantity, price, and category
• Store / channel — where the purchase took place (in-store POS, online, app)
• Payment method — used for payment-based rule conditions
• Totals — cart total, taxes, discounts applied

How It Triggers Loyalty Rules

When a cart event is received:

1. Discount evaluation — applicable promotional campaigns are evaluated and discounts applied.
2. Points/wallet earning — points campaigns are evaluated against the cart contents and the customer's profile.
3. Challenge progress — any challenge tracking a purchase-based attribute is updated.
4. Instant Win — if an Instant Win campaign is active, it fires for qualifying purchases.
5. Customer history — the cart becomes part of the customer profile, reporting, calculated attributes, and audience conditions.

Streaming API Endpoint

POST /carts
POST /carts/simulate
POST /carts/realtime

The request body includes the full cart contents, customer ID, store or location, payment methods, product lines, additional costs, and any redemptions requested at checkout.

note

Use POST /carts/simulate to preview discounts, points, coupons, and cashback without persisting the cart. Use POST /carts or POST /carts/realtime when checkout is confirmed and effects must be committed.

Finding Purchases in the Owner App

Go to Customers → Events → Carts to search and inspect individual purchases.

Search Filters

Filter	Description
ID	The unique numeric ID of the purchase. Use this for a direct lookup of a single transaction.
Associate ID	An additional ID linked to the purchasing entity (e.g., a loyalty card ID or e-commerce user). Availability depends on company setup.
Locations	Filter by the store or channel where the purchase was made.
Date	Filter by the date the purchase occurred.

Click Search after filling any filter field. Results appear in a table showing ID, code, date, location, and total spend. Click any Customer ID or Location value in the results to navigate directly to the Customers page or Location Details.

Cart Details

Click View next to any result to open the Cart Details page, which shows:

• Total spending, date, and store location
• Line items: each product purchased, linked to its product detail page
• Points breakdown: points earned from this purchase (displays 0 if no active loyalty program)
• Discount and cashback impact when the cart included promotional effects or wallet redemption
• Raw payload for integration debugging

tip

Use the View JSON format button on the Cart Details page to inspect the raw transaction payload — useful for debugging integration issues.

How It Works

1. Your POS or e-commerce system sends the completed transaction to POST /carts or POST /carts/realtime.
2. The Streaming API validates the payload and identifies the customer.
3. Discount evaluation runs first — qualifying promotions are applied and the response includes the adjusted prices.
4. Points campaigns fire based on cart contents, awarding balance to the customer's account.
5. Challenge progress counters update if any active challenge tracks a purchase-based attribute.
6. Instant Win campaigns evaluate if any qualifying trigger conditions match the cart.
7. The persisted cart becomes available in the customer profile, reporting, calculated attributes, and webhook events.

Key fields that drive DATA

Field area	Why it matters
Customer identifier	Links the cart to the customer profile, loyalty balance, audiences, and tier status.
Store or location	Connects the cart to Store Catalog, store-level targeting, regional reporting, and usual-store calculations.
Product lines	Connects the cart to Product Catalog, category conditions, points multipliers, challenges, and discount application.
Payment methods	Enables payment-method conditions and points campaigns based on the amount paid with a selected method.
Coupons and vouchers	Controls which coupon-gated or voucher-gated promotions are evaluated in the cart.
Cashback request	Lets customers redeem available balance as a monetary discount at checkout.
Returns or cancellation references	Preserve historical accuracy when a cart is partially returned or fully cancelled.

Configuration

Cart events require integration with the Streaming API. Configuration is done at the company level during onboarding:

Setting	Description
Streaming API credentials	Per-company API keys configured in Owner App → Configuration → API
POS / checkout integration	Your team maps cart fields to the Loyal Guru activity schema
Validation rules	Required fields, minimum line amounts, and deduplication logic