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
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
Headers
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
Headers
Request Body
Configuration
To communicate with external system properly, the external system administrators must provide values stated below to the venue owners or PORTOS support.
Data model
The rewards API data model is described below.
All prices include taxes.
CustomerRewards
The collection of rewards available for given customer.
Customer
Information about customer.
Reward
Represents the reward.
RewardCondition
RewardPurchaseCondition
RewardItem
Single reward item.
RewardItemDiscountType
List of known discount types:
RewardItemTarget
The target that reward item applies to.
RewardItemProductFilter
Model that uniquely identifies product.
RewardItemPurchaseItemFilter
Model that selects purchase item.
PurchaseItemLookupMode
Specifies, what strategy is used to look up single purchase item among all items in purchase, that reward will be applied to.
Error models
Error
Error model received for non-2XX HTTP statuses.
ErrorCode
The third-party server can return an Error
with one of the following codes:
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 toRewardCondition
.
Version 1.0-beta.1 (2023-05-26)
Initial version.
Last updated