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.

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:

Fetch available rewards
Claim reward(s)

The PORTOS system expects that responses from external system follows data format described below.

Fetch available rewards

GET {external-system}{get-rewards-url}

The PORTOS system will fetch available rewards from the external system, by initiating GET HTTP request to the external system address. External system returns response of type CustomerRewards, that contains the collection of rewards, that customer can be rewarded with.

Query Parameters

Name Type Description

Name	Type	Description
version*	string	The version of the exchange protocol. For versions 1.X, value is set to `1`.
key*	string	The API key.
customerId	string	The customer identifier. E.g. the serial number of the loyalty card, if provided by customer.

version*

string

The version of the exchange protocol. For versions 1.X, value is set to 1.

key*

string

The API key.

customerId

string

The customer identifier. E.g. the serial number of the loyalty card, if provided by customer.

Headers

Name Type Description

Name	Type	Description
Accept-Language	string	Specifies the desired localization for receiving messages from the API. E.g. `sk-SK`.

Accept-Language

string

Specifies the desired localization for receiving messages from the API. E.g. sk-SK.

{
    "customer":
    {
        "displayName": "John Doe",
        "email": "example@portos.sk",
        "points": 1281
    },
    "maxApplicableRewards": null,
    "rewards":
    [
        {
            "id": "dda658c8-7ca1-4993-9212-f1bcd992e638",
            "title": "Najlacnejšia pizza za jeden cent!",
            "description": "Získajte najlacnejšiu pizzu za jeden cent. Zľava platí pri nákupe nad 20 eur.",
            "conditions":
            [
                {
                    "purchase":
                    {
                        "minAmountIncludingVat": 20
                    }
                }
            ],
            "items":
            [
                {
                    "target": "purchaseItem",
                    "discountType": "absolute",
                    "discountAmount": 0.01,
                    "purchaseItemLookupMode": "cheapest",
                    "purchaseItemFilter":
                    {
                        "articleCategoryLabels":
                        [
                            "PIZ"
                        ],
                        "maxQuantity": 1
                    }
                }
            ]
        },
        {
            "id": "0214d09d-844f-4677-a449-829ddbf5d1cc",
            "title": "Vymeňte 1000 bodov za 5 eurovú zľavu",
            "items":
            [
                {
                    "target": "purchase",
                    "discountType": "absolute",
                    "discountAmount": 5
                }
            ],
            "priceInPoints": 1000
        }
    ]
}

{
  "message": "This is the optional message describing the error."
}

{
  "message": "A loyalty card is required for receiving rewards.",
  "code": "CUSTOMER_ID_REQUIRED"
}

Claim reward(s)

POST {external-system}{claim-rewards-url}

After the reward is confirmed by Cashier trough the PORTOS cash register system user interface, the PORTOS system will initiate the POST HTTP request to the external system, to mark reward(s) as claimed.

Query Parameters

Name Type Description

Name	Type	Description
version*	string	The version of the exchange protocol. For versions 1.X, value is set to `1`.
key*	string	The API key.

version*

string

The version of the exchange protocol. For versions 1.X, value is set to 1.

key*

string

The API key.

Headers

Name Type Description

Name	Type	Description
Accept-Language	string	Specifies the desired localization for receiving messages from the API. E.g. `sk-SK`.

Accept-Language

string

Specifies the desired localization for receiving messages from the API. E.g. sk-SK.

Request Body

Name	Type	Description
rewardIds*	string[]	Non-empty collection of claimed reward identifiers.

Name

Type

Description

rewardIds*

string[]

Non-empty collection of claimed reward identifiers.

/* No response body is required by PORTOS. */

{
  "message": "This is the optional message describing the error."
}

{
  "message": "This reward is currently not available.",
  "code": "REWARD_USAGE_LIMIT_EXCEEDED",
  "rewardId": "29e61e3b-34ae-4c1f-9bd8-f4ef9925a1f8"
}

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

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.

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

Name	Type	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.

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

Name	Type	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.

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

Name	Type	Description
`id`	`string`	Unique reward identifier.
`title`	`string`	Reward title.
`description`	`string`	Short reward description.
`conditions`	`RewardCondition[]`	Conditions that need to be fulfilled in order for the customer to claim the reward.
`items`	`RewardItem[]`	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.

id

string

Unique reward identifier.

title

string

Reward title.

description

string

Short reward description.

conditions

RewardCondition[]

Conditions that need to be fulfilled in order for the customer to claim the reward.

items

RewardItem[]

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

Name	Type	Required	Description
`purchase`	`RewardPurchaseCondition`		Optional conditions related to purchase.

purchase

RewardPurchaseCondition

Optional conditions related to purchase.

RewardPurchaseCondition

Name Type Required Description

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

minAmountIncludingVat

number

If specified, represents the minimum purchase amount required to claim the reward.

RewardItem

Single reward item.

Name Type Required Description

Name	Type	Description
`target`	`string`	One of `RewardItemTarget`.
`productFilter`	`RewardItemProductFilter`	Required, when `target` is `product`. Must be null otherwise.
`purchaseItemFilter`	`RewardItemPurchaseItemFilter`	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.

target

string

One of RewardItemTarget.

productFilter

RewardItemProductFilter

Required, when target is product. Must be null otherwise.

purchaseItemFilter

RewardItemPurchaseItemFilter

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

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.

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

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

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

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.

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

Name	Type	Description
`pluIds`	`PluId[]`	`TicketItem.Plu.Code` and `TicketItem.Plu.StockName`must 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.

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

Name	Description
`cheapest`	Prefers least expensive product, based on it's unit price.
`mostExpensive`	Prefers most expensive product, based on it's unit price.

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

Name	Type	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.

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

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.

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.

PreviousOnline orders API NextPDA Files

Last updated 9 months ago