Sign in

Reward by Order

POST https://{organization}.myguper.com/api/loyalty/rewardByOrder

Calculates the cashback amount that a given order is eligible for. This endpoint operates in two modes: Private and Public. Pick the mode that matches your use case below.

Try-it values populated from environment ACME (Demo)

Modes

Returns customer data, redeemable reward information and a confirmation token you can later send to confirmOrder. Requires a valid user token.

Authentication

Token

Send your user token in the x-guper-authorization header. Endpoints that support a Public mode (e.g. acúmulo and resgate previews) accept the same request without the header — Private mode adds customer data and a confirmation token to the response.

Headers

Name Type Description
x-guper-authorization * string User token issued by Guper. Omit only on endpoints that explicitly support a Public mode.
Content-Type * string Always `application/json` for endpoints that accept a JSON body.

Request body

Content-Type: application/json

{
    "interface": "generic",
    "storeId": "1",
    "checkoutId": "ck_demo_a1b2-c3d4",                          // optional
    "purchaseType": "delivery",                                 // optional
    "client": {                                                 // optional
        "id": "123123",                                         // optional
        "name": "Tintim",                                       // optional
        "document": "32165987",                                 // optional
        "email": "tintim@guper.co",                             // optional
        "countryCallingCode": 55,                               // optional
        "cellphone": "19954264546"                              // optional
    },
    "attendants": {                                             // optional
        "cashier": {                                            // optional
            "id": "123"
        },
        "salesperson": {                                        // optional
            "id": "342"
        }
    },
    "items": [
        {
            "id": "1",                                          // SKU id
            "productId": "1",                                   // optional
            "name": "Smartphone Guper MK1",
            "categoryId": "20",                                 // optional
            "brandId": "20",                                    // optional
            "sellerId": "1",                                    // optional
            "tax": 1232,                                        // optional, cents
            "quantity": 1,                                      // int ≥ 1
            "price": 96390,                                     // cents
            "listPrice": 100000                                 // optional, cents
        }
    ],
    "shipping": [                                               // optional
        {
            "id": "AA123456785BR",
            "courierId": "correios-br",
            "courierName": "Correios",
            "price": 2000,                                      // cents
            "listPrice": 2000                                   // optional, cents
        }
    ]
}

Responses

{
    "organization": "acme",
    "interface": "generic",
    "customerId": 708,
    "cashback": {
        "thisOrder": {
            "redeemable": {
                "total": 522,
                "item": [{ "id": "1", "value": 522 }]
            },
            "accumulating": {
                "total": 4819,
                "item": [{ "id": "1", "value": 4819 }]
            }
        },
        "userBalance": { "total": 0, "availableAmount": 0 }
    },
    "confirmToken": "54eb6281f4e3e13671a5e4c95609f4a69247a5f38d01bef99768399bb6645c49",
    "smartpos": "https://acme.myguper.com/smartpos/54eb6281f4e3e13671a5e4c95609f4a69247a5f38d01bef99768399bb6645c49",
    "expiresAt": "2024-05-21T11:21:27-03:00",
    "dateTime": "2024-05-21T10:51:27-03:00"
}

Notes

Redemption blocked by the wallet rule. When the wallet has a dynamic minimum (minOrderRate), the customer's balance can only be used if the order is worth N times that balance — 3 with a $30.00 balance requires a $90.00 purchase. It is all-or-nothing: below that, nothing is redeemed, not even part of it.

In that case redeemable.total comes back 0 and redeemable.blocked says why:

"redeemable": {
    "total": 0,
    "item": [],
    "blocked": [
        {
            "wallet": 60,
            "reason": "minOrderRate",
            "rate": 3,
            "balance": 3000,
            "required": 9000,
            "missing": 1500
        }
    ]
}

wallet is the policy id, rate the multiplier, balance the balance considered, required what the order would have to be worth and missing what is left (required − order total). Amounts in cents.

The balance itself is untouched — userBalance still shows it, and the same customer redeems normally on a bigger cart. Show missing to the customer: "$15.00 more to use your balance". The same block shows up in Update transaction, which re-applies the rule when the cart changes.

Copied to clipboard