---
title: "Locks one or more rewards for a specified customer."
method: POST
path: "/api/v1alpha1/rewards:lock"
tags: ["RewardsService"]
---

# Locks one or more rewards for a specified customer.

`POST /api/v1alpha1/rewards:lock`

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.

## Headers

- `Brand` string, required

## Request body

- V1alpha1LockRewardsRequest
  - `customerId` string, required — The customer identifier must be the same as that sent to Dito.
  - `orderValue` string, required — Total value of the customer order.
  - `customData` object — Custom data, a map of string to string value.
  - `storeId` string — The store identifier must be the same as that sent to Dito.
  - `sellerId` string — The seller identifier must be the same as that sent to Dito.
  - `source` string — The source represents where the redemption request comes from (e.g., pdv, ecommerce, mobile).
  - `orderVoucher` string — The order voucher is the code of the voucher used in the order.
  - `sellerVoucher` string — The seller voucher is the code of the voucher used in the order.
  - `orderDiscount` string — The order discount is the total discount applied to the order.
  - `products` Cashbackapiv1alpha1Product[] — The products represents the details of the products included in the order.
    - `sku` string
    - `ean` string
    - `name` string
    - `quantity` integer, required
    - `categories` string[]
    - `grossUnitValue` string, required
    - `netUnitValue` string, required
    - `discountUnitValue` string, required
    - `extraInformation` object

## Response `200`

A successful response.

- V1alpha1LockRewardsResponse
  - `lockId` string — Deprecated.
  - `cashbackTotalValue` string — Amount available for cashback on the order.
  - `lockedRewards` V1alpha1LockRewardsResponseLockedRewards[] — List of rewards used for cashback value.
    - `reward` Corev1alpha1Reward
      - `id` integer — ID of the reward.
      - `dueDate` string, date-time — Reward expiration date.
      - `value` string — Maximum amount to be redeemed for the reward.
      - `rate` integer — Maximum percentage of the purchase value that the reward value can be applied to.
      - `status` string — Informs the status of the reward. It can be available, locked, used, expired and undefined.
      - `availableAt` string, date-time — Reward available date.
      - `createdAt` string, date-time — Reward create date.
      - `balance` string — Balance available to be redeemed.
      - `canceledAt` string, date-time — Reward cancel date.
      - `extraInformation` V1alpha1ExtraInformation
        - `orderId` string — OrderID is the ID that identifies the purchase transaction that generated the reward.
        - `storeId` string — StoreID is the ID of the store where the purchase comes from.
    - `campaign` V1alpha1Campaign
      - `id` integer — ID of the campaign that generated the reward.
      - `name` string — Name of the campaign that generated the reward.
      - `description` string — Description of the campaign that generated the reward.
    - `cashbackValue` string — Reward value that is available for redemption based on consumption criteria.
  - `lockToken` string — Lock identifier generated for rewards.

## Other responses

- `400` — When an invalid request is sent.
- `401` — When the authentication is failed.
- `403` — when it was not authorized.
- `default` — An unexpected error response.

---

[API](https://skmtc.dev/dito/apis/authentication-api.md) · [All operations](https://skmtc.dev/dito/apis/authentication-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/dito/authentication-api/revisions/de4a5e2a412f/schema)