v1

latestOpenAPI 3.0.2EULA2026-07-143221521.2 MB

Purchases

Provides a list of rewards and vouchers available for purchase closure

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.

post/purchases/actions/recommended-best-rewards

Headers

Accept-Languagestring

The unique ID of the language code by ISO 639-1.

Request body

store_idstring 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

cashdesk_numberinteger required

Number of the cash desk in the store. Used to identify a specific cash desk when multiple are available.

card_numberstring

The customer card number.

customer_idstring

ID of the customer who is closing the purchase. You can search for customers by various parameters in the GET /customers 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

Example request

{
  "store_id": "8bed991c68a470e7aaeffbf048",
  "cashdesk_number": 1,
  "card_number": "1000000000016",
  "customer_id": "8ea2591121e636086a4a9c0992",
  "reward_list_type": "C",
  "bill": {
    "bill_id": "39475X",
    "payment_time": "2016-06-30 15:05:49",
    "created_by": "API user",
    "currency_id": "8bed991c68a470e7aaeffbf048",
    "total_price": 700,
    "bill_items": [
      {
        "plu_ids": [
          {
            "list_code": "GLOBAL",
            "code": "abc"
          }
        ],
        "plu_name": "Iphone 14",
        "category_plu_id": "CA234B",
        "vat_rate": 20,
        "quantity": 2,
        "paid_amount": 1200,
        "price": 1200,
        "bill_item_id": "6fd73167342d6899c415320",
        "loyalty_off": true,
        "purchase_item_type_id": "86e05affc7a7abefcd513ab400",
        "customer_id": "8ea2591121e636086a4a9c0992",
        "purchase_item_property_records": [
          {
            "property_record_id": "docasna_blokace_darce_do:8ea2591121e636086a4a9c0992",
            "property_id": "docasna_blokace_darce_do",
            "property_name": "Property #6",
            "last_change": "2023-02-02 00:00:00"
          }
        ]
      }
    ]
  }
}

Response

Example response

{
  "data": {
    "recommended_best_rewards": [
      {
        "code": "PTV138",
        "name": "SVK_wine",
        "reward_priority": 8,
        "description": "SVK_wine",
        "reward_properties": {
          "valid_time_from": "00:00:00",
          "valid_time_to": "23:00:00"
        }
      }
    ],
    "total_items": 1
  }
}