Vouchers redeem vs Discounts redeem

At checkout confirmation, integrations often need to tell Loyal Guru that a promotion was used. Two Streaming API endpoints can look similar: POST /vouchers/redeem and POST /discounts/redeem. They are not interchangeable.

Use these integration models when reading this page:

Model	Who calculates the final price	Guide
New Engine Promo Engine	Loyal Guru	Cart endpoints with `apply_discounts: true`
New Engine Coupon Server	POS / e-commerce	POS calculates; Loyal Guru confirms usage
Legacy Coupon Server	POS / e-commerce	Legacy coupon/voucher fields and lifecycle

Loyal Guru always owns campaign eligibility and code validation. The model only defines who calculates the final price and how usage is confirmed.

One-line difference

Endpoint	What it does
`POST /vouchers/redeem`	Marks voucher records as used so the same voucher cannot be reused.
`POST /discounts/redeem`	Confirms an external campaign redemption on the current engine: records the applied amount for budget, limits, and discount history. If a voucher is involved, Loyal Guru also marks that voucher as used.

Use POST /discounts/redeem when a client system calculated the discount and Loyal Guru must store the applied amount for the campaign. Use POST /vouchers/redeem when you only need to close the voucher lifecycle, typically in Legacy Coupon Server flows.

Which endpoint should you use?

Situation	Recommended call
Promo Engine checkout on an LG-integrated channel	Prefer `POST /carts/simulate` then `POST /carts/realtime` with `apply_discounts: true`. Extra redeem calls are usually unnecessary.
Promo Engine company, but a non-integrated POS also accepts the same vouchers	Use `POST /discounts/redeem` from that POS to burn the voucher/code in Loyal Guru and reduce double-redemption fraud.
New Engine Coupon Server	Prefer `POST /discounts/redeem` with the applied amount in cents.
Static coupon code (no per-customer voucher) on the current engine	Prefer `POST /discounts/redeem` with `static_code`.
Legacy Coupon Server, only need “code cannot be reused”	`POST /vouchers/redeem` remains valid.
Full campaign reporting / budget / ROI on New Engine Coupon Server	`POST /discounts/redeem` with cart linkage (`cart_id` or `cart_code`) on a cart that already exists.

Side-by-side comparison

Topic	`POST /vouchers/redeem`	`POST /discounts/redeem`
Main purpose	Close voucher lifecycle	Record campaign redemption amount on the current engine
Typical input	List of vouchers + optional activity / cart reference	One `voucher_code` or `static_code`, plus customer or cart, plus required `discount` (cents)
Static codes without a voucher	Not the right tool	Supported
Campaign budget and discount history	Not updated by this call alone	Updated with the amount you send
Marks voucher as used	Yes	Yes, when a voucher is resolved for that code
Multiple codes in one request	Yes	No — one code per request
Rollback companion	`POST /vouchers/rollback`	No dedicated discounts rollback for this flow yet — plan cancellations/returns with your Loyal Guru project team
Response	Success status	Effect object with `effect_type: external_redemption`

New Engine Coupon Server recommendation

For New Engine Coupon Server integrations:

Read eligibility and rules with GET /discounts and validate codes with GET /vouchers/{code} as needed.
Calculate the final price in the POS / e-commerce system.
Confirm usage with POST /discounts/redeem, sending the exact applied amount in cents.
Do not also call POST /vouchers/redeem for the same confirmation. POST /discounts/redeem already marks the related voucher as used when applicable. Calling both can consume the voucher twice.

Keep voucher lifecycle endpoints (select, deselect, freeze, unfreeze, print) as needed for your POS UX. Those are separate from campaign amount confirmation.

When Loyal Guru is the Promo Engine on one channel (for example online checkout or one physical POS), other store systems may still accept the same vouchers without calling the cart Promo Engine flow.

In that case, use POST /discounts/redeem from the non-integrated POS to:

Mark the voucher or static code as used in Loyal Guru.
Record the applied amount for campaign budget and history.
Reduce fraud from double redemption across channels (online vs store, or LG-integrated POS vs another POS).

Example: Loyal Guru evaluates discounts only on the ecommerce checkout. A store POS that is not integrated as Promo Engine still accepts the customer voucher. That store POS should call POST /discounts/redeem when it applies the voucher, so the code cannot be reused later on the LG-integrated channel.

Do not call POST /vouchers/redeem in addition to POST /discounts/redeem for the same confirmation.

Cart timing

POST /discounts/redeem accepts either a customer identifier or a cart identifier.

Pattern	Result
Redeem with `customer_id` or `customer_code` only	Succeeds. Campaign redemption can be recorded without a cart.
Redeem with `cart_id` or `cart_code` of an existing cart	Succeeds and links the redemption to that cart. Prefer this when sales attribution or ROI matters.
Redeem with `cart_id` or `cart_code` of a cart that does not exist yet	Fails with cart not found.
Redeem without cart, then send the cart later	Both calls can succeed, but the later cart is not automatically linked to the earlier redemption.

Recommended order when you need cart-linked reporting: create or send the cart first, then call POST /discounts/redeem with cart_id or cart_code.

Example: confirm a Discount redemption (Coupon Server)

POST /discounts/redeem
X-Api-Key: your_api_key
X-Api-Secret: your_api_key_secret
X-Api-Version: 1
Content-Type: application/json

{
  "voucher_code": "212128711",
  "customer_id": 8223,
  "cart_id": 202607090001,
  "discount": 1500
}

Notes:

Send either voucher_code or static_code, not both as competing values for different intents.
Send either customer (customer_id / customer_code) or cart (cart_id / cart_code).
discount is required and expressed in cents (example: 1500 = 15.00 in the company currency).

Full schemas: Discount endpoints and Voucher endpoints.

Migration note

If you are moving from Legacy Coupon Server to New Engine Coupon Server and need campaign budget, limits, or discount history in Loyal Guru, replace usage confirmation with POST /discounts/redeem. Keeping only POST /vouchers/redeem closes the voucher, but does not record the campaign amount on the current engine.

One-line difference​

Which endpoint should you use?​

Side-by-side comparison​

New Engine Coupon Server recommendation​

Promo Engine: redeem from a non-integrated POS​

Cart timing​

Example: confirm a Discount redemption (Coupon Server)​

Migration note​

Related guides​