New Engine Coupon Server

Use this model when the external system must keep final price calculation, but Loyal Guru remains the source of truth for campaign eligibility, coupon/voucher validation, customer assignment, limits, and redemption state.

Responsibilities

System	Responsibility
Loyal Guru	Exposes active campaign rules through GET /discounts, validates coupon/voucher ownership and status, records redemption or rollback.
POS / e-commerce	Reads campaign fields, maps them to local pricing logic, calculates the final amount, and sends confirmed usage back to Loyal Guru.

End-to-end flow

The POS owns the promotional mechanics: it reads active campaign and voucher data, calculates the discount locally, prints or validates the voucher when needed, and confirms usage back to Loyal Guru. Loyal Guru remains the source of truth for Customer identity, campaign eligibility, voucher assignment, limits, and redemption state.

Supporting data sync

Before the POS can calculate promotions locally, Loyal Guru needs the data used by campaign rules and audience eligibility:

Data area	Integration role
Customers	Keep Customer identity and profile fields aligned so vouchers and audiences can be resolved. Legacy integrations that still read/write custom1–custom11 / custom1f–custom8f should migrate to the attributes object — see Custom fields → Attributes.
Products	Keep product IDs, codes, and taxonomy fields aligned with the catalog used by POS pricing logic.
Locations	Keep store/location identifiers aligned with the stores where discounts can apply.
Cart events and lines	Send historical and ongoing cart data so Customer behavior, audiences, and usage reporting stay consistent.

These sync flows can use files or APIs depending on project scope. Endpoint-level schemas belong in the API Reference.

Runtime endpoints

Endpoint	Use it for
GET /customers/{value} / POST /customers/search	Resolve the Customer used to request available campaigns or validate vouchers.
GET /discounts	Campaign catalog, customer-specific campaigns, campaign rule fields, coupon metadata, targeted voucher details.
GET /discounts/{value}	Campaign detail; use search_by=campaign_history_id when the same targeted campaign was sent more than once.
GET /vouchers/{code}	Validate a voucher or coupon code before applying it in the POS.
PUT /vouchers/select / POST /vouchers/{code}/select	Reserve one or more vouchers before checkout when the POS has a selection step.
PUT /vouchers/deselect / POST /vouchers/{code}/deselect	Cancel a previous voucher selection before checkout.
POST /vouchers/{code}/freeze / POST /vouchers/{code}/unfreeze	Temporarily block a voucher from being printed or redeemed, and release that hold.
POST /carts/realtime	Persist the confirmed cart and usage with apply_discounts: false.
POST /discounts/redeem	Confirm campaign usage when the POS calculated the amount. Send the applied amount in cents. Preferred confirmation call for New Engine Coupon Server.
POST /vouchers/redeem / POST /vouchers/rollback	Explicit voucher lifecycle mark-as-used or rollback. Prefer POST /discounts/redeem for New Engine campaign amount confirmation — see Vouchers redeem vs Discounts redeem.
POST /vouchers/print	Get the batch of vouchers to print on the receipt, ordered by campaign priority, voucher priority, then soonest expiration.

Reading and interpreting GET endpoints

In Coupon Server mode the POS (or middleware) must read campaign and voucher data from Loyal Guru and interpret it before calculating the final price locally.

Endpoint	What to interpret
GET /discounts	Active campaigns, metadata, coupon/voucher info, and rule JSON (rule_conditions, rule_application, rule_effects)
GET /discounts/{value}	Single campaign detail (use search_by=campaign_history_id when needed)
GET /vouchers/{code}	Code ownership, status, redemptions, and validity before apply
Customer lookup	Which Customer the campaigns/vouchers belong to

The response of GET /discounts may include:

• Campaign metadata: id, name, active, available_from, available_to, currency, category, priority.
• Audience and code metadata: select_customers, coupon_required, coupon_info.
• Targeted voucher data: coupon_info.voucher_info for customer-specific assignments.
• Rule JSON: rule_conditions, rule_application, rule_effects.
• POS helper arrays: product_ids_rule_conditions, product_ids_rule_application, locations_ids, location_codes. The Company must have default_apply_discounts: false (coupon server). If that slug is missing or true, GET does not return these arrays. When the company is a coupon server, each campaign still decides whether to populate them (internal taxonomy vs direct IDs/codes). See POS helper fields.

Full field-by-field guide (nested under this Coupon Server section): Reading from GET — response shape, conditions, application, and effects.

Static coupons and vouchers

Code type	How it behaves
Static coupon	Shared code configured on the campaign. It can be shown publicly or entered manually, subject to campaign limits and configuration.
Voucher	Customer-specific assignment with its own code, status, date window, redemptions, and customer ownership.

Do not treat static coupons and vouchers as interchangeable. A voucher proves that a specific customer received a personalized campaign or benefit; a static coupon is the campaign-level code configuration.

Confirming usage after the POS calculates the price

After the POS applies the discount locally, confirm usage in Loyal Guru:

• Prefer POST /discounts/redeem for New Engine Coupon Server so Loyal Guru records the applied amount for budget, limits, and discount history.
• Do not also call POST /vouchers/redeem for the same confirmation — POST /discounts/redeem marks the related voucher as used when applicable.
• For cart-linked reporting, send or create the cart first, then redeem with cart_id or cart_code.

Full decision guide: Vouchers redeem vs Discounts redeem.

Implementation notes

• Cache GET /discounts for a short interval only; campaign availability, budget, limits, and targeted delivery history can change.
• Always re-check customer-specific vouchers before final application if the checkout flow can last more than a few minutes.
• When POS helper arrays are empty, parse rule_conditions, rule_application, and rule_effects directly or use your local catalog mapping.
• Send apply_discounts: false in cart confirmation when the POS has already calculated the final price. The company slug default_apply_discounts must also be false for coupon-server mode (otherwise GET omits POS helper arrays and the engine may still try to calculate discounts).
• Keep rollback behavior explicit for failed payments, order cancellations, and returns.
• For campaign amount confirmation on New Engine Coupon Server, use POST /discounts/redeem rather than only POST /vouchers/redeem.

Troubleshooting

Symptom	What to check
A campaign is missing from GET /discounts	active, date window, customer filter, campaign_audience, country/store filters, targeted voucher state, and pagination.
POS helper arrays are empty	Company default_apply_discounts must be false. If it is, this campaign may use direct IDs/external taxonomy that cannot be expanded — parse rule_*.
Voucher appears twice for the same campaign	The campaign may have been sent in multiple deliveries; use campaign_history_id to identify the intended delivery.
POS applies a discount but Loyal Guru rejects the code	Check voucher ownership, status, available redemptions, store scope, expiration, and whether the static coupon code is unique to the campaign.
Campaign budget / discount history missing after POS applied a discount	Confirm the integration calls POST /discounts/redeem with the applied amount in cents, not only POST /vouchers/redeem.