Links
Comment on page

Rewards API

Rewards connector that enables to provide vouchers, coupons, rewards or deals for your customers.
This is a DRAFT version and is subject to changes.
This document has been created as a preliminary version to gather feedback, suggestions, and input from all parties involved.

Glossary

Term
Definition
PORTOS
The cash register solution developed by Nine Digit, s.r.o.
External system
The 3rd party system (such as e-shop or food delivery platform) from which rewards are fetched to PORTOS.
Venue
E.g. store or restaurant.
Cashier
The Venue personnel.
Customer
Person who purchases the goods.
Reward
The coupon or discount that customer can be rewarded with.
Product
The product that is being purchased by customer.

How it works

The Rewards API is a mechanism that allows importing rewards (such as coupons, deals or discounts) to the PORTOS system.
The PORTOS system acts as an "client" initiating HTTP request targeting the external system, that acts as an "server" and handles the following requests:
  1. 1.
    Fetch available rewards
  2. 2.
    Claim reward(s)
The PORTOS system expects that responses from external system follows data format described below.
get
{external-system}
{get-rewards-url}
Fetch available rewards
post
{external-system}
{claim-rewards-url}
Claim reward(s)

Configuration

To communicate with external system properly, the external system administrators must provide values stated below to the venue owners or PORTOS support.
Value
Type
Description
External system "get rewards" URL
string
The URL hosted by external system, that will be requested by PORTOS to fetch rewards.
External system "claim rewards" URL
string
The URL hosted by external system, that will be requested by PORTOS to claim rewards.
API key
string
The venue-specific API key (authorization token) that will be placed in the key query parameter of all HTTP requests.

Data model

The rewards API data model is described below.
All prices include taxes.

CustomerRewards

The collection of rewards available for given customer.
Name
Type
Required
Description
rewards
Reward[]
The collection of available rewards.
customer
Customer
The information about customer, if available.
maxApplicableRewards
int
The maximum number of applicable rewards per given purchase.

Customer

Information about customer.
Name
Type
Required
Description
displayName
string
The display name of customer or customer loyalty account.
points
number
Represents number of loyalty points associated with customer account.
firstName
string
First name.
lastName
string
Last name.
email
string
E-mail address that can be used when sending receipt in e-mail form.
maxApplicableRewards
int
The maximum number of rewards that can be applied per purchase. The rewards can also be limited by specifying available customers loyalty points and price in points of reward.

Reward

Represents the reward.
Name
Type
Required
Description
id
string
Unique reward identifier.
title
string
Reward title.
description
string
Short reward description.
conditions
Conditions that need to be fulfilled in order for the customer to claim the reward.
items
Collection of one or more items associated with given reward.
activationDate
string
If specified, the reward becomes applicable only after the specified date and time in ISO_8601 format, expressed in UTC.
expirationDate
string
If specified, the reward is applicable only before the specified date and time in ISO_8601 format, expressed in UTC.
minPurchaseAmountIncludingVat
number
If specified, represents the minimum purchase amount required to claim the reward.
priceInPoints
number
Specifies number of loyalty points subtracted from customer's loyalty account once the reward is claimed.
remainingUsage
number
Specifies maximum number of times can this reward be claimed by any customer.
remainingCustomerUsage
number
Specifies maximum number of times can this reward be claimed by given customer.

RewardCondition

Name
Type
Required
Description
purchase
Optional conditions related to purchase.

RewardPurchaseCondition

Name
Type
Required
Description
minAmountIncludingVat
number
If specified, represents the minimum purchase amount required to claim the reward.

RewardItem

Single reward item.
Name
Type
Required
Description
target
string
productFilter
Required, when target is product. Must be null otherwise.
purchaseItemFilter
Required, when target is purchaseItem. Must be null otherwise.
purchaseItemLookupMode
string
One of PurchaseItemLookupMode. when target is purchaseItem. Must be null otherwise.
discountType
string
One of RewardItemDiscountType. If target is equal to purchase, value must be prcentage or absolute.
discountAmount
number
Positive, non-zero number. Minimal value is 0.01. Required, when discountType is absolute or relative. Must be null otherwise.
discountRate
number
Positive, non-zero number, with value between 0.01 and 100. Required, when discountType is percentage. Must be null otherwise.

