Sign in

v1

latestOpenAPI 3.0.32026-07-24153644.3 KB
RewardsService

Locks one or more rewards for a specified customer.

This endpoint is designed to calculate the cashback value accessible to the customer. The calculation is based on the consumption rules defined in the campaign that generated the balance.

To utilize this endpoint, you need to provide the customer identifier and the purchase amount. The customer identifier must match the one used in integrations with Dito.

If the customer has an available balance, it will be returned along with a lock_token. This token must be used to confirm the utilization of cashback in cases where it was applied to a purchase, or to release the balance for new queries following a rollback.

It's crucial to note that, for security reasons, performing two locks sequentially is not allowed. If a lock is executed for a consumer with an available cashback amount, and then another lock is requested, the API will return empty.

Only available rewards are considered as candidates for forming the cashback balance. Rewards in other states (unavailable, available, used, expired) will be disregarded.

post/api/v1alpha1/rewards:lock

Headers

Brandstring required

The brand label provided by us.

Request body

customerIdstring required

The customer identifier must be the same as that sent to Dito.

orderValuestring required

Total value of the customer order.

customDataobject

Custom data, a map of string to string value.

storeIdstring

The store identifier must be the same as that sent to Dito.

sellerIdstring

The seller identifier must be the same as that sent to Dito.

sourcestring

The source represents where the redemption request comes from (e.g., pdv, ecommerce, mobile).

orderVoucherstring

The order voucher is the code of the voucher used in the order.

sellerVoucherstring

The seller voucher is the code of the voucher used in the order.

orderDiscountstring

The order discount is the total discount applied to the order.

Example request

{
  "source": "pdv",
  "orderVoucher": "ORDERVOUCHER",
  "sellerVoucher": "SELLERVOUCHER"
}

Response

A successful response.

lockIdstring

Deprecated.

cashbackTotalValuestring

Amount available for cashback on the order.

lockTokenstring

Lock identifier generated for rewards.

Example response

{
  "lockedRewards": [
    {
      "reward": {
        "id": 1,
        "dueDate": "2024-02-02T04:22:18-03:00",
        "rate": 20,
        "status": "available",
        "availableAt": "2024-02-02T04:22:18-03:00",
        "createdAt": "2024-02-02T04:22:18-03:00",
        "canceledAt": "2024-02-02T04:22:18-03:00"
      },
      "campaign": {
        "id": 1,
        "name": "Every store with 10 cashback",
        "description": "All products have a 10% cashback until the end of the month or the end of stock. The cashback will be available 7 days after the purchase date and can be used for up to 20% of the next purchase."
      }
    }
  ],
  "lockToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJjYXNoYmFja192YWx1ZV9pbl9jZW50cyI6MTAwLCJjdXN0b21lcl9pZCI6ImN1c3RvbWVySWQiLCJleHAiOjE3MDU0MjQ5MTEsImxvY2tfaWQiOiIxMjMiLCJvcmRlcl92YWx1ZV9pbl9jZW50cyI6NTAwMDAwfQ.aNRtKU5S0FR2_JhZzDvc4DdqWKND5wriRTNX_aC9xzs"
}