Sign in
.md

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:

  1. Reward — preview cashback and discounts for the order
  2. Confirm — apply the rewards once payment goes through
  3. 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