---
title: "Provides a list of rewards and vouchers available for purchase closure"
method: POST
path: "/purchases/actions/recommended-best-rewards"
tags: ["Purchases"]
---

# Provides a list of rewards and vouchers available for purchase closure

`POST /purchases/actions/recommended-best-rewards`

Method returns all rewards and vouchers available for a specific client application (e-commerce, POS, etc.).
The response includes reward definitions and customer-specific vouchers that are valid at the time of the request. For each item, a parameter defines the maximum usage per purchase.
If the value of this parameter is zero, the item cannot be applied.

Each item in the response can represent one of two types:
 - Reward definition - a catalog-level reward identified by an alphanumeric code (for example, `PTV12`).
 - Voucher - a reward issued to a specific customer, identified by a numeric code generated by CareCloud or a custom code syntax defined by the client.

Rewards are always associated with products via bill items.

## Headers

- `Accept-Language` string

## Request body

- object
  - `store_id` string, required — The store ID identifies the store or business unit that will close the purchase for the customer. The list of all stores is available at the endpoint [GET /stores](https://carecloud.readme.io/reference/getstores)
  - `cashdesk_number` integer, required — Number of the cash desk in the store. Used to identify a specific cash desk when multiple are available.
  - `card_number` string — The customer card number.
  - `customer_id` string — ID of the customer who is closing the purchase. You can search for customers by various parameters in the [GET /customers](https://carecloud.readme.io/reference/getcustomers) endpoint.
  - `reward_list_type` 'F' | 'C' | 'A', required — Specifies the type of rewards to be listed in the response. Possible values: - F (full) - All manual rewards that are valid in the defined store - C (condensed) - Returns manual rewards that are related to the items from provided purchase. If application is not possible, the reward is not returned. - A (all) - List of all available rewards on the project (including automatic rewards). Extended information about rewards is available at the endpoint [GET /rewards](https://carecloud.readme.io/reference/getrewards)
  - `bill` Bill, required — Structure of bill from POS.
    - `bill_id` string, required — Identification number of the purchase created in the production system like POS, e-commerce solution or ERP (The ID must be unique in the production system). In case you want to send cancelled purchase, please use prefix `C` for the original purchase ID. Example: ``` Original purchase ID: 39475X Canceled purchase ID: C39475X ```
    - `bill_number` string — Alternative identification of the bill. In the case of cancellation, there should be bill_id from the original bill.
    - `payment_time` string, required — Timestamp of the payment. Accepts the format `YYYY-MM-DD HH:MM:SS` or ISO-8601 format (`YYYY-MM-DDTHH:MM:SS`). All times must be in the local timezone.
    - `created_by` string — Name of the user who created a bill.
    - `currency_id` string, required — ID of the currency from resource [currencies](https://carecloud.readme.io/reference/getcurrencies).
    - `total_price` number, float, required — The total price of the bill as a sum of all items.
    - `bill_items` BillItem[], required — List of bill items.
      - `plu_ids` PluId[], required — An array of all available pluIds from the particular product lists (default is Product ID from Global product list (consist cleaned data - unique ID of every product across all POS systems)).
        - `list_code` string, required — Code of the particular product list (basic is code of Global product list (consist cleaned data - unique ID of every product across all POS systems)). For example, “GLOBAL”, “SKU”, “PLU”, etc.
        - `code` string, required — Code of product from the product list (basic is Product ID from Global product list (consist cleaned data - unique ID of every product across all POS systems)).
      - `plu_name` string, required — Product name.
      - `category_plu_id` string — Product group ID identify the product group in the system outside of CareCloud (POS, e-shop, etc.). Consist cleaned data - unique ID of every product group across all POS systems. This parameter needs to be set only if product learning is activated. If not set during product learning the default product group will be used.
      - `vat_rate` number, float, required — VAT rate of the item.
      - `quantity` number, float, required — Quantity of product.
      - `paid_amount` number, float, required — Real money value (unit price * quantity) paid by the customer (The value for a pharmaceutical client could have a copayment for drug prescription or money value of drugs not covered by an insurer).
      - `price` number, float, required — Value of parameter "paid_amount". In the case of a pharmaceutical client, add to the value of "paid_amount" a value of money covered by the customer health insurance.
      - `bill_item_id` string, required — ID of the bill item.
      - `loyalty_off` true | false, required — Switch off all loyalty benefits (points, discounts- instant and campaign prices, vouchers) on the item.
      - `purchase_item_type_id` string, required — Type of the purchase item from resource [purchase-item-types](https://carecloud.readme.io/reference/getpurchaseitemtypes).There is a distinction between a purchase in an e-shop, in a brick-and-mortar store, a mobile application, or a cancellation of the purchase. It also differentiates purchases without the possibility of applying loyalty benefits from ordinary purchases or from purchases with the application of loyalty points.
      - `customer_id` string — The ID of the customer. [GET /customers](https://carecloud.readme.io/reference/getcustomers)
      - `purchase_item_property_records` PropertyRecord[] — List of properties for the purchase item.
        - `property_record_id` string — The unique ID of the property record.
        - `property_id` string, required — The unique ID of the property.
        - `property_name` string — Name of the property.
        - `property_value` union — Value of the property record. The format depends on the data type of the property. - **string** – a plain text value: ```json { "property_id": "p1_note", "property_value": "VIP customer" } ``` - **date** – a date string in `YYYY-MM-DD` format: ```json { "property_id": "p1_birth_date", "property_value": "1985-06-15" } ``` - **integer** – a whole number: ```json { "property_id": "p1_visit_count", "property_value": 42 } ``` - **float** – a decimal number: ```json { "property_id": "p1_average_spend", "property_value": 149.90 } ``` - **enum** – a single-item array containing a PropertyItem object: ```json { "property_id": "p1_favourite_color", "property_value": [ { "id": "86e05affc7a7abefcd513ab400", "name": "Blue", "resource_record_id": null, "state": 1 } ] } ``` - **multiselect** – a multi-item array of PropertyItem objects: ```json { "property_id": "p1_favourite_color", "property_value": [ { "id": "86e05affc7a7abefcd513ab400", "name": "Blue", "resource_record_id": null, "state": 1 }, { "id": "81eaeea13b8984a169c490a325", "name": "Green", "resource_record_id": null, "state": 1 } ] } ``` - **custom data type** – the format depends on the specific data type configuration. For example, a serialized JSON object: ```json { "property_id": "p1_address", "property_value": "{\"street\":\"Main St\",\"city\":\"Prague\"}" } ```
          - string
          - number
          - integer
          - boolean
          - unknown[]
            - unknown
          - object
        - `last_change` string — Date and time of the last change. *(YYYY-MM-DD HH:MM:SS)*

## Response `200`

OK

- object
  - `data` object
    - `recommended_best_rewards` RecommendedReward[] — List of the best rewards for a specific client application (e-commerce, POS, etc.).
      - `code` string — Code of the reward.
      - `name` string — Name of the reward.
      - `reward_priority` 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 — Priority of the reward. *1 - highest, 9 - lowest*
      - `max_count` integer — Maximum number of the reward applications.
      - `description` string — Reward description.
      - `reward_properties` RewardProperties — Properties of the reward.
        - `image` string, byte — Image of the reward encoded in BASE64.
        - `valid_time_from` string — Time the reward is valid from. *(HH:MM:SS)*
        - `valid_time_to` string — Time the reward is valid to. *(HH:MM:SS)*
    - `total_items` integer — The number of all found rewards.

## Other responses

- `400` — Bad input parameter. The response body's `error.error_data.invalid_params[]` array lists the parameters that caused the failure, each carrying a `reason` code. See the `BadRequestErrorBody` schema for the generic reason taxonomy. Operations with domain-specific business rules document additional reasons at the operation level.
- `401` — The client has invalid credentials or auth token.
- `403` — The client does not exist or the client tried to access an unauthorized property or resource.
- `404` — The resource was not found.
- `405` — The resource does not support the specified HTTP method.
- `429` — Too many requests - more than the resource limit.
- `500` — Server is not working as expected.
- `503` — Temporary state when the service is temporarily unavailable, overloaded or there is a maintenance window.

---

[API](https://skmtc.net/crmcarecloud/apis/rest-api-reference.md) · [All operations](https://skmtc.net/crmcarecloud/apis/rest-api-reference/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/crmcarecloud/rest-api-reference/revisions/329c06dbf8d9/schema)