Generic Checkout
If your storefront isn't VTEX or Shopify (or you want fine-grained control), this is the API-level integration that everyone else builds on. The pre-built VTEX IO and Shopify connectors talk to the same endpoints under the hood.
Plug Guper into your checkout in three calls. Each step has a focused responsibility:
- Reward — preview cashback and discounts for the order
- Confirm — apply the rewards once payment goes through
- Update — modify the pending order before confirming (size change, cancellation, etc.)
A fourth optional step lets you require a PIN for high-value redemptions.
Step 1 — Reward by order
Send the cart contents and the customer identifier. Guper returns a confirmToken, the cashback amount that would accumulate, and any redeemable rewards available on the customer.
POST /api/loyalty/rewardByOrder
Pick the Public variant (omit x-guper-authorization) for a preview that doesn't carry customer data, or Private when you need the full customer view + token. See Reward by Order for the full schema.
Step 2 — Confirm transaction
Once the payment processor returns success, hand the confirmToken back to Guper. The rewards become real on the customer's account, and the transaction is recorded.
POST /api/loyalty/confirmOrder/{confirmToken}
After this point, the cashback is on the customer's balance and the order shows up in the Order feed for downstream systems.
Step 3 — Update transaction (optional)
If the order changes between Reward and Confirm — items added/removed, address changed, partial cancel — call Update before Confirm to refresh the cashback calculation.
POST /api/loyalty/updateTransaction/{confirmToken}
The same confirmToken carries through. Guper recalculates and the next Confirm uses the new amount.
Optional — PIN validation
For high-value redemptions you can require the customer to enter a PIN. Two endpoints:
GET /api/register/customer/{person}/pin # generate / send PIN to customer
POST /api/register/customer/{person}/pin/validate # confirm PIN entered at POS
Validate the PIN between Reward and Confirm — only proceed to Confirm if validation succeeds.
Full flow
┌──────────────────────────────────────────────┐
│ │
┌─────────┐ │ ┌─────────┐ │
│ Reward │ ─→│ │ Update │ ─→ (PIN check, optional) ─→ │
└─────────┘ │ └─────────┘ │
│ ↑ │
│ │ ↓
│ │ ┌──────────────┐
│ └─────────────────────────────│ Confirm │
│ └──────────────┘
└──────────────────────────────────────────────┘
(recalculations loop until payment succeeds)
Cancellation
If you need to undo a confirmed order — full or partial:
- Full —
POST /api/loyalty/cancelOrderByTransaction/{TID}returns the cashback that was earned and rolls back any redeemed reward. - Partial —
POST /api/loyalty/cancelPartial/{TID}for cancelling specific items. See Partial cancellation for the per-item rules.
Authentication
All Confirm/Update/Cancel endpoints require a valid x-guper-authorization token. The Public variant of Reward is the only checkout endpoint that doesn't. See Authentication.
See also
- Reward by Order — endpoint reference with full schema and Try-it
- Cancel transaction and order
- Sandbox — test the full flow end-to-end before flipping production