RewardItemDiscountType

List of known discount types:
Name
Description
percentage
Reward provides a percentage discount.
absolute
Reward provides a discount that is specified by a fixed or absolute value rather than a percentage.
relative
Reward provides a discount by subtracting a specific value from the original retail price of a product or service.

RewardItemTarget

The target that reward item applies to.
Name
Description
purchaseItem
Reward provides a discount to single purchase item. Purchase item can be specified by RewardItemPurchaseItemFilter. If no suitable product is found in the purchase, reward is not applied.
product
Reward provides a discount for a certain product, specified by RewardItemProductFilter. If given product is not initially included in the purchase, it will be added to the purchase automatically, so that the discount can be applied.
purchase
Reward applies a discount to entire purchase

RewardItemProductFilter

Model that uniquely identifies product.
Name
Type
Required
Description
pluId
PluId
At least one of identifier fields (pluId or id) must be specified.
id
string
At least one of identifier fields (pluId or id) must be specified.

RewardItemPurchaseItemFilter

Model that selects purchase item.
Name
Type
Required
Description
pluIds
PluId[]
TicketItem.Plu.Code and TicketItem.Plu.StockNamemust be equal to one of provided values, if value is not null or empty.
articleCategoryLabels
string[]
TicketItem.Plu.ArticleCategoryLabel must be equal to one of provided values, if value is not null or empty.
minUnitPriceIncludingVat
number
If specified, TicketItem.UnitPriceIncludingVat must be greater than or equal to provided value.
maxUnitPriceIncludingVat
number
If specified, TicketItem.UnitPriceIncludingVat must be less than or equal to provided value.
minQuantity
number
If specified, TicketItem.Quantity must be greater than or equal to provided value.
maxQuantity
number
If specified, TicketItem.Quantity must be less than or equal to provided value.

PurchaseItemLookupMode

Specifies, what strategy is used to look up single purchase item among all items in purchase, that reward will be applied to.
Name
Description
cheapest
Prefers least expensive product, based on it's unit price.
mostExpensive
Prefers most expensive product, based on it's unit price.

Error models

Error

Error model received for non-2XX HTTP statuses.
Name
Type
Required
Description
message
string
Human readable message describing the error.
rewardId
string
Id of Reward, if error is reward-specific.
code
string
Available, if error matches one of known error codes.

ErrorCode

The third-party server can return an Error with one of the following codes:
Error code
Description
CUSTOMER_ID_REQUIRED
Should be used when PORTOS attempts to fetch rewards without providing loyalty card id, but loyalty card is required by the third-party server.
UNKNOWN_CUSTOMER_ID
Customer loyalty card is not recognized.
REWARD_NOT_FOUND
Reward is not found.
REWARD_NOT_AVAILABLE
Reward is currently not available. E.g. current date and time does not match with Rewards ActivationDate and ExpirationDate.
REWARD_USAGE_LIMIT_EXCEEDED
The reward usage limit has been exceeded.
REWARD_CUSTOMER_USAGE_LIMIT_EXCEEDED
The reward usage limit has been exceeded for the specified customer.
INSSUFICIENT_LOYALTY_POINTS
The customer lacks sufficient loyalty points to claim the reward.

Versioning

This API uses semantic versioning. Given a version number MAJOR.MINOR, increment the:
  • MAJOR version: incompatible API changes are introduced.
  • MINOR version: functionality is added in a backward compatible manner.

Changelog

Version 1.0-beta.2 (2023-05-29)

  • Added:
    • Accept-Language header added to HTTP requests.
  • Changed:
    • RewardRule renamed to RewardCondition.

Version 1.0-beta.1 (2023-05-26)

  • Initial version.