Liquid Barcodes Application Feed Interface JSON/REST

Introduction

The app-API allows Liquid Barcodes to distribute coupons and other content to your app and a host of additional functionality.

In order to ease the use of this API, a Postman collection can be downloaded here.

USER REGISTRATION

Before content can be distributed to the user’s app, the user must be registered. The API requires a unique and persistent ID to be created per user upon registration.

Registration with Liquid Barcodes user creation and consent handling: creating a unique user profile can be handled entirely by Liquid Barcodes, in which case you will normally have to register consent as part of the registration process.
Registration with external user creation and consent handling: If you already have a registration service, the registration to Liquid Barcodes can be done in the background without involving the user.

These two registration processes are described in detail below.

CONTENT DISTRIBUTION

Liquid Barcodes will populate a record per user with information to display in the app. Liquid Barcodes will ensure that the data in the record at all times is correct, and will remove coupons when they expire, have been redeemed etc. This record is obtained through the API using GET /content function. The record contains one or several coupons, games or surveys that are distributed as content objects (see content model below for detailed description).

Content can be presented in one or multiple locations in the app, described in detail below as sections.

Liquid Barcodes will populate each users' record based on the campaigns that have been created in Liquid Barcodes dashboard. This process is handled in its entirety in Liquid Barcodes back end.

General principles

Background

This document describes the application interface to register a user, request the user’s coupons, loyalty cards, promotions, rewards, surveys and games. The document is organized in sections to describe functionality classes, and not every functionality class may be relevant for every mobile application. They are however included to detail the fully fledged functionality, but may not be present in the actual implementation for this particular purposes. The full functionality of the practical implementation has to be agreed with Liquid Barcodes before using the services provided.

Nomenclature

A user is an end customer that is using the application.

A coupon gives user right to a financial discount or rebate when purchasing a product. A coupon can take many forms, such as single use rebate coupons, loyalty cards, reward coupons, limited coupons etc. All these should be treated equally by the app.

HTML based content is some content that is displayed in the in-app web browser, for example games, surveys and weblink images. Common to all these content types is that user is presented with an image that works like a button to open the HTML content.

Shop offer: a content object that end users can buy. Purchasing these items will trigger issue of related content, eg. coupons or gift card balance top up.

Preferred API format and HTTP Headers

The preferred content type for the requests that are being sent to LIQUID is JSON. For every function call the following parameters are always
placed in the HTTP header:

X-Liquid-Timestamp – datetime in ISO-8601 format. e.g. 2014-03-06T13:11:04+03:00. Time should be in UTC
X-Liquid-Signature – signature calculated in the manner described above

Signature

The Application ID and the security details are available on request. This API relies on the use of SHA-2 256 hash signatures with all mandatory
parameters + an API key unique to the customer. It is important to make efforts to obfuscate this key in the app implementation.

Let's say we have agreed upon the API key "wild-e-coupon". Then, the source for the checksum would be "abcd" + "1234" + "wild-e-coupon".
The correct checksum would be:

SHA-2 256("2014-03-07T11:07:21+01:00abcd1234wild-e-coupon")
= 800226d761b1bfe2248f68a353f73e720ab9322408dff29f50ed2dba223432e2

Each service specification below will detail how to build the source for the checksum, that is, which parameters and the order in which they should
be concatenated.

JSON

Example (pseudo) service call:

{ "DateTimeHeader": "2014-03-07T11:07:21+01:00" "parameter_a": "abcd", "parameter_b": "1234", "signature": "1aaade12efceba0f9ddda4a94bce59a6" }

General Disclaimer

This document describes the interface to get the relevant content (coupons, games, survey etc.) for a unique user and application. In order to utilize this interface there must be a commercial agreement with Liquid Barcodes in place. In all circumstances the IPR of the interface resides with Liquid Barcodes. Liquid Barcodes reserves the right to change this interface at any moment. Any implementation that utilizes this interface is the sole responsibility of the implementer, and under no circumstances should the issuing of this document be construed to signify that Liquid Barcodes will participate with the implementation, testing, verification of the implementation, unless otherwise agreed.

Liquid Barcodes requires external app developers (2nd or 3rd party) to follow guidelines for handling our API key. Technical instructions will be sent directly to the app developer. Liquid Barcodes App API includes best effort checks to detect unusual/abusive operations and minimize impact in case an API key should still be exposed.

Register user – Liquid Barcodes user creation & consent handling

If you do not already register customers on your side including correct consent handling, you must register user with consent in Liquid Barcodes system.

The application identifies itself/the user in a two stage process, which is normally only carried out once. However the LIQUID services has the ability to force a re-registration either explicitly (hard) or implicitly (silent).

The high-level registration process is described and illustrated below (click images to enlarge):

Execute POST /initialize

The application identifies itself with a unique and persistent ID. As a response it is given a temporary UserId from the system that it is to use in all future function calls to this API and an array of consents.

Consent handling. The API supports two types of consents: Master consents and Non-master consents. Master consent is identified through the consent situation model parameter Name= ‘Master’. User should accept Master consent on registration. As a minimum, user should be presented with the consent model title and link to Privacy policy text. Both texts are provided through the API.
Age restrictions. App is responsible for verifying user’s age, either by collecting date of birth or presenting user with active consent mechanism (eg. toggle button or check box) and MinimumAgeText. User registration cannot be completed if DateOfBirth < MinimumAge.
Texts can be provided as HTML converted from markdown.

Execute POST /pin

After age verification and consent accept, the application calls this API again with a unique user identificator (normally phone number, but it may also be e-mail or in the response to this function call) together with the temporary UserID. The user is then sent a PIN on SMS (or email if that is preferred)

Execute POST /user

The application calls this API with the unique temporary UserID, the received PIN code and consent accept (including age information). In addition, other information about the user may be added. Upon verification from the system that the UserID and PIN matches, the application gets a final UserID. The final UserID is either the same as the temporary UserID (user has never registered before) or a new UserID (in the case where the user has previously registered). The function returns the processed user model (see The User model).

If still missing user information, execute PUT /user

If some mandatory user information is required for the application, and this was not provided with the POST /user call this should be updated to complete the registration process. This will typically involve granular consents:

Non-master consents provide options for granular consents that can be handled after the main registration process or on ‘My page’. We advice to present users with all granular consents on one page. Present consent model title and link to consent model description.

It is important to note that several application instances can share the same UserID, if a particular user installs and register the application on several phones (as long as he has access to the phone that gets the PIN).

Note: store the UserID locally, not in clear text.

Consent update

The API supports breaking and non-breaking changes. If a breaking change to either the Master consent or the Granular consents is introduced, users should accept the new consent texts.

The API may provide change description for each consent update back to previous accepted consent version. Note that there may be several new versions and corresponding change log texts for one user.

Master consent

Breaking changes on Master consent will block the app from getting content until new consent has been accepted. Prompt user with updated consent version to restore app functionality. The app should check for, at regular intervals eg. daily, and warn user about non-breaking changes to Master consent. In case of non-breaking changes, the state in the Consent situation model will be set to 'ConsentRenewalRequired' for the Master consent. Use GET /user to retrieve updated consent texts.

Granular consents

User can continue to use the app even if there is a breaking change to one or multiple granular consents. The app should check for, at regular intervals eg. daily, and warn user about any changes to Non-master consents. If change is identified, give user option to renew consent. In case of changes to the granular consents, the state in the Consent situation model will be set to 'ConsentRenewalRequired' for the applicable consent(s). Use GET /user to retrieve updated consent texts.

Register user - external user creation & consent handling

If you already register customers on your side with a unique and persistent ID for each individual user and correct consent handling, you can perform a simpler registration process that can be done silently to the end user. We call this Foreign Id Mode.

Important note: using this registration method it is the caller’s responsibility to handle all consents and management of the user’s data, and for ensuring user identity uniqueness and persistence. Not all Liquid Barcodes features are available in foreign id mode.

It is important that the registration is done through the caller’s back end and not by the mobile application itself.

The main steps in this registration flow are:

Register user and consent in your system and create a unique and persistent UserID
Register user in Liquid Barcodes system by posting your UserID using the POST /user request. POST /initialize and POST /pin requests should not be used in Foreign Id Mode.
You are now ready to use your own UserId with App API functional requests.

Note: Liquid Barcodes data reports use LB internal UserIDs, except the following exceptions that will user Foreign Id in case that users are registered using this mode:

CouponIssueReport
CouponValidationReport
ShopTransactionReport
ShopSettlementReport
MembersReport (LB internal UserIDs is used but ForeignId is in ExternalIdentifiers column)
BlockedMembersDataReport (LB internal UserIDs is used but ForeignId is in ExternalIdentifiers column)

Manage and edit user

To update user information, use the PUT /user function. You can update all information about the user except the unique user identificator used to identify each user (usually phone number).

For GDPR compliance, in the User model Liquid Barcodes provides link to our generic My page. The link is dynamic and unique for each user. Make sure to link to this page in your app to fulfill all GDPR requirements.

User rights

The API provides basic account information and a link to advanced ‘My page’ solution. Make sure to link to this ‘My page’ solution to ensure full compliance with user rights under GDPR. Expect the ‘My page’ link to be unique and dynamic for each user.

Customer user groups

Customers can reveal their preferences by joining customer user groups. All available groups and the user's status are presented in GET /user. Groups can be free opt in, require code, or not editable. The presentation of the list of groups in the app should be dynamic to allow for future changes to the groups.

Select preferred store(s)

Use this flow to let users to select their preferred stores to get local offers and regional offers.

User models

These models are used by various requests related to user registration and user management.

The User model

It contains all the user information about each user available to the app.

Parameter	Description
UserId stringRequired	For new users the UserId will match the UserId from the request. For returning users the UserId will be the UserId previously associated with the MSN.
Msn stringRequired	User's mobile number. Formatted using country code (without `+` symbol) and digits only. For example: if country code is `+1` and phone number is `987654321`, field value will be `1987654321`.
Name stringOptional	Name of the user.
Surname stringOptional	Surname of the user.
Address stringOptional	Address of the user.
PostCode stringOptional	User's zip code
DeviceId stringOptional	User's device identificator.
City stringOptional	User's city of residence
Emails array of stringOptional	Array of user's preferred e-mail.
DateOfBirth stringOptional	User's date of birth in ISO-8601 format (yyyy-mm-dd).
Gender stringOptional	User's gender specified as M or F.
PreferredStores array of integerOptional	List of user's preferred store(s) based on their interaction with the system. This is a JSON array of stores listed in most preferred store first. Must use the same Id as listed in GET /stores response. A store can be present in both PreferredStores (set by the system) and SelectedPreferredStore (selected by the user).
SelectedPreferredStores array of integerOptional	List of user's selected preferred store(s). This is a JSON array of stores listed in most preferred store first. Must use the same Id as listed in GET /stores response. A store can be present in both PreferredStores (set by the system) and SelectedPreferredStore (selected by the user)
UserGroups array of objectOptional	Array of userGroups for this user.
GroupId stringRequired	A unique identifier for this group.
GroupDescription stringRequired	A human readable description to be displayed to the user.
IsUserMember booleanRequired	If true, the user is part of the group. If false, the user is not part of the group.
UserConfigurable stringRequired	I can take one of the following values: 'NotConfigurable' - The user cannot toggle membership him/herself 'Configurable' - The user is allowed to change the group membership status him/herself 'CodeConfigurable' - The user is allowed to change the group membership status him/herself but it requires an additional code to be entered by the user in the app Additional values may be added in the future, and unrecognized values should take 'NotConfigurable' as default.
RegistrationDate stringRequired	ISO 8601 date/time that indicates when the user was registered. The registration date/time is given in UTC.
Culture stringOptional	Indicates the users culture / language. Must be one of the values from the GET/ languages service. Values follow RFC 4646.
ReferralCode stringOptional	Referral code that user can share with friends and family. If these register and provides the referral code, a reward is triggered to referrer and referee. Populated if configured for customer, empty otherwise. 6 alphanumeric characters, unique per user. Uppercase letters.
Consents array of objectRequired	Array of consents (see Consent situation model) that is applicable for this user to use this application. Any Mandatory consents must be displayed and approved by the user before POST /user call. If user was registered with 'Register user - external user creation & consent handling', the consent handling is the responsibility of the calling party and this section will be empty.
UserMyPage stringRequired	Link to HTML page with advanced settings (including historic data for the user). If user has Msn, PIN to enter into page will be sent by sms. Otherwise, if user has Email, PIN to enter into page will be sent by Email. If both Msn and Email are empty, empty string is returned in UserMyPage parameter.
PaymentMethods array of objectOptional	Array of payment methods this user currently has registered.
Id integerRequired	Payment method ID.
Title stringRequired	Descriptive title that should be shown to the user, for example "MasterCard ending in 1234".
PlateNumber objectOptional	Plate Number description.
Id integerRequired	Id of a plate number.
PlateNumber stringRequired	Plate number.
Title stringRequired	Title for a plate number.
ExternalIdentifiers array of objectOptional	Array of external identifiers that are applicable to this user. If external identifiers are not preset in LB system - ExternalIdentifiers are populated only if user has value set. If any external identifier is preset in LB system - all of those configured external identifiers are returned. Even if User has not populated identifier.
Identifier stringOptional	String that represents external identifier.
Type stringRequired	Type of the identifier. Supported types: MacauPass CitizenID LoyaltyID PumaFastPayID
Name stringRequired	A human readable localized name of Identifier to be displayed for the user.
Subscriptions array of objectRequired	Array of user’s subscriptions. If no subscription - empty array will be returned.
PlanName stringRequired	Name of the Subscription Plan, e.g. "Car wash Gold"
SubscriptionId integerRequired	Id of the subscription.
SubscriptionState stringRequired	State of the Subscription, it can be: Active Downgrading Cancelled
ContentId integerRequired	ContentId associated with this subscription (it can be changed).
IsMultiUserPlan booleanRequired	True if plan allow to have extra users, otherwise false.
MaxUsersAmount integerRequired	Max number of extra users for subscription (we don't count subscription owner here).

The Consent model

The fields that make up a specific consent revision. It is used by the Consent situation model below, which is in turn used by the appfeed services.

Parameter	Description
Id integerRequired	The consent Id is an immutable ID for the version, any change in the consent text would mean a new ConsentId (even if the change is so minor that the ConsentVersion hasn't changed).
Title stringRequired	Localized / descriptive name.
Version stringRequired	This is a human readable consent version number of the latest valid consent.
Description stringRequired	The exact consent text that the user is consenting too.
PrivacyPolicyTitle stringOptional	Localized / descriptive name for the privacy policy.
PrivacyPolicy stringOptional	The privacy policy text for the current consent version for the entire service.
DefaultState booleanRequired	If true, it means this consent can be checked as approved when presenting it to the user for the first time.
RevokeWarningText stringOptional	A text that must be shown to the user when trying to revoke this consent.
MinimumAge integerOptional	The minimum age of user to use this app. Given as a number of years.
MinimumAgeText stringOptional	The text that is provided to indicate 'This app requires that you are X years or older'. This text must be shown to the user and she must either set a toggle to True or confirm by setting their birthdate. If the user did not confirm his age then this consent cannot be confirmed.

The Consent situation model

This model describes the current situation for all relevant consents, including what the user has approved and what he needs to approve.

Parameter	Description
Name stringRequired	A value to indicate the consent type. The following values are defined for all applications: 'Master', 'Location', 'Push notification'
State stringRequired	The current state of this consent name for this user. It can take the following values: 'NoConsent' - No consent has every been given for this consent name 'ConsentGiven' - The user has given his consent for the ConsentId/Version details in LastApproved 'ConsentRevoked' - The user has given but since revoked his consent 'ConsentRenewalRequired' - The user has given his consent for the ConsentId/Version details in LastApproved, but a renewal of the consent is required to use this part of the service
Mandatory booleanRequired	If true the user must consent to or renew this consent for the app to work, if the user hasn't already given his consent. If the user wants to revoke a mandatory consent, this will mean that the user opts out of the entire service. If false, this particular consent is not required for the service to work.
LastApproved objectRequired	Consent object (see Consent model). The last revision the user has approved (may be revoked) of this consent name. If the user has never approved this will be null / not present.
CurrentVersion objectRequired	Consent object (see Consent model). The current / latest revision of this consent.
ChangeLog array of objectOptional	Array of change log from the last approved consent version to the current version.
Id integerRequired	The exact consent version as an Id.
Version stringRequired	The consent version in a human readable form.
Text stringRequired	A textual description of the changes that was introduced with this particular version from the previous Consent version.

User methods

This section contains all methods needed for user registration, management and edition.

POST /initialize

This is the first service to be called for a uninitialized app instance. This function call is normally only done initially, or when the user has logged out.

Request

The service expects the following parameters as part of the JSON body:

Parameter	Description
DeviceId stringRequired	A unique identifier for the device that as far as possible is persistent when the user logs in after having a) logged out, b) deleted and re-installed the app, and c) done a factory reset (if possible). This identifier is used to prevent fraud by setting limitations on the number of times a user can use the same device with different MSNs.
Culture stringOptional	Indicates the users culture / language. Only values present in GET /languages service are accepted. Values follow RFC 4646. This feature is only used if your app supports more than 1 language.

The signature is calculated as a SHA-2 256 checksum using string source from the following concatenated parameters:

DateTime (HTTP header)
DeviceId
Your secret API Key

Successful Response

A successful call will return a HTTP 200 OK response code and the following JSON object in response body:

Parameter	Description
UserId stringRequired	A randomly created user ID. The app should store this UserId for use with the following service calls.
Consents array of objectRequired	Array of consents (see Consent situation model) that is applicable for this user to use this application. Any Mandatory consents must be displayed and approved by the user before POST /user call.
MsnPrefixWhitelist array of stringRequired	It's a list of MSN prefixes allowed to use in this app. App developers should use it to show only supported MSN prefixes.

POST /pin

Before a user can be registered he must order a PIN to his mobile number to confirm he is the owner of that mobile number. The users PIN must then be used as with the POST /user service to register a new user.

Request

The service expects the following parameters as part of the JSON body:

Parameter	Description
UserId stringRequired	The unique and persistent ID that identifies the user that is being registered.
Msn stringRequired	Mobile number where the PIN will be sent. It should be sent using country code (without `+` symbol) and digits only. For example: if country code is `+1` and phone number is `987654321`, field value will be `1987654321`. By default, only the prefix of customer's country will be allowed (SMS will not be sent to other prefixes). Please contact us to whitelist additional prefixes.

The signature is calculated as a SHA-2 256 checksum using string source from the following concatenated parameters:

DateTime (HTTP header)
UserID
Msn
Your secret API Key

Successful Response

A successful call will return a HTTP 200 OK response code and the following JSON object in response body:

Parameter	Description
Status stringRequired	Pin order status. It can take the following values: SmsSent: A new SMS has been sent. PinOnItsWay: SMS has not been sent; 3 SMS messages has already been sent to the user before.

POST /user

Registers a new user profile and returns the users UserId. In case of returning users that needed to re-register, their previously UserId will be returned. The mobile app must then replace it's UserId.

Request

The service expects the following parameters as part of the JSON body:

Parameter	Description
UserId stringRequired	A unique and persistent ID that identifies the given User. For Register user – Liquid Barcodes user creation & consent handling process, `UserId` is assigned by Liquid Barcodes and given in POST /initialize response. For Register user - external user creation & consent handling process, `UserId` must be created by you.
Pin stringOptional	Users PIN code (see POST /pin). Pin is required for Register user – Liquid Barcodes user creation & consent handling process.
Msn stringOptional	The MSN of the user. It should be sent using country code (without `+` symbol) and digits only. For example: if country code is `+1` and phone number is `987654321`, field value will be `1987654321`. In case that user already exists: If this parameter is not present or null, current data will be unchanged. If empty string, current data will be removed.
Name stringOptional	Name of the user. In case that user already exists: If this parameter is not present or null, current data will be unchanged. If empty string, current data will be removed.
Surname stringOptional	Surname of the user. In case that user already exists: If this parameter is not present or null, current data will be unchanged. If empty string, current data will be removed.
Address stringOptional	Address of the user. In case that user already exists: If this parameter is not present or null, current data will be unchanged. If empty string, current data will be removed.
PostCode stringOptional	User's zip code. In case that user already exists: If this parameter is not present or null, current data will be unchanged. If empty string, current data will be removed.
City stringOptional	User's city of residence. In case that user already exists: If this parameter is not present or null, current data will be unchanged. If empty string, current data will be removed.
Emails array of stringOptional	List of user's preferred e-mails. In case that user already exists: If this parameter is not present or null, current data will be unchanged. If empty array, current data will be removed.
DateOfBirth stringOptional	Users date of birth in ISO-8601 format (yyyy-mm-dd). If there is a consent that requires a minimum user age, this field is mandatory. In case that user already exists: If this parameter is not present or null, current data will be unchanged. If empty string, current data will be removed.
Gender stringOptional	User's gender specified as 'M' or 'F'. In case that user already exists: If this parameter is not present or null, current data will be unchanged. If empty string, current data will be removed.
SelectedPreferredStores array of integerOptional	List of the user's selected preferred store(s). This is a JSON array of stores listed in most preferred store first. Must use the same StoreId as available in Stores section of this document. In case that user already exists: If this parameter is not present or null, current data will be unchanged. If empty array, current data will be removed.
Culture stringOptional	Indicates the users culture / language. Must be one of the values from the GET/ languages service. Values follow RFC 4646. In case that user already exists: If this parameter is not present or null, current data will be unchanged. If empty string, current data will be removed.
ReferralCode stringOptional	Referral code that user can share with friends and family. If these register and provides the referral code, a reward is triggered to referrer and referee. Populated if configured for customer, empty otherwise. 6 alphanumeric characters, unique per user. Uppercase letters.
ApprovedConsents array of integerOptional	A list of approved consent IDs.
RevokedConsents array of integerOptional	A list of revoked consent IDs. Note: first we will revoke any sent consents and then only add any approved.
ExternalIdentifiers array of objectOptional	Array of external identifiers that are applicable to this user. In case that user already exists: If array is null no changes will be done to existing external identifiers. If array is not null - existing external references will be rewritten with the new list (identical to existing identifiers won't be changed (identifier+type)).
Identifier stringRequired	String that represents external identifier.
Type stringRequired	Type of the identifier. Supported types: MacauPass. CitizenID LoyaltyID PumaFastPayID

The signature is calculated as a SHA-2 256 checksum using string source from the following concatenated parameters:

DateTime (HTTP header)
UserID
Pin
Your secret API Key

Successful Response

A successful call will return a HTTP 200 OK response code and the current user model JSON object in response body.

GET /user

Gets a user profile.

Request

The service expects the following parameters as part of the URL query-string:

Parameter	Description
UserId stringRequired	The unique and persistent ID that identifies the user whose profile is requested.

The signature is calculated as a SHA-2 256 checksum using string source from the following concatenated parameters:

DateTime (HTTP header)
UserId
Your secret API Key

Successful Response

A successful call will return a HTTP 200 OK response code and the current user model JSON object in response body.

PUT /user

Updates a user's profile data.

Request

The service expects the following parameters as part of the JSON body:

Parameter	Description
UserId stringRequired	The unique and persistent ID that identifies the user whose profile data will be updated.
Msn stringOptional	The MSN of the user. It should be sent using country code (without `+` symbol) and digits only. For example: if country code is `+1` and phone number is `987654321`, field value will be `1987654321`. Note: If this parameter is not present or null, current data will be unchanged. If empty string, current data will be removed.
Name stringOptional	Name of the user. Note: If this parameter is not present or null, current data will be unchanged. If empty string, current data will be removed.
Surname stringOptional	Surname of the user. Note: If this parameter is not present or null, current data will be unchanged. If empty string, current data will be removed.
Address stringOptional	Address of the user. Note: If this parameter is not present or null, current data will be unchanged. If empty string, current data will be removed.
PostCode stringOptional	User's zip code. Note: If this parameter is not present or null, current data will be unchanged. If empty string, current data will be removed.
City stringOptional	User's city of residence. Note: If this parameter is not present or null, current data will be unchanged. If empty string, current data will be removed.
Emails array of stringOptional	List of user's preferred e-mails. Note: If this parameter is not present or null, current data will be unchanged. If empty array, current data will be removed.
DateOfBirth stringOptional	Users date of birth in ISO-8601 format (yyyy-mm-dd). Note: If this parameter is not present or null, current data will be unchanged. If empty string, current data will be removed.
Gender stringOptional	User's gender specified as 'M' or 'F'. Note: If this parameter is not present or null, current data will be unchanged. If empty string, current data will be removed.
SelectedPreferredStores array of integerOptional	List of the user's selected preferred store(s). This is a JSON array of stores listed in most preferred store first. Must use the same StoreId as available in Stores section of this document. Note: If this parameter is not present or null, current data will be unchanged. If empty array, current data will be removed.
Culture stringOptional	Indicates the users culture / language. Must be one of the values from the GET/ languages service. Values follow RFC 4646. Note: If this parameter is not present or null, current data will be unchanged. If empty string, current data will be removed.
ApprovedConsents array of integerOptional	A list of approved consent IDs.
RevokedConsents array of integerOptional	A list of revoked consent IDs. Note: first we will revoke any sent consents and then only add any approved.
ExternalIdentifiers array of objectOptional	Array of external identifiers that are applicable to this user. Note: If array is null no changes will be done to existing external identifiers. If array is not null - existing external references will be rewritten with the new list (identical to existing identifiers won't be changed (identifier+type)).
Identifier stringRequired	String that represents external identifier.
Type stringRequired	Type of the identifier. Supported types: MacauPass. CitizenID LoyaltyID PumaFastPayID
UserGroups array of objectOptional	Array of userGroups that is applicable to this user.
GroupId stringRequired	A single word tag for this group. Only tags that have been fetched through GET /user is accepted.
IsUserMember booleanRequired	If true, the user is to join/is joined. If false, the user is to quit/has quit the group in question.
UserCode stringOptional	Provides a needed code to verify the change of status if UserConfigurable = 'CodeConfigurable'. Blank otherwise.
PlateNumber objectOptional	Plate Number description.
Id integerRequired	Id of a plate number. If a new plate number - use 0.
PlateNumber stringRequired	Plate number.
Title stringRequired	Title for a plate number.

The signature is calculated as a SHA-2 256 checksum using string source from the following concatenated parameters:

DateTime (HTTP header)
UserID
Your secret API Key

Successful Response

A successful call will return a HTTP 200 OK response code and the current user model JSON object in response body.

DELETE /user

Deletes a user profile.

Request

The service expects the following parameters as part of the URL query-string:

Parameter	Description
UserId stringRequired	The unique and persistent ID that identifies the user that will be deleted.

The signature is calculated as a SHA-2 256 checksum using string source from the following concatenated parameters:

DateTime (HTTP header)
UserId
Your secret API Key

Successful Response

A successful call will return a HTTP 200 OK response code.

GET /languages

Lists the possible languages / cultures the user can select in this app.

Request

The service has no arguments but the standard headers.

The signature is calculated as a SHA-2 256 checksum using string source from the following concatenated parameters:

DateTime (HTTP header)
Your secret API Key

Successful Response

A successful call will return a HTTP 200 OK response code and a JSON object built with the following key - string value pairs that represent available languages in response body:

Key: IETF RFC 4646 language tag.
String value: language name.

An example is shown in code section at the right side of this page.

Keys returned in this dictionary are the valid alternatives that can be set in Culture field of the following services:

POST /user
PUT /user

JSON

Response body example:

{
"de-DE": "German (Germany)",
"en-GB": "English (Great Britain)"
}

Points program

Services for managing points programs.

GET /points-program/{UserId}/log/points

This method returns all historical transactions of earned, used and expired points.

Request

The service expects the following parameters as part of the URL path:

Parameter	Description
UserId stringRequired	The unique and persistent ID that identifies the user which points log is requested for.

The signature is calculated as a SHA-2 256 checksum using string source from the following concatenated parameters:

DateTime (HTTP header)
UserId
Your secret API Key

Successful Response

A successful call will return a HTTP 200 OK response code and the following JSON object in response body:

Parameter	Description
LogData array of objectRequired	An array of log records.
Type stringRequired	Points event type. Possible values: Earned Used Expired
Timestamp stringRequired	ISO 8601 formatted event datetime in UTC
PointsChange numberRequired	Amount of points change (also includes bonus points if any).
BonusPoints numberOptional	Amount of bonus points received.
NewBalance numberRequired	New giftcard balance after event.
Description stringRequired	Description of an operation.
ExpirationDate stringOptional	ISO 8601 formatted datetime when issued points would be expired.
ReceiptId stringOptional	ID of the receipt if points have been earned based on purchase in store.
StoreId integerOptional	ID of the store if points have been earned based on purchase in store.

GET /points-program/{UserId}/history/points

This method returns historical data on points balance and transactions for a specific user in the indicated period.

Request

The service expects the following parameters as part of the URL path:

Parameter	Description
UserId stringRequired	The unique and persistent ID that identifies the user which points history is requested for.

The service expects the following parameters as part of the URL query-string:

Parameter	Description
PeriodType stringRequired	Type of requested period. Valid values are: Days Months
PeriodsNumber integerRequired	An integer determining the length of the points history time series. For example 3 will return data for current period and previous 3 periods.

The signature is calculated as a SHA-2 256 checksum using string source from the following concatenated parameters:

DateTime (HTTP header)
UserId
Your secret API Key

Successful Response

A successful call will return a HTTP 200 OK response code and the following JSON object in response body:

Parameter	Description
Data array of objectRequired	An array of records for each period in the report.
PeriodType stringRequired	Type of requested period. Valid values are: Days Months
PointsBalance numberRequired	Total points balance at the end of period.
Timestamp stringRequired	ISO 8601 formatted datetime that indicates the start date of the period.
Earned numberRequired	Number of points earned in the period.
Used numberRequired	Number of points used in the period.
Expired numberRequired	Number of points expired in the period.

GET /points-program/{UserId}/history/store-activity

This method returns historical data organized in the way that it can be used to build visualizations and customer information.

Request

The service expects the following parameters as part of the URL path:

Parameter	Description
UserId stringRequired	The unique and persistent ID that identifies the user which visits and spend history is requested for.

The service expects the following parameters as part of the URL query-string:

Parameter	Description
PeriodType stringRequired	Type of requested period. Valid values are: Days Months
PeriodsNumber integerRequired	An integer determining the length of the points history time series. For example 3 will return data for current period and previous 3 periods.

The signature is calculated as a SHA-2 256 checksum using string source from the following concatenated parameters:

DateTime (HTTP header)
UserId
Your secret API Key

Successful Response

A successful call will return a HTTP 200 OK response code and the following JSON object in response body:

Parameter	Description
Data array of objectRequired	An array of records for each period in the report.
PeriodType stringRequired	Type of requested period. Valid values are: Days Months
Timestamp stringRequired	ISO 8601 formatted datetime that indicates the start date of the period.
MoneySpent numberRequired	The amount of money spent in this period.
Visits integerRequired	The number of visits in stores in this period.

GET /points-program/{UserId}/tier-status

This method returns required conditions to upgrade to the next tier and current status.

Request

The service expects the following parameters as part of the URL path:

Parameter	Description
UserId stringRequired	The unique and persistent ID that identifies the user which tier status is requested for.

The signature is calculated as a SHA-2 256 checksum using string source from the following concatenated parameters:

DateTime (HTTP header)
UserId
Your secret API Key

Successful Response

A successful call will return a HTTP 200 OK response code and the following JSON object in response body:

Parameter	Description
CurrentTierId integerRequired	Id of the user's current tier.
CurrentTierName stringRequired	Name of the user’s current tier.
NextTierId integerRequired	Id of the next tier.
NextTierName stringRequired	Name of the next tier.
RollingDaysPeriod integerOptional	The number of days in the current counted period.
Conditions array of objectRequired	A list of conditions required for the next tier.
ConditionType stringRequired	The type of condition. Valid values are Visits Points MoneySpent
RequiredValue numberRequired	The threshold value required to be promoted to next tier.
CurrentValue numberRequired	User’s current value. `RequiredValue` minus `CurrentValue` is the additional number of ‘Visits’, ‘Points’ or ‘MoneySpent’ user must obtain to be promoted.
DegradationDate stringOptional	This parameter will only be available for Tier logic v2 and if user's activity in the current period does not qualify for the current Tier.

GET /points-program/{UserId}/history/issues

This method returns a history of issued points including their expiration dates.

Request

The service expects the following parameters as part of the URL path:

Parameter	Description
UserId stringRequired	The unique and persistent ID that identifies the user which points issues history is requested for.

The signature is calculated as a SHA-2 256 checksum using string source from the following concatenated parameters:

DateTime (HTTP header)
UserId
Your secret API Key

Successful Response

A successful call will return a HTTP 200 OK response code and the following JSON object in response body:

Parameter	Description
IssuedPoints array of objectRequired	An array of issue records.
Timestamp stringRequired	ISO 8601 formatted points issue datetime in UTC.
PointsChange numberRequired	Amount of points change (also includes bonus points if any).
BonusPoints numberOptional	Amount of bonus points received.
RuleName stringRequired	Name of the triggered rule.
ExpirationDate stringRequired	ISO 8601 formatted datetime when issued points would be expired.
ReceiptId stringOptional	ID of the receipt if points have been earned based on purchase in store.
StoreId integerOptional	ID of the store if points have been earned based on purchase in store.

POST /points-program/points/share

This method allows points sharing with another registered user.

Request

The service expects the following parameters as part of the JSON body:

Parameter	Description
UserId stringRequired	The unique and persistent ID that identifies the user which is the current owner of the points that will be shared.
PointsAmount numberRequired	The amount of points to share.
FriendUserRef stringRequired	The unique user reference to the friend that the user wants to give points to. Usually, this is the phone number of the friend (MSN). In that case, it should be sent using country code (without `+` symbol) and digits only. For example: if country code is `+1` and phone number is `987654321`, field value will be `1987654321`.

The signature is calculated as a SHA-2 256 checksum using string source from the following concatenated parameters:

DateTime (HTTP header)
UserID
PointsAmount
Your secret API Key

Successful Response

A successful call will return a HTTP 200 OK response code.

Content management

In most cases, the main content of the app is obtained through the GET /content request. It gives the app access to each users unique content record that can contain coupons, games and/or surveys.

Liquid Barcodes content is organized in a hierarchy, the app should follow this hierarchy and not tamper with the organization or order content is sent to the app:

Request: GET /content gives access to all users coupon, game and survey content, presented in the content model form.
Sections: The content is grouped into sections. Your app may have only one section or multiple sections. Each section should correspond to a designated are in the app where Liquid Barcodes content is displayed, eg. an 'Offers room'.
Content objects: within each section, there can be none, one or multiple content objects. These may be Coupon content or HTML content. The app must be able to handle these two, and only these two, content types. Present the content in the same order as they appear in the API.
Content model: the structure of each content object is described in the content model.

Some general content guidelines:

Add a refresh button to allow the user to update content. As a minimum, this should force a refresh of all content for this content object.
Update images based on HTML headers.
Make it possible to share coupons if the coupon is shareable (LB defines shareable or not)
Make sure to use the various information according to its intention (e.g. the parameter BackUrl should be placed on the backside of the coupon)
The app should not filter or alter the order of content obtained through content requets such as Get Content or Get ShopOffers requests

OFFLINE HANDLING

In order to improve the user experience, it is suggested to have a graceful offline caching. Cache data locally to ensure app functions even without internet connection. Do not delete cache on device if in offline mode or no response from server. The app should work without connection (albeit with limited functionality).

All image URLs that is returned contains the form https://www.domain.com/path/filename.extension?v=guid. Whenever an image changes the URL will also change (possibly the filename, but always the GUID). Thus an image change will result in a new and unique URL. Any device/app caching mechanisms used must miss and load the image for such new and unique URLs.

Sections

All coupon objects are structured in groups called sections.

When setting up a campaign the retailer will define which section the content should be assigned to. All content types can appear in all sections, provided that the app supports this.

Each section should be displayed in its entirety in one designated space in the app. One app may contain one or several such spaces, depending on your requirements, with one corresponding section per space. The number of Sections can be configured to your needs.

However the content in each section should be kept together in the order specified by the section.

Coupon content

Designated Type=Coupon in the Content model. Use coupon handling as fallback method to present any unknown content in the GET /content response.

Coupon content are typically coupons, loyalty cards or similar items where the purpose is to give the user a discount in store. Coupon objects consist of a series of elements that should be presented in this way:

The TopImageUrl will always be present, but any or all of the remaining parameters may be empty. The app should be robust and display the coupon regardless of which parameters are present. The app must handle images that are too small or too large (aspect ratio not optimal for current screen size).

Activate content

HTML content

Designated Type=HTML in the Content model.

HTML content is content that requires the app to open in-app browser. There are two key elements:

an image that works like a button: When user clicks the image, open the unique content link. Designated TopImageUrl in the Content model.
content link: the URL that is to be opened in the in-app browser. Designated ContentUrl in the Content model.

Make sure to test the app with various types of HTML content before releasing to customers.

Content model

The content object is used in a several places and has two different states:

Activated, this means that the content has already been issued either by a user action or because the underlying campaign automatically issues the content to the user
Not yet activated, is currently not implemented

Parameter	Description
ScheduleId integerRequired	LIQUID Barcodes' internal Schedule identifier.
ContentId integerOptional	Required if content is issued. LIQUID Barcodes content identifier. NOTE: The content identifier is only unique in scope of the content type (coupon, survey, game, ...). I.e. a game and a survey may, in theory, share the same ID. NOTE: For content that is shared by multiple users, for example web links, the ContentId may be 0 / zero.
TopImageUrl stringOptional	URL to the top image part of the content. Either TopImageUrl or ContentUrl has to be present.
TopText stringOptional	Not present if content is not issued. Top text for the coupon which can be 1-3 lines of text. The most common use of this parameter is the text "Valid to ...", but it can have other information as well. This is used if the the app builds the complete coupon itself, otherwise this is optional
BarcodeUrl stringOptional	Not present if content is not issued. Url to the barcode proper. This will have a small white border around it.
BottomText stringOptional	Not present if content is not issued. Bottom text for the coupon.
BottomImageUrl stringOptional	Not present if content is not issued. URL to a bottom image of a coupon.
BackUrl stringOptional	If present this points to an image to present on the back side of the content.
BackMarkup stringOptional	Content in markup language (for example HTML) that should be shown on the back side of the content. If present, should be used instead of BackUrl fields.
ThumbUrl stringOptional	If present this points to an smaller representation of the content to be used in an overview display
ContentUrl stringOptional	Not present if content is not issued. If content is a HTML based content, this URL is to be opened in the in-app browser. Either TopImageUrl or ContentUrl has to be present
BackgroundColour stringOptional	If present this represents a background colour to use with this coupon. The background colour is represented in #AABBCC notation
Type stringRequired	Content type: Coupon HTML (this is a link to an HTML page) If the app feed returns an unknown or unrecognized app type the application should default back on the Coupon type
Description stringOptional	The content description.
DescriptionMarkup stringOptional	The content description in a markup language (for example HTML). If has value should be used instead of Description field
SubText stringOptional	Not present if content is not issued. A short text to present with the content image.
AmountLeft integerOptional	If this content has a limited amount of validations, the remaining count is given here. A value of 0 means that no further validations will be possible. If this parameter is not in use the value is empty
ExpiryDate stringRequired	ISO 8601 time/date after which the content will be expired. The expiration date/time is given in UTC
IssueDate stringRequired	ISO 8601 time/date when the content has been issued. The issue date/time is given in UTC
RatingsCategory objectOptional	The rating category to use.
Id integerOptional	The Id of the Rating category.
Name stringOptional	The name of the Rating category (e.g. COFFEE).
ShareType stringOptional	Can take the values ''NotSharable', 'Shareable' or 'ShareAndCare'. If not present then content is not shareable
ValidForStore integerOptional	Not present if content is not issued. If the content can only be used in one particular store, this field has the StoreId value of this store
ValidForStoreTags array of integerOptional	A list of all the storeTagIDs where this content can be used. The StoreTags can be resolved to a list of stores. It is up to the app to decide how to display this to the consumer
GiftCardBalance numberOptional	Not present if content is not issued. Balance of the gift card
Activated booleanRequired	If true the coupon is already activated. If false the content must be activated before they can be used. If empty - no possibility to change the state of a coupon.
IsPointsCard booleanRequired	If true - it's a points program coupon, and we can get additional information for it (see GET /points-program/{UserId}/status/points-last-dats etc)
Featured booleanRequired	If true - this content should be promoted in the app (using pop-up or marked somehow)
New booleanRequired	If true - "New" mark should be added to content
Like booleanOptional	If true - content is liked. If false - content disliked. If null - no mark.
LikeCounters objectRequired	State of likes and dislikes for a content
Likes integerRequired	Count of likes.
Dislikes integerRequired	Count of dislikes.
TagsData array of objectRequired	An array of tags associated with this content, tags are grouped by types
Type stringRequired	Type of the Tags.
Tags array of objectRequired	An array of content tags (see Content Tag Model) of this type.
RemainingValidations integerOptional	Shows the number of remaining validations for the content. If NULL - there's no limit on number of validations
AvailableStamps integerOptional	Shows the number of the stamps on the current stage of a loyalty card. For regular coupons this field is NULL
StampsRequired integerOptional	Shows the number of the stamps required to fill loylaty card current level. For regular coupons this field is NULL
AdditionalInfo1 stringOptional	Additional content's info
AdditionalInfo2 stringOptional	Additional content's info
AdditionalInfo3 stringOptional	Additional content's info
BarcodeNumber stringOptional	Code prefix + coupon code
IsSubscription booleanRequired	Boolean flag to show if the object is associated with a subscription or not
SubscriptionState stringOptional	State of the subscription. Possible values: Active Downgrading Cancelled
SharedUser array of objectOptional	Info about shared user
Name stringOptional	Name of a shared user.
UserId stringOptional	The unique and persistent ID that identifies the shared User.
ExternalUserId stringOptional	A unique ID for the given User in external customer systems.

GET /content

Gets an overview of all the coupons assigned to a user. This call is primarily used to get an overview of the coupons available to check for changes that have occurred since last time the app was used.

Request

The service expects the following parameters as part of the URL query-string:

Parameter	Description
UserId stringRequired	The unique and persistent ID that identifies the user which content is requested for.
SectionIds array of integerOptional	If desirable to only get the content for one or more sections, it can be specified as an array of sectionIds. If not present or empty the response will contain all the available sections.

The signature is calculated as a SHA-2 256 checksum using string source from the following concatenated parameters:

DateTime (HTTP header)
UserId
Your secret API Key

Successful Response

A successful call will return a HTTP 200 OK response code and the following JSON object in response body:

Parameter	Description
Sections array of objectRequired	Array of sections.
Id integerRequired	The Id of the section.
Name stringRequired	The name of the section.
Content array of objectRequired	Array of content objects (see Content model) that is placed in this section

PUT /content/togglestate

Toggle the state of the content or activate promises.

Request

The service expects the following parameters as part of the JSON body:

Parameter	Description
UserId stringRequired	The unique and persistent ID that identifies the user that owns the content whose state will be toggled.
ContentId integerRequired	Id of the content you want to change state.
ScheduleId integerRequired	ScheduleId of the content you want to change state.

The signature is calculated as a SHA-2 256 checksum using string source from the following concatenated parameters:

DateTime (HTTP header)
UserId
ContentId
Your secret API Key

Successful Response

A successful call will return a HTTP 200 OK response code and the following JSON object in response body:

Parameter	Description
Content objectOptional	Updated content model (see Content model).

GET /preview

Gets an overview of public coupon previews. Can be used to show the list of available coupons before user is logged in.

Request

The service expects the following parameters as part of the URL query-string:

Parameter	Description
Culture stringOptional	Desired culture of a coupons.
SectionIds array of integerOptional	If desirable to only get the content for one or more sections, it can be specified as an array of sectionIds. If not present or empty the response will contain all the available sections.

The signature is calculated as a SHA-2 256 checksum using string source from the following concatenated parameters:

DateTime (HTTP header)
Your secret API Key

Successful Response

A successful call will return a HTTP 200 OK response code and the following JSON object in response body:

Parameter	Description
Sections array of objectRequired	Array of sections.
Id integerRequired	The Id of the section.
Name stringRequired	The name of the section.
Content array of objectRequired	Array of content objects (see Content model) that is placed in this section

Share content

App coupons can be shared to registered users or non-registered members. Sharing to registered users is done app to app. Sharing to unregistered uers is done through any external channel, eg. SMS or other messaging service.

When creating campaigns, dashboard users determine if coupons should be shareable or not. Shareable content is identified using the ShareType parameter in the Content model.

Shareable content can be 'issue new' or 'give away', but this distinction is handled in Liquid Barcodes back end.

Coupon sharing is a two step process.

POST /share

Shares some content with the user's friend. This function call should only be used if the content has been assigned as shareable (see ShareType parameter of Content model).

Request

The service expects the following parameters as part of the JSON body:

Parameter	Description
ContentId integerRequired	The Id of the content to share.
FriendUserRef stringRequired	The unique user reference to the friend that the user wants to give the coupon to. Usually, this is the phone number of the friend (MSN). In that case, it should be sent using country code (without `+` symbol) and digits only. For example: if country code is `+1` and phone number is `987654321`, field value will be `1987654321`.
ScheduleId integerRequired	LIQUID Barcodes' internal Schedule identifier.
UserId stringRequired	The unique and persistent ID that identifies the user that owns the content that will be shared.

The signature is calculated as a SHA-2 256 checksum using string source from the following concatenated parameters:

DateTime (HTTP header)
UserId
ContentId
Your secret API Key

Successful Response

A successful call will return a HTTP 200 OK response code and the following JSON object in response body:

Parameter	Description
Message stringOptional	The default text to use when the content to be shared should be sent through the user's phone (SMS or some other means). The typical use case is when the recipient has not given consent to the retailer.
ResultCode stringRequired	The result of the operation. The following values are supported: SharedOnSms - The content has already been shared directly to the friend through SMS. SharedByApp - The content has already been shared to the friend's app. SharedByUrl - The content has to be shared from the user's mobile phone. The 'Message' parameter contains what needs to be shared. CouldNotShare - The content couldn't be shared to the proposed end user.
ResultMessage stringRequired	A human readable text of the result.

Share stamps

Allows users to share stamps with friends.

POST /content/coupons/{ContentId}/stamps/share

Shares stamps from the loyalty card with registered user. Only the number of stamps on the current stage can be fixed (see value of AvailableStamps of the Content Model).

Request

The service expects the following parameters as part of the URL path:

Parameter	Description
ContentId integerRequired	The Id of the content to share stamps from.

The service expects the following parameters as part of the JSON body:

Parameter	Description
UserId stringRequired	The unique and persistent ID that identifies the user that owns the content to share stamps from.
ScheduleId integerRequired	LIQUID Barcodes' internal Schedule identifier.
StampsCount integerRequired	The amount of stamps to share.
FriendUserRef stringRequired	The unique user reference to the friend that the user wants to give the coupon to. Usually, this is the phone number of the friend (MSN). In that case, it should be sent using country code (without `+` symbol) and digits only. For example: if country code is `+1` and phone number is `987654321`, field value will be `1987654321`.

The signature is calculated as a SHA-2 256 checksum using string source from the following concatenated parameters:

DateTime (HTTP header)
UserId
ContentId
Your secret API Key

Successful Response

A successful call will return a HTTP 204 response code.

Likes

Allows users to like content. Information about likes can be used to filter / sort content in app and as input to machine learning.

PUT /content/{ContentId}/like

This method allows set/remove like/dislike for content.

Request

The service expects the following parameters as part of the URL path:

Parameter	Description
ContentId integerRequired	The Id of the content that user wants to like/dislike.

The service expects the following parameters as part of the JSON body:

Parameter	Description
UserId stringRequired	The unique and persistent ID that identifies the user that owns the content that will be liked/disliked.
ScheduleId integerRequired	LIQUID Barcodes' internal Schedule identifier of the content that user wants to like/dislike.
Like booleanOptional	Like state: true - liked false - disliked null or not present - no mark

The signature is calculated as a SHA-2 256 checksum using string source from the following concatenated parameters:

DateTime (HTTP header)
UserId
ContentId
Your secret API Key

Successful Response

A successful call will return a HTTP 200 OK response code and the following JSON object in response body:

Parameter	Description
ContentId integerRequired	The Id of the content that was liked/disliked.
ScheduleId integerRequired	LIQUID Barcodes' internal Schedule identifier of the content that was liked/disliked.
Like booleanOptional	New like state: true - liked false - disliked null or not present - no mark
LikeCounters objectRequired	Object containing updated total like/dislike counters for a content.
Likes integerRequired	Number of likes.
Dislikes integerRequired	Number of dislikes.

Parameter	Description
TagId integerRequired	The Id of the Tag.
Name stringRequired	Name of the Tag.
ImageUrl stringOptional	Image URL for a Tag image.
Likable booleanRequired	If true, user can set like or dislike for the content.
Dislikable booleanRequired	If true, dislikes are allowed (it depends on `Likable` field: if `Likable` is false, dislikes are not allowed and `Dislikable` field has no effect).
Like booleanOptional	User Like state for this category: true - liked false - disliked null or not present - no mark

Parameter	Description
UserId stringRequired	The unique and persistent ID that identifies the user which content tags are requested for.

Parameter	Description
Type stringRequired	Type of the Tags.
Tags array of objectRequired	An array of Content Tag Model of this type.

Parameter	Description
TagId integerRequired	Id of the target Tag.

Parameter	Description
UserId stringRequired	The unique and persistent ID that identifies the user which content tag will be liked/disliked for.
Like booleanOptional	New like state: true - liked false - disliked null or not present - no mark

Rating

Rating allows users to give their opinion on a product they have purchased or the service.

The rating service consists of two types of functions: requests to manage a single user's rating(s) and requests to obtain rating statistics.

When implementing rating functionality in the app, you can choose between making one location in the app to show a dynamic list of all rating types and pending ratings (recommended), or you can make one specific location for each rating type.

GET /ratings/categories

This method returns all rating categories. Per category, it also includes the first of any pending ratings.

Request

The service expects the following parameters as part of the URL query-string:

Parameter	Description
UserId stringRequired	The unique and persistent ID that identifies the user which rating categories are requested for.
CategoryId integerOptional	ID of the rating category to get. If not set, all rating categories with pending ratings will be returned.

The signature is calculated as a SHA-2 256 checksum using string source from the following concatenated parameters:

DateTime (HTTP header)
UserId
CategoryId
Your secret API Key

Successful Response

A successful call will return a HTTP 200 OK response code and the following JSON object in response body:

Parameter	Description
Categories array of objectRequired	One object per rating category.
Id integerRequired	Category ID.
Name stringRequired	Category name.
RatingsSinceReward integerRequired	Number of ratings the user has submitted since last rewarded.
RatingsUntilReward integerRequired	Number of remaining ratings before the next reward.
RatingsPending integerRequired	Number of currently pending ratings. A value of 1 means that only 1 pending rating is available (this one).
PendingRating objectOptional	If any pending ratings are found for this category, the first (oldest) pending rating is returned here.
RatingId integerRequired	The ID of the rating.
TimeToLive stringRequired	Time before the rating expires. If value is in the past, it is not possible to rate the product. The time is given in UTC.
Store objectRequired	Details of the store where the pending rating was created / where the product was bought.
Id integerRequired	The ID of the store where the product was bought/redeemed.
Name stringRequired	The name of the store where the product was bought/redeemed.

POST /rating

This method submits an user rating for a given rating.

Request

The service expects the following parameters as part of the JSON body:

Parameter	Description
UserId stringRequired	The unique and persistent ID that identifies the user which is rating.
RatingId integerRequired	The ID of the pending rating. This id is only available through the previous function call GET /ratings/categories.
Rating integerRequired	The rating of the product. Any integer value between 1 and 5.

The signature is calculated as a SHA-2 256 checksum using string source from the following concatenated parameters:

DateTime (HTTP header)
UserId
RatingId
Rating
Your secret API Key

Successful Response

A successful call will return a HTTP 200 OK response code and the following JSON object in response body:

Parameter	Description
Bonus booleanOptional	It will be 'true' if a reward was given, 'false' otherwise.
Backlog integerOptional	Number of pending ratings that can still be submitted.

GET /ratings/statistics

This method gets the rating statistics for all stores.

Request

The service expects the following parameters as part of the URL query-string:

Parameter	Description
CategoryId integerOptional	The ID of the category to get the statistics for.

The signature is calculated as a SHA-2 256 checksum using string source from the following concatenated parameters:

DateTime (HTTP header)
CategoryId
Your secret API Key

Successful Response

A successful call will return a HTTP 200 OK response code and an array of the following JSON object in response body:

Parameter	Description
StoreId integerRequired	The ID of the store where the product was bought/redeemed.
StoreName stringRequired	The name of the store where the product was bought/redeemed.
Longitude numberRequired	Store geolocation longitude.
Latitude numberRequired	Store geolocation latitude.
Av2MonthRating numberRequired	The average rating for the store going back 2 months.
Tot2MonthRatings integerRequired	The number of ratings for the store going back 2 months.
AvRating numberRequired	The average/current rating of the store all time.
TotRatings integerRequired	The total number of ratings for this store all time.

GET /ratings/statistics/store

This method gets the stats for one specific store.

Request

The service expects the following parameters as part of the URL query-string:

Parameter	Description
StoreId integerRequired	The ID of the store where the product was bought/redeemed.
CategoryId integerOptional	The ID of the category to get the statistics for.

The signature is calculated as a SHA-2 256 checksum using string source from the following concatenated parameters:

DateTime (HTTP header)
StoreId
CategoryId
Your secret API Key

Successful Response

A successful call will return a HTTP 200 OK response code and an array of the following JSON object in response body:

Parameter	Description
StoreId integerRequired	The ID of the store where the product was bought/redeemed.
StoreName stringRequired	The name of the store where the product was bought/redeemed.
Longitude numberRequired	Store geolocation longitude.
Latitude numberRequired	Store geolocation latitude.
Av2MonthRating numberRequired	The average rating for the store going back 2 months.
Tot2MonthRatings integerRequired	The number of ratings for the store going back 2 months.
AvRating numberRequired	The average/current rating of the store all time.
TotRatings integerRequired	The total number of ratings for this store all time.
WeekRatings array of objectRequired	Array of last nine weeks ratings average presented in oldest first. The 9th data point is the current week.
AvgRating numberRequired	Ratings average.
Count integerRequired	Number of ratings.
WeekNr integerRequired	Number of the week.

Stores management

Liquid Barcodes can store and send a wide range of information per store to the app.

The stores information is typically used to let user select favourite store and store finder.

Note that only active stores will be available meaning stores that are not closed down for maintenance/refurbishment, closed permanently etc. It is recommended to download the stores list on a regular interval (say 24 hours) and cache it locally, as the store list can be significant amount of data, in addition to it by nature being fairly static.

GET /stores

This method returns all availalble stores and their details.

Request

The service has no arguments but the standard headers.

The signature is calculated as a SHA-2 256 checksum using string source from the following concatenated parameters:

DateTime (HTTP header)
Your secret API Key

Successful Response

A successful call will return a HTTP 200 OK response code and the following JSON object in response body:

Parameter	Description
Stores array of objectRequired	List of store objects.
Id integerRequired	LIQUID internal ID.
ExternalId integerRequired	External (customer's) ID.
Name stringRequired	Name of the store.
ShortName stringRequired	Name of the store in a shorted format.
Address stringRequired	Address of the store.
Telephone stringRequired	Phone number of the store.
Latitude numberRequired	Store geolocation's latitude.
Longitude numberRequired	Store geolocation's longitude.
CurrentState stringRequired	The current state of the store. Permitted values are: Open. The store is open for business Closed. The store is not open for business TemporarilyClosed. The store is not open for business but will open again in the future PermanentlyClosed. The store is no longer operational
OpeningHours array of stringOptional	Array of opening hours, one entry for each way of the week from Monday to Sunday. Each entry takes the format "H1:M1-H2:M2" where H1/M1 are opening time hours/minutes and H2/M2 are closing time hours/minutes. For example: "09:00-18:00".
Note stringOptional	Store defined text to signify some special announcements, e.g. 'Closed on Monday due to public holidays'.
TagIds stringOptional	Contains a comma separated list of TagIds that are used to group stores.
Metadata stringOptional	Contains a comma separated list of key:value pairs related to this particular store. Any keys that the app is unaware of should be ignored.
Logo stringOptional	URL to store logo (if the store uses a different logo from the company logo).
Email stringOptional	Email address of the store.
Zip stringOptional	Zip code of the store address.
City stringOptional	City where store is placed.

GET /storetagids

This method returns a list of Store Tags.

Request

The service has no arguments but the standard headers.

The signature is calculated as a SHA-2 256 checksum using string source from the following concatenated parameters:

DateTime (HTTP header)
Your secret API Key

Successful Response

A successful call will return a HTTP 200 OK response code and the following JSON object in response body:

Parameter	Description
StoreTags array of objectRequired	List of store tags, each object containing the following parameters.
Id integerRequired	The ID of the tag/region.
Title stringRequired	The full name of the tag/region.
StoreIds array of integerRequired	An array of IDs of all stores that belong to this tag/region.

GET /store/{storeId}/status

It returns status for the given store.

Request

The service expects the following parameters as part of the URL path:

Parameter	Description
storeId integerRequired	Id of the store which status is required for.

The signature is calculated as a SHA-2 256 checksum using string source from the following concatenated parameters:

DateTime (HTTP header)
storeId
Your secret API Key

Successful Response

A successful call will return a HTTP 200 OK response code and the following JSON object in response body:

Parameter	Description
SuccessModel stringOptional	The data model will be customer and situation dependant. This field will be returned as a string. Typically it will contain JSON. Default: `"{\"StoreAvailable\":true}"`
MachineTriggerTypes array of stringOptional	List of supported machine trigger types. Possible options: QR WashCode

GET /stores/machines/status

It returns a list of store machines and they status.

Request

The service expects the following parameters as part of the URL query-string:

Parameter	Description
UserId stringOptional	The unique and persistent ID that identifies the user which store machines are requested for. Required to set machines names to a correct culture.
LastUpdateTime stringOptional	Datetime in ISO-8601 format. If set, response will only show statuses that have been changed after this time.

The signature is calculated as a SHA-2 256 checksum using string source from the following concatenated parameters:

DateTime (HTTP header)
Your secret API Key

Successful Response

A successful call will return a HTTP 200 OK response code and the following JSON object in response body:

Parameter	Description
StoreMachinesStatus array of objectRequired	Array of store machine statuses.
StoreId integerRequired	Liquid barcodes store identifier (can be found in GET /stores response).
Status stringRequired	Store status. Possible values: Available OutOfService
StoreMachines array of objectRequired	Array of store machine info objects.
Name stringRequired	Name of machine.
MachineDeviceId stringRequired	Machine device Id.
Status stringRequired	Machine status. Possible values: Available OutOfService

Recruit-a-friend

The function allows app users to recruit friends to the app and the Recruiter and/or Recruitee can receive reward when the new user registers. It is not possible to recruit already existing users or users that have a pending recruiting attempt.

If new user is not already registered, the app will receive a message text from Liquid Barcodes to prepopulate to the user's preferred native messaging app.

On the recruiting page, make sure that there is an information image (hosted by Liquid Barcodes) that can be updated without app update.

GET /validreferral

This method checks whether the referral user is already a member or is eligible for referral.

Request

The service expects the following parameters as part of the URL query-string:

Parameter	Description
UserId stringRequired	The unique and persistent ID that identifies the user which will send a friend referral.
Msn stringRequired	The MSN of the user that is to be issued a referral. It should be sent using country code (without `+` symbol) and digits only. For example: if country code is `+1` and phone number is `987654321`, field value will be `1987654321`.

The signature is calculated as a SHA-2 256 checksum using string source from the following concatenated parameters:

DateTime (HTTP header)
UserId
Msn
Your secret API Key

Successful Response

A successful call will return a HTTP 200 OK response code and the following JSON object in response body:

Parameter	Description
SmsTemplate stringRequired	The template for the SMS text to send to the person being referred.

POST /referral

This method allows a user to refer a friend. If the friend registers the app inside a given time period the referral and/or referee is given a reward. This function call should only be called if the mechanism for referral distribution confirms that the referral has been sent (or as close as possible).

Request

The service expects the following parameters as part of the JSON body:

Parameter	Description
UserId stringRequired	The unique and persistent ID that identifies the user which is sending the friend referral.
Msn stringRequired	The MSN of the user that is to be issued a referral. It should be sent using country code (without `+` symbol) and digits only. For example: if country code is `+1` and phone number is `987654321`, field value will be `1987654321`.

The signature is calculated as a SHA-2 256 checksum using string source from the following concatenated parameters:

DateTime (HTTP header)
UserId
Msn
Your secret API Key

Successful Response

The service replies with HTTP-200 status when the operation was successful.

Push notification support

Push notifications can have a dramatic positive effect on app opening rates. Liquid Barcodes supports sending push notifications depending on certain events to the app provided that the following steps are completed by the app developer/publisher:

iPhone users should be asked to accept push notification as part of the registration process.
On Android, and if accepted on iPhone, register the application with the relevant push notification services (Apple, Google, etc)
Forward the credentials to Liquid Barcodes. The credentials we require are:
- Apple push notification service: The iOS Push certificate
- Google Cloud Messaging (GCM) service: The API key
Add functionality to register each instance of the application running on the consumers' devices with the relevant push notification services to obtain the DeviceToken/RegistrationID
Every time the DeviceToken/RegistrationID changes, AND upon achieving a successful registration, the app must call the RegisterDevice function described below:

It is very important to test push when releasing new app versions to avoid missing out on push notification registrations.

Note: Repeat device registration when customer opens the app and the app does the initial GET /content request. The app does not have to reregister on every GET /content request, once per day is recommended.

POST /device

This function registers a device with Liquid Barcodes. It is optional to register device. Each UserId can register maximum one device. If a new DeviceId is registered for a UserId, any existing DeviceId will be overwritten and only the new DeviceId will be stored.

Also for this function we expect the UserAgent HTTP header in the request.

Request

The service expects the following parameters as part of the JSON body:

Parameter	Description
DeviceId stringRequired	A unique identifier for the device that as far as possible is persistent when the user logs in after having a) logged out, b) deleted and re-installed the app, and c) done a factory reset (if possible). This identifier is used to prevent fraud by setting limitations on the number of times a user can use the same device with different MSNs.
UserId stringRequired	This is the user identifier for the application.
DeviceToken stringRequired	The device token assigned to the device upon registering with the appropriate push notification service. If empty, the application user has declined to receive push notifications.
MSN stringRequired	The telephone number the user has registered with. It should be sent using country code (without `+` symbol) and digits only. For example: if country code is `+1` and phone number is `987654321`, field value will be `1987654321`.
Language stringRequired	The language setup for the user device according to ISO 639‑1.
DeviceType stringRequired	The device type, where the following values are allowed 'iOS', 'Android'.
AppVersion stringRequired	The version of the application (used to track how many users have upgraded to the latest versions).
Notes stringOptional	This is a free-text field that can be used to convey any information deemed relevant.

The signature is calculated as a SHA-2 256 checksum using string source from the following concatenated parameters:

DateTime (HTTP header)
DeviceId
UserId
DeviceToken
MSN
Language
DeviceType
AppVersion
Your secret API Key

Successful Response

A successful call will return a HTTP 200 OK response code.

Receipts handling

Liquid Barcodes stores all receipts in a receipt repository and the app has access to these receipts through our receipts service.

The app can obtain a list of receipts and can ask Liquid Barcodes to forward one or multiple receipts to an email recipient.

Receipt Model

Receipt model that will be used

Parameter	Description
ReceiptId stringRequired	Id of the receipt record (Will be used in POST /receipt/forward).
Format stringRequired	Receipt format, e.g. Liquid/1.0 for this field. The format is detailed below.
Receipt stringOptional	A JSON representation of the whole receipt for the complete transaction. The JSON should take format of the table bellow. Note: The JSON code must be escaped so that the Receipt field is just a regular string.

Receipt

Liquid/1.0 receipt format:

Parameter	Description
ReceiptId stringRequired	A unique ID for this sale / receipt.
SubTotal decimalOptional	Summed amount of the saleslines. Includes rebates and tenders. Does not include tax.
RebateOnSubTotal decimalOptional	Total rebates.
TenderOnSubTotal decimalOptional	Total tenders.
TaxSetupId integerOptional	The tax setup used.
TaxAmount decimalOptional	Total amount of taxes.
TaxDescription stringOptional	Textual description of taxes for this item. Formatted for country conventions and member locale.
TaxesInfo array of objectsOptional	Array of taxes per tax category (combined for all items in the basket)
TaxCategoryTitleCultureData stringOptional	Title of the tax category (options for all supported cultures)
TaxAmount decimalOptional	Tax calculated for this item
TaxPercentage decimalOptional	Tax percent for the category
TaxLegalEntityName stringOptional	Hold information about tax legal entity
StoreTaxIds dictionary<string, string>Optional	Store specific tax identifiers for different tax categories
TotalToPay decimalOptional	Total amount to pay. Including tax.
Currency stringOptional	Currency unit for all monetary amounts.
TransactionDateTime stringRequired	Timestamp when the sale was completed (ISO-8601 format).
GLN stringOptional	Global Location Number (Wikipedia page).
OrganizationNumber stringOptional	Organization number of the store.
Store objectRequired	Information about the store
StoreId integerOptional	Unique Id of a store in Liquid Barcodes system.
StoreRef stringOptional	Store reference in POS system.
ExternalStoreRef stringRequired	The same and interchangeable with StoreRef.
StoreName stringOptional	Name of the store.
POSId stringOptional	Unique POS identifier.
EmployeeId integerOptional	Unique employee identifier.
EmployeeName stringOptional	Employee name.
Customer objectRequired	Information about store customer.
id integerOptional	Unique id of a customer in a LiquidBarcodes system
loyalty_id stringOptional	Coupon code that was used by the customer. Replaces userRef if filled.
msn stringOptional	Mobile number.
userRef stringRequired	User identifier (App user id or Foreign id). Can be replaced by loyalty_id.
name stringOptional	Full name.
gender stringOptional	Gender (M/F).
birthdate stringOptional	Birthdate (ISO-8601).
Saleslines array of objectsOptional	Sales lines in the receipt.
Description stringOptional	Description of the sales line.
EAN stringOptional	European Article Number / International Article Number (Wikipedia page). Replaces ProductCode if filled.
ProductCode stringRequired	The POS' internal identifier for the bought product. Can be replaced by EAN.
PLU stringOptional	Price Lookup Code (Wikipedia page)
Quantity decimalRequired	Bought quantity. Can be a decimal amount.
Unit integerOptional	Supported unit types: None = 0 Number = 1 Kg = 2 Meter = 3 Liter = 4
Brand stringOptional	Product brand.
SalesPrice decimalRequired	Total price per unit (exluding rebates and tenders, but including tax).
TotalLinePrice decimalRequired	Final price of the sales line.
Rebate decimalRequired	Rebate given per unit.
Tender decimalRequired	Tender given per unit.
RebatedPrice decimalOptional	Actual price per unit (including rebates, tenders and tax).
Comment stringOptional	Extra information about this line.
TaxAmount decimalOptional	Tax amount included in this sales line.
TaxPercentage decimalOptional	Tax percentage applicable for this sales line.
TaxDescription stringOptional	Textual description of taxes for this item. Formatted for country conventions and member locale
LineTaxesInfo array of objectsOptional	Array of taxes per tax category for this line.
TaxCategoryTitleCultureData stringOptional	Title of the tax category (options for all supported cultures)
TaxAmount decimalOptional	Tax calculated for this item
TaxPercentage decimalOptional	Tax percent for the category
RewardPointsLines array of objectsOptional	Information about points issued as a reward for this receipt
Description stringOptional	Points reward description.
TotalPoints decimalOptional	Given points amount.
Payments array of objectsOptional	Payment information
type stringOptional	Payment type, for example: Card, Cash
card_issuer stringOptional	For example: VISA; Mastercard, AmericanExpress
card_issuer_country stringOptional	For example: NO, SE
terminal_id stringOptional	Unique payment terminal identifier.
terminal_print stringOptional
transaction_id stringOptional	Unique payment transaction ID.
ref_auth stringOptional
Ref stringOptional
auth stringOptional
bax stringOptional
censored_card_number stringOptional	Masked credit card number that can be safely shown on a receipt.
amount decimalOptional	Payment amount.
tip_amount decimalOptional	Additional tip amount.
processing_fee decimalOptional	Processing fee.
currency stringOptional	Currency of payment.
ProviderData stringOptional	Payment provider specific information. It can contain Payment reference or some special info, content depends on Payment provider used.
card_type stringOptional	Only relevant for Moneris/RocketPartners payment integration. Type of card used. ie: Visa, MasterCard, etc.
ReceiptTxt stringOptional	Only relevant for Moneris/RocketPartners payment integration. TransactionId in APP API POST /ProcessShopBasket response.
AuthCode stringOptional	Only relevant for Moneris/RocketPartners payment integration. Authorization code returned from the issuing institution.
AuthResponseCode stringOptional	Only relevant for Moneris/RocketPartners payment integration. Transaction Response Code. < 50: Transaction approved >= 50: Transaction declined NULL: Transaction was not sent for authorization For further details on the response codes that are returned please see the Moneris Response Codes table.
AuthResponseCodeIso stringOptional	Only relevant for Moneris/RocketPartners payment integration. ISO response code return from issuing institution. For further details on the response codes that are returned please see the Moneris Response Codes table.
ExternalReferenceNumber stringOptional	Only relevant for Moneris/RocketPartners payment integration. Terminal used to process the transaction as well as the shift, batch and sequence number. This data is typically used to reference transactions on the host systems, and must be displayed on any receipt presented to the customer. This information is to be stored by the merchant. Example: 660123450010690030: 66012345: Terminal ID 001: Shift number 069: Batch number 003: Transaction number within the batch
PaymentTransactionId stringOptional	Liquid Barcodes payment transaction id.
Metadata stringOptional

JSON

1

2

3

4

5

6

7

8

9

10

11

12

13

14

15

16

17

18

19

20

21

22

23

24

25

26

27

28

29

30

31

32

33

34

35

36

37

38

39

40

41

42

43

44

45

46

47

48

49

50

51

52

53

54

55

56

57

58

59

60

61

62

63

64

65

66

67

68

69

70

71

{
  "ReceiptId":"",
  "TransactionDateTime":"",
  "SubTotal":0,
  "RebateOnSubTotal":0,
  "TenderOnSubTotal":0,
  "TaxAmount":0,
  "TotalToPay":0,
  "Currency":"",
    "Metadata":"",
  "Store":{
    "StoreId":"",
    "ExternalStoreId":"",
    "StoreName":"",
    "GLN":"",
    "OrganizationNumber":"",
    "POSId":"",
    "EmployeeId":0,
    "EmployeeName":""
  },
  "Saleslines":[
    {
      "Description":"",
      "EAN":"",
      "ProductCode":"",
      "PLU":"",
      "Quantity":0,
      "Unit":"",
      "Brand":"",
      "SalesPrice":0,
      "Rebate":0,
      "Tender":0,
      "RebatedPrice":0,
      "TaxAmount":0,
      "TaxPercentage":0,
      "Comment":""
    }
  ],
  "Payments":[
    {
      "type":"Card",
      "card_issuer":"",
      "card_issuer_country":"",
      "terminal_id":"",
      "terminal_print":"",
      "transaction_id":"",
      "ref_auth":"",
      "ref":"",
      "auth":"",
      "bax":"",
      "censored_card_number":"",
      "card_token":"",
      "amount":0,
      "tip_amount":0,
      "processing_fee":0,
      "currency":""
    },
    {
      "type":"Cash",
      "amount":20000,
      "tip_amount":0,
      "currency":"NOK"
    }
  ],
  "customer":{
    "id":"",
    "loyalty_id":"",
    "msn":"",
    "name":"",
    "gender":"",
    "birthdate":""
  }
}

GET /receipts

Request

The service expects the following parameters as part of the URL query-string:

Parameter	Description
UserId stringRequired	The unique and persistent ID that identifies the user which receipts are requested for.
StoreIds integerOptional	Will limit the retrieved receipts to this list of stores. Should use the StoreId as available in the GET /stores call.
DateFrom stringOptional	ISO 8601 datetime string. It will limit the retrieved receipts to this datetime and forwards. This is used to get the receipts for the last 6 months f.e.x

The signature is calculated as a SHA-2 256 checksum using string source from the following concatenated parameters:

DateTime (HTTP header)
UserId
Your secret API Key

Successful Response

A successful call will return a HTTP 200 OK response code and the following JSON object in response body:

Parameter	Description
Logo stringRequired	Url to company logo. Note: If a particular store needs a separate logo, the store logo is available for each store from GET /stores function call
Receipts array of objectRequired	An array of Receipt Model objects.

POST /receipts/forward

This service is used to forward receipts outside the app.

Request

The service expects the following parameters as part of the JSON body:

Parameter	Description
UserId stringRequired	The unique and persistent ID that identifies the user which is forwarding receipts.
ReceiptIds array of stringRequired	A list of receiptIDs to be forwarded (ReceiptId field from response of GET /receipts, NOT ReceiptID in Receipt field).
MediaType stringRequired	The media to forward the receipts, currently only 'Email' is accepted.
UserReference stringOptional	The recipient of the receipts. Not necessary if it appropriate information is already stored with the user (e.g. the e-mail address). Note that this value will override any values stored with the user (if the user wants to forward it to another person or another e-mail address).

The signature is calculated as a SHA-2 256 checksum using string source from the following concatenated parameters:

DateTime (HTTP header)
UserId
ReceiptIds
MediaType
Your secret API Key

Successful Response

The service replies with HTTP-200 status when the operation was successful.

PUT /receipts/{ReceiptId}

This service allows you to update MetaData receipt field.

Request

The service expects the following parameters as part of the URL path:

Parameter	Description
ReceiptId stringRequired	Id of the receipt record (from GET /receipts).

The service expects the following parameters as part of the JSON body:

Parameter	Description
UserId stringRequired	The unique and persistent ID that identifies the user which owns the receipt that will be updated.
Metadata stringRequired	Field to store any additional information.

The signature is calculated as a SHA-2 256 checksum using string source from the following concatenated parameters:

DateTime (HTTP header)
UserId
ReceiptId
Your secret API Key

Successful Response

The service replies with HTTP-200 status with Receipt Model in the body of response (see Receipt Model) when the operation was successful.

Shop

The shop allows users to buy content from Liquid Barcodes. The shop provides a set of shop offers that are items that have a defined price and that end users can purchase. The shop functionality consists of three parts:

Shop front-end, this is the virtual store where the consumer can choose which products he wants to buy.
Shop back-end, this is the handling of the shop items and the issuing of content based on shop transactions.
Payment provider, this is a third party payment provider that handles the transaction of real money. If the currency in the shop is loyalty points this can be handled entirely by Liquid Barcodes, otherwise a integration between Liquid Barcodes or third party and the payment provider must be implemented.

Before buying a shop offer, customer must register payment method. This process is payment provider specific.

The interaction flow when buying a shop offer is as follows (where the app is only involved in step 1 to 3 and 5):

The App calls the function ShopOffers and gets a list of offers that can be bought for a certain price by the consumer. This call will provide all the details necessary for the consumer to make a choice, and all the necessary details for issuing coupons.
The consumer selects which offer he wants by putting them into a basket. When buying subscriptions, the app should check any price adjustment with Liquid Barcodes before proceeding to check out.
When checkout of the basket is selected, the app sends a request to the shop back-end using the ProcessShopBasket call.
the app sends request to Liquid Barcodes with shop offer to purchase and preferred payment option. Liquid Barcodes back-end, that is integrated towards the payment provider, will request the baskets grand total to be reserved by the payment provider (note that this is not the actual payment, but reserving an amount of money on the consumers account).
- The shop back-end will check that the request is valid and represents the offers that was provided in GET /shopoffers. This is to prevent tampering.
- Dependent on the third party payment provider the request will be processed synchronously (SuccessCode = OK) or asynchronously (SuccessCode = InProcess). If processed asynchronously the app needs to request the status using GET /ShopTransactionStatus
Appropriate information should be given to the user that the process has completed, how much was paid and, if any, which coupons could not be issued.
When payment has been reserved, one or multiple actions can be triggered in Liquid Barcodes system, such as starting a subscription, issuing a coupon or topping up a gift card. When actions are complete, Liquid Barcodes will confirm payment with the payment provider. On error, Liquid Barcodes will cancel payment.

Liquid Barcodes also support payment provider integrations by third parties. Read more about this under Customer integrates with payment provider.

Dashboard users can create shop offers and the related actions. Each shop offer has a unique shop offer token that serves to define the shop offer and add security.

When content has been issued, Liquid Barcodes updates the unique user's content record if relevant. The app shows the purchased content as described under Content management.

Receipts from successful purchases can be obtained as described under Receipts handling.

Shop offer model

This is the structure of the objects served in the GET /shopoffers request:

Parameter	Description
ShopOfferId integerRequired	The unique ID for this particular offer.
ContentId integerRequired	LIQUID Barcodes content identifier.
ScheduleId integerRequired	LIQUID Barcodes schedule identifier.
CategoryId integerRequired	Id of offer's category.
IssueDate stringRequired	ISO 8601 formatted datetime when this offer instance was issued. Date/time is given in UTC.
PaymentProviderId stringRequired	The ID of the payment provider where the OfferToken must be sent.
MaximumAmount integerOptional	The maximum number of times the offer can be bought. If not present or NULL it means unlimited.
ThumbUrl stringOptional	If present this points to an smaller representation of the shop offer to present on f.ex the front page of the application.
Url stringRequired	URL to the offer details image.
BackgroundColour stringOptional	If present this represents a background colour to use with this coupon. The background colour is represented in #AABBCC notation.
Type stringRequired	Defines the type of shop offer (Shop/Subscription/WebCouponShop/OrderAndPay/Local).
Description stringOptional	A textual description of the shop offer.
ExpiryDate stringRequired	ISO 8601 formatted datetime when this offer is no longer available . The expiration date/time is given in UTC.
RetailPrice numberRequired	The price to the consumer. Note: If `PersonalCalculatedPrice` is set, `PersonalCalculatedPrice` should be used.
RetailPriceWithoutTax numberRequired	For countries with PricePresentationType = IncludingTax, it is calculated as `RetailPrice` minus `TaxAmount`. For countries with PricePresentationType = ExcludingTax, it is equals to `RetailPrice`.
DefaultPrice numberRequired	The price without the discount.
PersonalCalculatedPrice numberOptional	The price offered to customer's that want to upgrade to a better plan. In the next renewal of the subcription, price will be full.
PersonalCalculatedPriceWithoutTax numberOptional	For countries with PricePresentationType = IncludingTax, it is calculated as `PersonalCalculatedPrice` minus `TaxAmount`. For countries with PricePresentationType = ExcludingTax, it is equals to `PersonalCalculatedPrice`.
TaxAmount numberRequired	Tax amount of the price to be paid in this particular payment. Calculated from `PersonalCalculatedPrice` if it has value or from `RetailPrice` if `PersonalCalculatedPrice` not present.
TaxPercentage numberOptional	Tax percentage.
Currency stringRequired	Will always be the currency of the app's country (one app, one country).
OfferToken stringOptional	This is the token that represents the offer for this user. The OfferToken will be used to trigger coupons between the App vendor and Liquid Barcodes backends. NOTE: All the offer tokens will expire according to the OfferTokensExpiration field below. NOTE: This property is marked optional because it will not be used in the case where Liquid Barcodes' own payment backend is used.
OfferInstanceId stringRequired	The unique instance ID for each individual shop offer
ProductDescription stringOptional	A textual description of the product.
PurchaseConfirmationDescription stringOptional	Contains message with instructions on what to do after successfull purchase (for example: Configure your subscription on MyPage). If this field is not empty - it should be shown after successfull POST /ProcessShopBasket request
PurchaseConfirmationMessage stringOptional	Contains message with information about purchase that user is going to do (for example: Subscription price: X$. Auto-renew: Y$). If this field is not empty - this message should be shown before purchase (before POST /ProcessShopBasket request)
Like booleanOptional	If true - offer is liked. If false - offer disliked. If null - no mark.
LikeCounters objectRequired	State of likes and dislikes for a content.
Likes integerRequired	Count of likes.
Dislikes integerRequired	Count of dislikes.
TagsData array of objectsRequired	An array of tags associated with this content, tags are grouped by types.
Type stringRequired	Type of tags.
Tags array of objectsRequired	List of tags (see Content tag model) of the same type.
DescriptionMarkup stringOptional	The content description in a markup language (for example HTML). If has value should be used instead of Description field.
AdditionalInfo1 stringOptional	Additional offer's info.
AdditionalInfo2 stringOptional	Additional offer's info.
AdditionalInfo3 stringOptional	Additional offer's info.
HasAvailablePromoCodes booleanRequired	Shows whether this offer has active, live (active period between Start and Stop date) promo codes, that have not total usages limit or limit is not yet reached. Promo codes can be passed as OfferPromoCode in POST /ProcessShopBasket request for this shop offer.
ActiveSubscription booleanRequired	If true - this is user's current plan.
Featured booleanRequired	If true - this content should be promoted in the app (using pop-up or marked somehow).
New booleanRequired	If true - 'New' mark should be added to content.

Register payment method

Before customers can start buying items in the shop, customer must register payment mothod. The process may vary depending on the chosen payment service provider.

GET /payment/configuration

Gets a list of the payment registration configurations / how to register.

Request

The service expects the following parameters as part of the URL query-string:

Parameter	Description
UserId stringRequired	The unique and persistent ID that identifies the user which payment configuration is requested for.

The signature is calculated as a SHA-2 256 checksum using string source from the following concatenated parameters:

DateTime (HTTP header)
UserId
Your secret API Key

Successful Response

A successful call will return a HTTP 200 OK response code and the following JSON object in response body:

Parameter	Description
PaymentConfigurations array of objectRequired	List of the payment providers that accept payment method registrations.
Id stringRequired	ID of the payment setup.
Title stringRequired	Payment method title.
Url stringRequired	The URL to request.
Method stringRequired	HTTP request method to user, typically GET.

GET /shopoffers

Gets an overview of all the offers available in the shop for this user. This call is primarily used to get an overview of the shop offers that are available.

Request

The service expects the following parameters as part of the URL query-string:

Parameter	Description
UserID stringRequired	The unique and persistent ID that identifies the user which shop offers are requested for.
CategoryIds array of integerOptional	If desirable to only get the shop offers for one or more categories, it can be specified as an array of CategoryIds. If not present or empty the response will contain all the available categories.
StoreId integerOptional	Enables single shop offer pricing per store. If StoreId provided, prices for this store are returned and tax information is calculated with respect to that store Tax region (otherwise Preferred Store from User profile is taken).

The signature is calculated as a SHA-2 256 checksum using string source from the following concatenated parameters:

DateTime (HTTP header)
UserId
Your secret API Key

All images referred to in the response will have the HTTP headers Last-Modified and E-Tag set and the app should use this to detect when images have changed (do a HEAD request for the images).

Successful Response

A successful call will return a HTTP 200 OK response code and the following JSON object in response body:

Parameter	Description
Categories array of objectRequired	Array of categories.
Id integerRequired	The Id of the category.
Name stringRequired	The name of category.
ShopOffers array of objectRequired	Array of Shop Offer objects (see Shop Offer model) that is placed in this category.
OfferTokensExpiration stringOptional	The expiration datetime ISO 8601 formatted for included offer tokens in this category. After this time the offer tokens will be invalid. A new set of shop offers must be fetched to supply the user with fresh offer tokens.

GET /shopoffers/preview

Gets an overview of public shop offers previews. Can be used to show the list of available offers before user is logged in.

REQUEST

The service expects the following parameters as part of the URL query-string:

Parameter	Description
Culture stringOptional	Desired culture of a shop offers and shop categories.
CategoryIds array of integerOptional	If desirable to only get the shop offers for one or more categories, it can be specified as an array of CategoryIds. If not present or empty the response will contain all the available categories.

The signature is calculated as an SHA-2 256 checksum using string source from the following concatenated parameters:

DateTime (HTTP header)
Your secret API Key

All images referred to in the response will have the HTTP headers Last-Modified and E-Tag set and the app should use this to detect when images have changed (do a HEAD request for the images).

Successful Response

A successful call will return a HTTP 200 OK response code and the following JSON object in response body:

Parameter	Description
Categories array of objectRequired	Array of categories
Id integerRequired	The Id of the category
Name stringRequired	The name of category
ShopOffers array of objectRequired	Array of Shop Offer Preview objects that is placed in this category
ShopOfferId integerRequired	The unique ID for this particular offer.
ScheduleId integerRequired	The unique ID for the schedule.
CategoryId integerRequired	ID of shop offer's category.
PaymentProviderId stringRequired	The ID of the payment provider where the OfferToken must be sent.
MaximumAmount integerOptional	The maximum number of times the offer can be bought. If not present or NULL it means unlimited.
ThumbUrl stringOptional	If present this points to an smaller representation of the shop offer to present on f.ex the front page of the application.
Url stringRequired	URL to the offer details image.
BackgroundColour stringOptional	If present this represents a background colour to use with this coupon. The background colour is represented in #AABBCC notation.
Type stringRequired	Defines the type of shop offer (Shop/Subscription/WebCouponShop/OrderAndPay/Local).
Description stringOptional	A textual description of the shop offer.
RetailPrice numberRequired	The price to the consumer. 'Default price' for Subscription offers, 'Retail price' for single shop offers.
Currency stringRequired	Will always be the currency of the app's country (one app, one country).
ProductDescription stringOptional	A textual description of the product.
LikeCounters objectRequired	State of likes and dislikes for a content.
Likes integerRequired	Count of likes.
Dislikes integerRequired	Count of dislikes.
TagsData array of objectRequired	An array of tags associated with this content, tags are grouped by types.
Type stringRequired	Type of tags.
Tags array of objectsRequired	List of tags (see Content tag model) of the same type.
DescriptionMarkup stringOptional	The content description in a markup language (for example HTML). If has value should be used instead of Description field.
AdditionalInfo1 stringOptional	Additional offer's info
AdditionalInfo2 stringOptional	Additional offer's info
AdditionalInfo3 stringOptional	Additional offer's info
Featured booleanRequired	If true - this content should be promoted in the app (using pop-up or marked somehow).
New booleanRequired	If true - "New" mark should be added to content.

GET /shared/shopoffers

Gets an overview of public shop offers from other vendors that belong to same vendor group. In case there is a linked user, all shop offers available for that user in the other vendors will be shown.

Request

The service expects the following parameters as part of the URL query-string:

Parameter	Description
UserID stringRequired	The unique and persistent ID that identifies the user which shared shop offers are requested for.

The signature is calculated as a SHA-2 256 checksum using string source from the following concatenated parameters:

DateTime (HTTP header)
UserId
Your secret API Key

Successful Response

A successful call will return a HTTP 200 OK response code and the following JSON object in response body:

Parameter	Description
CustomerSharedOffers array of objectRequired	Array of CustomerSharedOffers.
CustomerId integerRequired	Id of the vendor.
UserId stringOptional	Id of the user (if null - means no linked user found, we see pullFromApp offers, if not null - we see member offers).
Categories array of objectRequired	Array of categories.
Id integerRequired	The Id of the category.
Name stringRequired	The name of category.
ShopOffers array of objectRequired	Array of Shop Offer objects (see Shop Offer model) that is placed in this category.

GET /shopcategories

Returns all shop offer categories.

REQUEST

The service has no arguments but the standard headers.

The signature is calculated as an SHA-2 256 checksum using string source from the following concatenated parameters:

DateTime (HTTP header)
Your secret API Key

Successful Response

A successful call will return a HTTP 200 OK response code and the following JSON object in response body:

Parameter	Description
Categories array of objectRequired	List of shop offer categories.
CategoryId integerRequired	The Id of the category.
CategoryName stringRequired	The name of category.

POST /ProcessShopBasket

This will process the basket of specified shop offers and withdraw credits from the account associated with the user. Each call to this function is a separate purchase transactions for the user.

Request

The service expects the following parameters as part of the JSON body:

Parameter	Description
UserId stringRequired	The UserId of the user
StoreId integerOptional	The Liquid Barcodes storeId is required if the offer can only be used at a given store.
PaymentProviderId stringRequired	The Liquid Barcodes Payment Provider Id. The appropriate value to use here will be provided by Liquid Barcodes.
PaymentInformation objectOptional	Any information that is necessary to process the transaction with the payment provider, an example could be the payment provider session if this session is started from the app. This parameter is a JSON object of Key:Value pairs.
TotalBasketValue numberRequired	The total value of the basket. This is used to control that what has been presented to the consumer matches the offers to be processed.
ShopOffers array of objectsRequired	An array of shop offers tokens that are to be processed.
OfferInstanceId stringRequired	The offer instanceId that is unique for this shop offer and UserId.
Amount integerRequired	The number of products to buy. This parameter have a value between 1 and MaximumAmount set in the shop offer. Currently only 1 is supported.
OfferPromoCodeId integerOptional	Promo code to apply to this shop offer. It has fixed price rebate. ID is received on verify promo code request.
ReturnUrl stringOptional	In case a user-present payment is configured, this URL should be set to tell the payment provider where to return after the user has done the payment. We expect the URL will be a deep-link back into the app. A query parameter BasketId will be added to the URL, so that on return the job status on the relevant job can be checked (see the GET /ShopTransactionStatus service, set BasketId to the TransactionId). The return position must poll until a successful or failed transaction is seen. Please see the Polling policy section.

The signature is calculated as a SHA-2 256 checksum using string source from the following concatenated parameters:

DateTime (HTTP header)
UserId
PaymentProviderId
TotalBasketValue
For each object of ShopOffers array concatenate:

OfferInstanceId
Amount
OfferPromoCodeId

Your secret API Key

Successful Response

A successful call will return a HTTP 200 OK response code and the following JSON object in response body:

Parameter	Description
TransactionId stringRequired	A reference to LIQUIDs internal transactionID.
Timestamp stringOptional	ISO 8601 formatted date and time when the reservation was completed. Not present if operation was not successful.
TotalValue numberRequired	This is the total value that is used for the transaction.
ShopOffers array of objectsOptional	An array of shop offers tokens that are to be processed. The array is only present if the order has been fulfilled.
OfferInstanceId stringRequired	The offer instance Id that was purchased.
Amount integerRequired	The number of products bought.
SuccessCode stringOptional	On success returns: OK - The purchases was completed synchronously and the transaction is finalised InProcess - The order is currently processed. The status of the order can be checked with GET /ShopTransactionStatus
SuccessMessage stringOptional	A human readable response message when the call was successful. Only set when SuccessCode is set.
RejectCode stringOptional	A code that can be used to programatically recognize the cause of a rejection. Either SuccessCode or RejectCode will be present in the response. The following values can occur: ActiveSubscription. Attempt to purchase already active subscription. PriceChanged. The app needs to get updated pricing information and re-issue ProcessShopBasket. NothingIsSelected. ShopOffers collection is empty. WrongPaymentProvider. The appropriate value to use here will be provided by Liquid Barcodes. TotalBasketValueNotMatch. This is used to control that what has been presented to the consumer matches the offers to be processed. WrongStore. ShopOffer can only be used at another store. InvalidAmount. ShopOffer is configured with MaximumAmount. WrongUser. UserId in request is wrong. OfferIsDepleted. Offer cannot be ordered because it is depleted. OfferIsInvalidated. Offer given to user has been invalidated. ShopOfferIsInactive. Offer has been deactivated. PaymentError. Error on payment. InvalidPromoCode. An invalid promo code was sent. UnknownError. An unexpected error occured
RejectMessage stringOptional	A human readable cause of rejection message in case a rejection occurred. Only set when RejectCode is set.

GET /ShopTransactionStatus

Can be called to check the status of the transaction at a later stage.

REQUEST

The service expects the following parameters as part of the URL query-string:

Parameter	Description
UserId stringRequired	The UserId of the user.
TransactionId stringRequired	A reference to LIQUIDs basket TransactionId given in POST /processshopbasket response.

The signature is calculated as an SHA-2 256 checksum using string source from the following concatenated parameters:

DateTime (HTTP header)
UserId
TransactionId
Your secret API Key

Successful Response

A successful call will return a HTTP 200 OK with an updated object of POST /processshopbasket response.

POST /promo-codes/{PromoCode}/verify

Can be called to check promo code status for this promo code, shop offer and user. For valid promo codes It returns rebate configured for this promo code. During this request promo code is not used, reserved or applied in any way.

Request

The service expects the following parameters as part of the URL path:

Parameter	Description
PromoCode stringRequired	A reference to LIQUIDs internal transactionID.

The service expects the following parameters as part of the JSON body:

Parameter	Description
UserId stringRequired	The UserId of the user.
ShopOfferId integerOptional	ID of the shop offer that owns the promo code. If empty - promo code can be applied to any shop offer.
StoreId integerOptional	If StoreId provided, tax information is calculated with respect to that store Tax region (otherwise Preferred Store from User profile is taken).

The signature is calculated as a SHA-2 256 checksum using string source from the following concatenated parameters:

DateTime (HTTP header)
UserId
PromoCode
ShopOfferId
Your secret API Key

Successful Response

A successful call will return a HTTP 200 OK response code and the following JSON object in response body:

Parameter	Description
IsValidPromoCode booleanRequired	Identifies if promo code can be used for this shop offer at this period by this user. If promo code is not valid - Reject code will be set.
PromoCodeId integerOptional	ID of promo code found for this entered promo code string. ID should be passed with /ProcessShopBasket request. Only set when IsValidPromoCode is true.
SuccessMessage stringOptional	A human readable response message when the promo code is valid. Only set when IsValidPromoCode is true. Can contain purchase confirmation message.
RebateUnitType stringOptional	Rebate type of this promocode. Currently support only one value - FixedPrice. Only set when IsValidPromoCode is true.
RebateValue numberOptional	Rebate value of this promocode. Only set when IsValidPromoCode is true.
RebatedPrice numberOptional	Best price - take promo code price if better than existing offer price.
RebatedPriceWithoutTax numberOptional	Rebated price without Tax. Only set when IsValidPromoCode is true. For countries with PricePresentationType = IncludingTax, it is calculated as `RebatedPrice` minus `TaxAmount`. For countries with PricePresentationType = ExcludingTax, it is equals to `RebatedPrice`.
TaxAmount numberOptional	Tax amount of the price to be paid in this particular payment. Only set when IsValidPromoCode is true.
TaxPercentage numberOptional	Tax percentage. Only set when IsValidPromoCode is true.
RejectCode stringOptional	A code that can be used to programatically recognize the cause of a promo code rejection. RejectCode will be present in the response if IsValidPromoCode is false. The following values can occur: NotExists: Promo code not found. NotActive: Promo code has been cancelled - not active. NotLive: Promo codes usage outside of active period. UsagePerUserLimitReached: Promo code has per user usages limit configured and limit has been reached by this user TotalUsageLimitReached: Promo code has total usages limit configured and limit has been reached UnknownError: Unknown unexpected error during promo code verification
RejectMessage stringOptional	A human readable cause of rejection message in case a rejection occurred. Only set when RejectCode is set.

Customer integrates with payment provider

Use this flow if you want to integrate towards the payment provider or if you manage your own payment service (eg. your own points program or private label gift cards)

The structure of the shop transactions is the same as for the Shop solution where Liquid Barcodes integrates with payment provider with one main distinction: when customer has decided on product(s) to buy and payment has been reserved, the app should decrypt the outer offer token for each product to compare paid amount and listed product prices. Stop transaction on mismatch.

Subscriptions

This section contains specific methods to deal with purchased Shop Offers that are subscriptions, which means that parameter Type is set to value Subscription.

GET /subscription-identifiers

Get a list of identifiers that can be used for a content object associated with a subscription. This endpoint should be called before calling POST /code/usage.

Request

The service expects the following parameters as part of the URL query-string:

Parameter	Description
UserId stringRequired	The unique and persistent ID that identifies the user which subscription identifiers are requested for.
ContentId integerRequired	The Id of the content.
ScheduleId integerRequired	LIQUID Barcodes' internal Schedule identifier.

The signature is calculated as a SHA-2 256 checksum using string source from the following concatenated parameters:

DateTime (HTTP header)
UserId
ContentId
Your secret API Key

Successful Response

A successful call will return a HTTP 200 OK response code and the following JSON object in response body:

Parameter	Description
AddSubscriptionIdentifierMessage stringOptional	Message with information how to configure identifiers. If message is not empty - it should be shown after GET /subscription-identifiers request.
Identifiers array of objectRequired	An array of identifiers that can be used for this subscription. If it's empty - it means no identifiers are available, so AddSubscriptionIdentifierMessage will contain a message that the app should show to user.
Identifier stringRequired	Identifier.
Title stringRequired	User specified title for this identifier.
CanAddIdentifier booleanOptional	Flag to say when app can add identifier using `PlateNumber` parameter PUT /user. If true - no user identifier and app can add it If false - no user identifier and app can NOT add it If null - user identifier exists, no need to do anything

PUT /subscription/restart

Allows restart a Subscription.

Request

The service expects the following parameters as part of the JSON body:

Parameter	Description
UserId stringRequired	The unique and persistent ID that identifies the user that owns the subscription that will be restarted.
SubscriptionId integerRequired	Id of the Subscription you want to restart (get it from GET /user).

The signature is calculated as a SHA-2 256 checksum using string source from the following concatenated parameters:

DateTime (HTTP header)
UserId
SubscriptionId
Your secret API Key

Successful Response

A successful call will return a HTTP 200 OK response code and the following JSON object in response body:

Parameter	Description
SubscriptionState stringRequired	New Subscription state: Active Downgrading

Multi-User Subscriptions

Multi-user subscriptions allow user to share a subscriptions with family, friends or company members. This section contains the methods to interact with that kind of subscriptions.

GET /subscriptions/{SubscriptionId}/users

Get a list of subscription extra users.

Request

The service expects the following parameters as part of the URL path:

Parameter	Description
SubscriptionId integerRequired	Id of the subscription is done the request for (get it from GET /user).

The service expects the following parameters as part of the URL query-string:

Parameter	Description
UserId stringRequired	The unique and persistent ID that identifies the user that owns the requested subscription.

The signature is calculated as a SHA-2 256 checksum using string source from the following concatenated parameters:

DateTime (HTTP header)
UserId
SubscriptionId
Your secret API Key

Successful Response

A successful call will return a HTTP 200 OK response code and the following JSON object in response body:

Parameter	Description
SubscriptionUsers array of objectRequired	Array of extra subscription users.
Id integerRequired	Group user record Id (will be used to delete it).
PersonalIdentifier stringRequired	Personal detail to identify subscription user (it can be MSN).

POST /subscriptions/{SubscriptionId}/users

Adds a new user to subscription.

Request

The service expects the following parameters as part of the URL path:

Parameter	Description
SubscriptionId integerRequired	Id of the subscription which user is being added to (get it from GET /user).

The service expects the following parameters as part of the JSON body:

Parameter	Description
UserId stringRequired	The unique and persistent ID that identifies the user that owns the subscription which users will be added to.
PersonalIdentifier stringRequired	Personal detail to identify existing user (can be MSN).

The signature is calculated as a SHA-2 256 checksum using string source from the following concatenated parameters:

DateTime (HTTP header)
UserId
SubscriptionId
PersonalIdentifier
Your secret API Key

Successful Response

A successful call will return a HTTP 200 OK response code and the following JSON object in response body:

Parameter	Description
Id integerRequired	Group user record Id (will be used to delete it).
PersonalIdentifier stringRequired	Personal detail to identify existing user (can be MSN).

DELETE /subscriptions/{SubscriptionId}/users/{Id}

Delete existing subscription user.

Request

The service expects the following parameters as part of the URL path:

Parameter	Description
SubscriptionId integerRequired	Id of the subscription which user is being added to (get it from GET /user).
Id integerRequired	Id of user record to delete (get from GET /subscriptions/{SubscriptionId}/users)

The service expects the following parameters as part of the JSON body:

Parameter	Description
UserId stringRequired	The unique and persistent ID that identifies the user whose subscription will be deleted.

The signature is calculated as a SHA-2 256 checksum using string source from the following concatenated parameters:

DateTime (HTTP header)
UserId
SubscriptionId
Id
Your secret API Key

Successful Response

A successful call will return a HTTP 200 OK response code.

Code usage

The function allows app users to enter a code in the app to get reward following a flow like this:

User has a coupon in app that was issued due to a subscription or a purchased shop offer and that coupon allows the user to get a product or service given by a machine (like car wash machine or coffee machine).
When user is at machine place (that can be identified scanning a QR code), coupon is validated using the app that will send POST /code/usage request to Liquid Barcodes. User could take one of the available upselling options coming in GET /upselling-options response to use a different program that the one given by coupon with a configured surcharge.
Once redemption is done, Liquid Barcodes back end will behave in one of the two following ways, depending on chosen configuration:
- Offline: code is validated, coupon marked as redeemed and response given to the app with no other interaction.
- Online: Liquid Barcodes is integrated with the machines and communicates that user wants to use that coupon, giving information about which programa is this code (or upselling option) for. Finally, code is validated, coupon marked as redeemed, response given to the app and machine activated to allow the user take the corresponding product or service.

Besides, this is also used to transfer stamps from paper loyalty card to app and many other functions.

POST /code/usage

This allows the app to use codes issued by Liquid Barcodes. The effect of such a usage is controlled entirely by Liquid Barcodes system.

Request

The service expects the following parameters as part of the JSON body:

Parameter	Description
UserId stringRequired	The UserId of the user
TransRef stringRequired	A 'unique' reference to this transaction. If several ReserveCodes call use the same transaction reference it means that the redemption of these codes should be considered a single transaction.
Code stringRequired	The code to be reserved.
StoreId integerOptional	If the app is simulating a redemption from a store the StoreId must be present.
Position objectOptional	An attempt to acquire geographical location. Should be set whenever an attempt to acquire location was made. In this object you must set either Position or ErrorCode+Error.
Position objectOptional	Must be set when the attempt to acquire geographical location succeeded. The position will be used to attempt identification of which store performed the reservation. Position is given as decimal degrees (DD). Conversion from sexagesimal (DMS): With degrees, add minutes as /60 fractions, add seconds as /3600 fractions.
Longitude numberRequired	Longitude / meridian. Range from -180.0 (180 degrees west) to 180.0 degrees (180 degrees east).
Latitude numberRequired	Latitude / parallel. Range from -90.0 (south pole) to 90.0 degrees (north pole).
Accuracy numberOptional	The accuracy for the position in meters.
Altitude numberOptional	Altitude in meters, relative to sea level.
AltitudeAccuracy numberOptional	The accuracy for the altitude in meters.
Speed numberOptional	Current velocity of the device in meters per second.
Heading numberOptional	Current heading in degrees of clockwise deviation from heading true north (which means that 0, 90, 180, 270 degrees is north, east, south and west, respectively).
ErrorCode stringOptional	Must be set when the attempt to acquire geographical location failed. Error classification. One of: PermissionDenied Unavailable Timeout NotSupported Unknown
Error stringOptional	Must be set when the attempt to acquire geographical location failed. Error message / details. May be a blank string if there are no further details that ErrorCode.
Parameters stringOptional	Customer specific parameters may be set here. We expect an object with string values.
UpsellingOptionId integerOptional	Selected upselling option. It's a value of the field Id in selected option from GET /upselling-options field Id.
MachineProgramId integerOptional	Selected machine program. It's a value of the field MachineProgramId in selected option from GET /upselling-options field MachineProgramId
ReturnUrl stringOptional	In case a user-present payment is configured, this URL should be set to tell the payment provider where to return after the user has done the payment. We expect the URL will be a deep-link back into the app. A query parameter TransactionId will be added to the URL, so that on return the job status on the relevant job can be checked (see the GET /code/usage/paymentjob/{TransactionId}/status service). The return position must poll until a successful or failed transaction is seen. Please see the Polling policy section.
MachineDeviceId stringOptional	DeviceId that should be activated. It can be gotten from GET /upselling-options StoreMachines.MachineDeviceId parameter.

The signature is calculated as a SHA-2 256 checksum using string source from the following concatenated parameters:

DateTime (HTTP header)
UserId
TransRef
Code
Your secret API Key

Successful Response

A successful call will return a HTTP 200 OK response code and the following JSON object in response body:

Parameter	Description
LiquidLogRef integerRequired	A reference to LIQUIDs internal logs.
UniqueCode stringRequired	The reserved unique coupon code.
Timestamp stringOptional	ISO 8601 formatted date and time when the reservation was completed.
SuccessCode stringOptional	The success code that can be used to programmatically recognize the successful result of the operation. Either SuccessCode or RejectCode will be present in the response.
SuccessMessage stringOptional	A human readable response message in case the codes was used. Only set when SuccessCode is set.
SuccessModel stringOptional	In some cases we need to return data to the app after a successful validation. The data model will be customer and situation dependant. This field will be returned as a string. Typically it will contain JSON.
TriggerJobId stringOptional	If this request could not be completed now but turned into a job, this is the job ID. The app must poll the job status from GET /code/usage/job/{TriggerJobId}/status until the result of the job is returned there.
RejectCode stringOptional	A code that can be used to programatically recognize the cause of a rejection. If this field is set it means that the reservation has failed, all other values for this reservation must be disregarded. Either SuccessCode or RejectCode will be present in the response. (Our suggested user response in italic and brackets) The following generic errors can occur: CustomerMismatch,(Invalid code),the requested UniqueCode belongs to a campaign that is not associated with the authenticated user. CampaignInactive,(Invalid code), the requested UniqueCode belongs to a campaign that is no longer / not yet active. CampaignOncePerSaleOnly,(Invalid code), the campaign setup demands that the UniqueCode can only be used once per receipt and this requirement was not fulfilled. ReservationCountTooHigh,(Code is depleted), too many unvalidated+uncancelled reservations exist for this UniqueCode. ScheduleInactive,(Invalid code), the requested UniqueCode belongs to a campaign that is no longer / not yet active. ScheduleStoreMismatch,(Wrong store), the UniqueCode was issued for use in a specific store, this requirement was not fulfilled. ScheduleStoreInRegionMismatch, (Wrong store), the UniqueCode was issued for use in a region which the current store is not part of. ScheduleNoRemainingValidations,(Campaign is depleted), the campaign has a limited amount of validations and there are no validations left. CodeInactive,(Code has expired), the requested UniqueCode has expired. CodeAlreadyUsed,(Code is depleted), the requested UniqueCode only allows one validation and is already validated. CodeNotFound,(Invalid code), the requested UniqueCode is invalid. CodeDepleted,(Code is depleted), the requested UniqueCode has already been used the maximum number of allowed times StoreClosed, (Store is currently closed), enforcing store opening hours has been activated and it's currently outside the opening hours. DailyValidationsExceeded,(Code is depleted today), the code has reached or exceeded the maximum number of validations per day. Blocked,(Code has expired), the code or campaign has been blocked. Used when phasing out a campaign, for example. InvalidSetup, (Administrative error), invalid setup in our system has been detected, the RejectMessage has details. ReservationNotFound, (Reservation not found), should be impossible to achieve in the 1-step validation process of the app, but it means that the reservation is not possible to find at time of validation, usually because more that 15 minutes has passed between the steps of a 2 step validation. The following giftcard specific errors can occur: GiftcardMaxOffsetExceeded GiftcardMinOffsetForZeroBalanceNotMet GiftcardMaxBalanceExceeded GiftcardMaxIncrementsExceeded GiftcardInsufficientBalance GiftcardMixedIncrementDecrement GiftcardBlocked
RejectMessage stringOptional	A human readable cause of rejection message in case a rejection occurred. Only set when RejectCode is set.
UserVisitUrl stringOptional	In case user-present payment is set up, and a payment was required in the code usage operation, the URL that the user must visit is sent here. The user will be redirected to ReturnUrl after.
PaymentTransactionId stringOptional	In case user-present payment is set up, and a payment was required in the code usage operation, PaymentTransactionId is sent here. The app must poll the transaction status from GET /code/usage/paymentjob/{TransactionId}/status until the result of the transaction is returned there.

GET /upselling-options

Get a list of upselling options available for the subscription coupon in particular store.

Request

The service expects the following parameters as part of the URL query-string:

Parameter	Description
UserId stringRequired	The unique and persistent ID that identifies the user that owns the requested subscription coupon.
ContentId integerRequired	The Id of the content.
ScheduleId integerRequired	LIQUID Barcodes' internal Schedule identifier.
StoreId integerRequired	The ID of the store where the coupon will be used.
MachineId integerOptional	Id of the machine to get only its available programs.

The signature is calculated as a SHA-2 256 checksum using string source from the following concatenated parameters:

DateTime (HTTP header)
UserId
ContentId
Your secret API Key

Successful Response

A successful call will return a HTTP 200 OK response code and an array of the following JSON object in response body:

Parameter	Description
Id integerOptional	Id of the upselling option (will be used in POST /code/usage field `UpsellingOptionId`).
MachineProgramId integerOptional	Id of the machine program (will be used in POST /code/usage field `MachineProgramId`).
Name stringRequired	Name of the option to display in the app.
Price numberOptional	Price you should pay to use this option. If null - it's a free option.
PriceWithoutTax numberOptional	Price without tax you should pay to use this option. If null - it's a free option. For countries with PricePresentationType = IncludingTax, it is calculated as `Price` minus `TaxAmount`. For countries with PricePresentationType = ExcludingTax, it is equals to `Price`.
TaxAmount numberOptional	Tax amount of the price to be paid in this particular payment.
TaxPercentage numberOptional	Tax percentage.
UpsellingConfirmationMessage stringOptional	Message to show on upselling confirmation.
StoreMachines array of objectRequired	List of machines located in the store (can be empty list "[]").
Name stringRequired	Name of machine.
MachineDeviceId stringRequired	Machine device Id, that should be used in POST /code/usage on machine activation (for Washtec or trigger of unitec machine).

POST /upselling-options/snooze

Stop showing upselling options on GET /upselling-options for some time.

Request

The service expects the following parameters as part of the JSON body:

Parameter	Description
UserId stringRequired	The unique and persistent ID that identifies the user that owns the subscription coupon which upselling options will be snoozed for.
ContentId integerRequired	The Id of the content.
ScheduleId integerRequired	LIQUID Barcodes' internal Schedule identifier.

The signature is calculated as a SHA-2 256 checksum using string source from the following concatenated parameters:

DateTime (HTTP header)
UserId
ContentId
Your secret API Key

Successful Response

A successful call will return a HTTP 200 OK response code.

GET /code/usage/job/{TriggerJobId}/status

This service lets the app check the status of a job returned by a POST /code/usage request.

REQUEST

The service expects the following parameters as part of the URL path:

Parameter	Description
TriggerJobId stringRequired	The ID of the job to get the status for.

The service expects the following parameters as part of the URL query-string:

Parameter	Description
UserId stringRequired	The UserId of the user.

The signature is calculated as SHA-2 256 checksum using string source from the following concatenated parameters:

DateTime (HTTP header)
UserId
TriggerJobId
Your secret API Key

Successful Response

A successful call will return a HTTP 200 OK response code and the following JSON object in response body:

Parameter	Description
TriggerJobId stringRequired	The ID of the job.
JobStatus stringRequired	The status of the job. Possible values: Pending Done Error
UseCodeResponse objectRequired	The result of the job. This field contains the same JSON object than is sent in POST /code/usage response body.

GET /code/usage/paymentjob/{TransactionId}/status

REQUEST

The service expects the following parameters as part of the URL path:

Parameter	Description
TransactionId stringRequired	The ID of the transaction to get the status for.

The service expects the following parameters as part of the URL query-string:

Parameter	Description
UserId stringRequired	The UserId of the user.

The signature is calculated as SHA-2 256 checksum using string source from the following concatenated parameters:

DateTime (HTTP header)
UserId
TransactionId
Your secret API Key

Successful Response

A successful call will return a HTTP 200 OK response code and the following JSON object in response body:

Parameter	Description
TransactionId stringRequired	The ID of the transaction.
JobStatus stringRequired	The status of the job. Possible values: Pending Done Error
UseCodeResponse objectRequired	The result of the job. This field contains the same JSON object than is sent in POST /code/usage response body.

List of errors

The raw error ID can be read from the X-Liquid-ErrorId HTTP header.

Error ID	HTTP Status	Services	Description
0	500 0	Any.	Unknown error, contact Liquid Barcodes.
1	401 1	Any.	The signature in the X-Liquid-Signature HTTP header was wrong.
2	401 2	Any.	The timestamp in the X-Liquid-Timestamp HTTP header was not parsable or had more than 10 minutes deviation from our current time.
8	500 8	Any.	Unauthorized access. User either not exists or not allowed to use app.
10	500 10	POST /pin	Failed to send PIN.
12	500 12	POST /user	Incorrect PIN.
13	500 13	POST /user	Expired PIN.
14	500 14	POST /user	Msn is blocked. More than 5 attempts to input pin where made. User should wait until PIN will be expired.
22	500 22	POST /user	Cannot find device ID for the user.
23	500 23	GET /validreferral POST /referral	Too many recruitment attempts.
33	500 33	POST /pin	Too many MSNs has been used from the same device.
34	500 34	GET /validreferral POST /referral POST /subscriptions/{SubscriptionId}/users	Missing or invalid MSN.
35	500 35	POST/PIN	Invalid MSN country code.
44	500 44	PUT /user	Failed to update user profile.The response body is an array of UserGroups that wasn't processed + ErrorCode + Message, with error description: 1001 Can't validate code [UserCode] for group tag [GroupId]. 1002 Can't find active group for tag [GroupId] 1003 Can't quit group [GroupId], because user is not member of this group 1004 Group [GroupId] is not user configurable
45	500 45	POST /initialize	Missing or invalid Device ID.
47	500 47	POST /user	Minimum age not met.
48	500 48	Any.	A service requires master consent approval before it can be used.
49	500 59	Any.	Reset user exception. The user has been marked for a reset, force a new POST /initialize, POST /pin, POST /user.
50	500 45	POST /share	Missing or invalid Schedule ID.
51	500 51	POST /referral	Attempted to refer a MSN that was not referable.
52	500 52	POST /device	Missing or invalid language code.
53	500 53	POST /device	Missing or invalid device type.
54	500 54	POST /device	Missing or invalid app version.
55	500 55	POST /user	Invalid PIN.
56	500 56	POST /user	Invalid person name.
57	500 57	POST /user	Invalid address.
58	500 58	POST /user	Invalid city.
59	500 59	POST /user	Invalid post code.
60	500 60	POST /user	Invalid email.
61	500 61	POST /user	Invalid date of birth, should be yyyy-mm-dd.
62	500 62	Any with UserId.	Missing or invalid User ID.
63	500 63	ValidateScratchCard	Invalid card ID.
64	500 64	POST /code/usage	Invalid code
65	500 65	POST /receipts/forward	Provided list of receipt Ids is empty
66	500 66	POST /receipts/forward	Member doesn't have valid e-mail and we can't send him message
67	500 67	POST /pin	Unable to register deleted same day
68	500 68	POST /user	Too many devices has been used for the same MSN
69	500 69	Any with `ContentId`.	Invalid content ID.
73	405 73	GET /points-program/{UserId}/tier-status GET /points-program/{UserId}/history/store-activity GET /points-program/{UserId}/history/points	Points program is not properly configured for a customer
75	500 75	PUT /content-tags/{TagId}/like	Content tag doesn't allow likes
76	500 76	PUT /content-tags/{TagId}/like	Content tag doesn't allow dislikes
77	500 77	PUT /user	Plate number was updated last time less than 30 days
80	500 80	POST /points-program/points/share POST /content/coupons/{ContentId}/stamps/share	Friend user reference (MSN) in the request is empty
81	500 81	POST /content/coupons/{ContentId}/stamps/share	There is not enough stamps on the loylaty card to share
82	500 82	POST /points-program/points/share POST /content/coupons/{ContentId}/stamps/share	User with user reference from the field FriendUserRef in the request is not registered app user
83	500 83	POST /content/coupons/{ContentId}/stamps/share	Friend doesn't have required loyalty card to receive shared stamps
84	500 84	POST /promo-codes/{PromoCode}/verify	Invalid promo code
85	500 85	GET /upselling-options	Invalid store ID
86	500 86	POST /points-program/points/share	Invalid points amount - less or equal 0
87	500 87	POST /points-program/points/share	Not enough points on balance to share
88	500 88	POST /points-program/points/share	Another points transaction problem
89	500 89	PUT/subscription/restart GET /subscriptions/{SubscriptionId}/users POST /subscriptions/{SubscriptionId}/users DELETE /subscriptions/{SubscriptionId}/users/{Id}	Subscription Id value is invalid
90	500 90	PUT/subscription/restart GET /subscriptions/{SubscriptionId}/users POST /subscriptions/{SubscriptionId}/users DELETE /subscriptions/{SubscriptionId}/users/{Id}	Subscription with this Id not found
91	500 91	PUT/subscription/restart GET /subscriptions/{SubscriptionId}/users POST /subscriptions/{SubscriptionId}/users DELETE /subscriptions/{SubscriptionId}/users/{Id}	This subscription doesn't belong to this user
92	500 92	POST/ProcessShopBasket POST/code/usage	User is blocked
93	500 93	POST /subscriptions/{SubscriptionId}/users	Max number of users reached
94	500 94	DELETE /subscriptions/{SubscriptionId}/users/{Id}	Invalid subscription user (Id is less or equal to 0)
95	500 95	POST /subscriptions/{SubscriptionId}/users	Attempt to add subscription owner to a group
96	500 96	POST /points-program/points/share	Limit on points operations exceeded

Change log

Here is a list of all updates to the App API:

version 3.0.4
- Added function to validate codes through the app

version 3.0.3
- Added functionality to process the shop basket through Liquid Barcodes (and not a 3rd party)
- Deprecated OfferToken in Get /ShopOffers (replaced with OfferInstanceId)

version 3.0.1
- Added shop offer category
- Corrected typos

version 3.0.0.1

GET /ratings/categories
- Added CategoryId
- Removed ProductCategory

POST /Ratings
- Added RatingId
- Removed StoreId

version 3.0.0

Change log Unified app feed

General
- All signatures are using SHA-2 256
- Deterministic PIN follows the same registration flow (POST /initialize => POST /pin => POST /user)
- The registration process has significantly changed to accommodate GDPR requirements
- All GET calls now takes the syntax /somefunction?parametername1=parametervalue1&parametername1=parametervalue2
- When mandatory consent has not been given, all functions apart from the registration functions will return a corresponding error code
- When the user needs to be forced to re-register, all functions apart from the registration functions will return a corresponding error code

POST /app
- Name change to POST /initialize
- InstanceId parameter has been removed
- UDID has changed name to DeviceId
- Optional culture parameter when app supports multiple languages (consent text needs to be presented in multiple languages)

POST /pin
- Now used also for deterministic pin applications (returns the PIN in the response)

POST /user
- Emails parameter support multiple emails (array)
- Deprecated PreferredStore is no longer supported
- Can set SelectedPreferredStore from the app (the user's preference)
- Parameters for ApprovedConsents and Revoked consents added
- The response returns the entire user model

PUT /user
- See POST /user

GET /User
- Changed syntax (see general section)
- Emails parameter support multiple emails (array)
- Deprecated PreferredStore is no longer supported
- will get SelectedPreferredStore from the app (the user's preference)
- Parameters for ApprovedConsents and Revoked consents added
- The response returns the entire user model

User Model
- Includes both the PreferredStores (allocated by the system) and SelectedPreferredStores (selected by the user)
- emails parameter includes all emails
- User's selected culture is now included
- The status of all current consents (whether approved or revoked) is returned
- Link to HTML page where the user can get the complete personal details is included

GET /languages
- Changed syntax (see general section)

Coupon object
- Renamed to Content model
- Deprecated CampaignId has been removed
- CouponId is renamed to ContentId
- Deprecated URL has been removed
- TopCouponImageUrl changed name to TopImageUrl
- TopCouponText changed name to TopText
- BottomCouponText changed name to BottomText
- BottomCouponImageUrl changed name to BottomImageUrl
- OverlayURL has changed name to ContentUrl
- Type options has reduced to Coupon and HTML
- Deprecated Version has been removed
- ProductCategory is replaced by the RatingCategory is associated with this content. The RatingCategory includes Id and Name
- Shareable parameter has been replaced by ShareType
- Optional parameter GiftCardBalance has been added
- Activated parameter has been added (currently always true)

GET /coupons
- Changed syntax (see general section)
- Changed name to GET /content
- Complete parameter has been replaced by array of SectionIds
- Returns an array of sections with Id, Name and array of content
- Reset user response is now included as an error code

GET /coupons/group
- Removed

Get Location Based Coupons
- Removed

GET /coupon
- Changed to a POST function
- Changed name to POST /share
- Changed CouponId to ContentId

GET /RatingState
- Changed syntax (see general section)
- Changed name to GET /ratings/categories
- The response contains an array for the first rating opportunity per rating category
- RatingAvailable has been replaced by PendingRating parameter
- Response has been reorganised and parameters renamed

POST /RateProduct
- Changed name to POST /rating
- AppId has been removed
- ShopId has changed name to StoreId

GET /ratings
- Changed syntax (see general section)
- Removed UserId and Appid as parameters are not needed
- ShopId has changed name to StoreId

GET /StoreStats
- Changed syntax (see general section)
- Removed UserId and Appid as parameters are not needed
- ShopId has changed name to StoreId
- ProductCategory has changed name to CategoryId
- ShopName has changed name to StoreName

GET /Stores
- Changed syntax (see general section)
- UserId removed as parameter no longer needed
- Deprecated Tag parameter has been removed

GET /StoreTags
- Changed syntax (see general section)
- Has changed name to GET /storetagids
- UserId removed as parameter no longer needed
- Deprecated Tag parameter has been removed

GET /validreferral
- Changed syntax (see general section)

POST /referral
- No change

POST /device
- No change

GET /receipts
- Changed syntax (see general section)

GET /shopoffers
- Changed syntax (see general section)
- Added MaximumAmount parameter
- Added Local shop offer parameters

List of errors
- Added ConsentAgeException (47), ConsentException (48) and ResetUserException (49) error codes

version 2.1.12

- Corrected email type in the specification

version 2.1.11
- Changed all signature calculations to SHA-2 256 variant (MD5/SHA-1 will continue to work for a time period)

version 2.1.8
- Allows the MSN to be set on the user (only when using deterministic/static pin)

version 2.1.7
- Added additional error codes

version 2.1.6
- Corrected underlying functionality to support ShareByUrl instead of SharedByUrl

version 2.1.5
- Corrected typo in ShareByUrl to SharedByUrl
- Added error ID 46: blacklisted user

version 2.1.3
- Clarified the use of Get / coupon calls

version 2.1.2
- Clarified the use of External StoreId/ShopId in the PUT/POST /User calls

version 2.1.1
- Formatting changes
version 2.1.0
- Added Shop function to display a list of coupons that can be bought in a virtual store
- Added functionality to display receipts in the app
- Added functionality to forward receipts from the app
- Added optional logo field on the Stores data
- Fixed an issue with the new share function

Coupon API

Introduction

The Coupon API allows third parties to issue and obtain various types of content on Liquid Barcodes platform.

IssueRequest, will automatically issue the specified content, eg. a coupon, a game or a survey, to an existing user in the Liquid Barcodes system.
GetContent, will retrieve a content object, most often a coupon, that can be distributed in the way the caller prefers.
Reports, a mechanism to retrieve reports of the activity.
Transaction/reserved, a mechanism to issue coupons based on a purchase in a virtual shop.

In order to ease the use of this API, a Postman collection can be downloaded here.

General principles

Background

This document describes the application interface to issue coupons, or other content, to an individual users or to get a coupon for other distribution. This provides an easy way for 3rd parties to send out coupons from given campaigns to consumers of their choice. The campaigns have to be agreed upon beforehand, and the API only allows coupons for these campaigns.

Nomenclature

A coupon gives user right to a financial discount or rebate when purchasing a product. A coupon can take many forms, such as single use rebate coupons, loyalty cards, reward coupons, limited coupons etc. All these should be treated equally by the app.

HTML based content is some content that is displayed in the in-app web browser, for example games, surveys and weblink images. Common to all these content types is that user is presented with an image that works like a button to open the HTML content.

Shop offer: a content object that end users can buy. Purchasing these items will trigger issue of related content, eg. coupons or gift card balance top up.

A TransactionID is an ID generated by the caller for these functions. The TransactionID should be unique for each call for a give ScheduleId

Any field that is marked with Deprecated, is obsolete but is present to maintain backwards compatibility. It can at any moment be removed from this API, and shouldn't be used

Headers

The recommended content type for the requests sent to our services is JSON, i.e. HTTP header Content-Type: application/json.

For every service request the following HTTP headers must be present:

X-Liquid-TimeStamp– date in ISO-8601 format. e.g. 2014-03-06T13:11:04Z
X-Liquid-Signature - signature calculated in the manner described below.

Note that a difference of more than 15 minutes between the current time and the DateTimeHeader will be rejected

Security

You are intended to connect to this API through your server and not directly from a webclient, In particular all code that is handling the calculation of signature and the security mechanisms of this API has to be done on the server side, Failure to implement it in such fashion means that we can disable you access at any point at Liquid Barcodes discretion. Also your implementation should be designed in such a way that re-enginering the webclient by 3rd parties are not able to create a 'infinite' coupon generator. Safety mechanisms should be put in place, e.g. a limit to the number of attempts from a given computer over a specific session etc.

All calls rely on HTTP Basic Authorization, and username and password are provided by LIQUID. The security credentials and additional details (the API key) is available on request.

The API Key is strictly confidential and must not be exposed. The customer is responsible to secure the API key. Liquid Barcodes management APIs relies on API keys being handled securely and do not include check for unusual/abusive operations.

Signature calculation

The services require the use of an SHA-2 256 checksum of the X-Liquid-Date header, one or more request parameters and a secret API Key. The API Key is known only by LIQUID and the customer. Each of the service definitions in the next chapter will specify which parameters should go into the checksum calculation.

Example:

The current UTC timestamp is 2014-03-06T13:11:04Z
The secret API Key is liquid1234
The parameters used for this example functions are:
- ParameterA = 5824
- ParameterB = abcd
- ParameterC =99

The calucation of the SHA-2 256 signature is given by (detailed in each function call):

SHA-2 256 checksum of: Timestamp + ParameterA + ParameterB + ParameterC + Your secret API Key

The source for the checksum would then be:

SHA-2 256("2014-03-06T13:11:04Z5824abcd99liquid1234") = ae76588d46686f300efba39d674d178863607f654f22d00a6cb4e9ba05d73e4f

Request Liquid Barcodes to issue content

The Coupon API – IssueRequest is a web service that allows you to issue one specific coupon at a time to one specific user using Liquid Barcodes’ distribution mechanisms. This can be Liquid Barcodes’ app-API (see above, Liquid Barcodes will populate the user’s record with the correct coupon) or Liquid Barcodes’ SMS handler. When calling the IssueRequest, the key information you provide is which coupon you want (schedule ID), which user should receive the coupon (UserReference) and your credentials.

POST /IssueRequest

Service: https://api.barcodes.no/v3/IssueRequest

Request

The service expects the following parameters as part of the JSON body:

Parameter	Description
TransactionId stringRequired	The transactionID for this transaction. It must be an ID that identifies this transaction uniquely.
ScheduleId integerRequired	LIQUID Barcodes' internal Schedule identifier.
UserRef stringRequired	The unique reference to the user. Accepted values are the unique Liquid Barcodes generated UserId, Foreign Id, e-mail or an MSN (Note that MSN should be formatted with the country code i.e. 4798765432 for Norway). If the ScheduleID is an app coupon and the user reference is unknown to Liquid Barcodes, the coupon will be issued if the user registers in the app within 2 weeks after issue request has been sent to Liquid Barcodes.
ExpirationDate stringOptional	ISO 8601 formatted expiration date and time of the coupon. Note: this date cannot precede or exceed the campaign start and stop dates. In case of conflict the expiration date will be moved to fit inside the period (if possible). If left out the default expiration date will be used (either static or a certain time period from the date of issue)
ExternalRef objectOptional	Custom key - string value JSON object. A reference that identifies the call in a meaningful way for the caller. The value here will be propagated all the way to the reports that gets generated.
TopSMSText stringDeprecated	A text that is to be inserted before the SMS content that LIQUID provides. Will only be used when issuing coupons. Must be in accordance with the GSM 03.38 character set. Only applicable if Destination = 'SMS'.
BottomSMSText stringDeprecated	A text that is to be inserted after the SMS content that LIQUID provides. Will only be used when issuing coupons. Must be in accordance with the GSM 03.38 character set. Only applicable if Destination = 'SMS'.
Culture stringOptional	The culture that should be used for issued instance (Culture should be supported by customer, if not - exception will be thrown).

The signature is calculated as a SHA-2 256 checksum using string source from the following concatenated parameters:

DateTime (HTTP header)
ScheduleId
UserRef
TransactionId
Your secret API Key

Successful Response

A successful call will return a HTTP 200 OK response code and the following JSON object in response body:

Parameter	Description
ResponseStatus objectOptional	Object that contains information about the status of the process.
Message stringOptional	Message that informs about the status of the issue request. In case of success, it will be "Push to `{UserRef}` successful".
RejectCode stringOptional	A code that can be used to programatically recognize the cause of a rejection. If this field is set it means that the reservation has failed, all other values for this reservation must be disregarded. The following values can occur: NoContentIssued - the content was not issued Exception - when there were unpredictable exceptions during the issue
RejectMessage stringOptional	A human readable cause of rejection message in case a rejection occurred. Only set when `RejectCode` is set.

Get content from Liquid Barcodes

The Coupon API – GetContent is a web service that allows you to obtain one specific coupon, survey or game at a time for your own distribution. When calling the GetContent service, the key information you provide is which content you want (schedule ID), which user should receive the coupon (UserReference) and your credentials. Liquid Barcodes will then respond with a coupon, survey or game object, from which you can select the relevant information necessary for your distribution.

How to build a coupon image

The coupon image can be built with the following five elements:

TopCouponImageUrl
TopCouponText
BarcodeImageUrl
BottomCouponText
BottomCouponImageUrl (Often not present)

You are required to use all 5 elements to depict the coupon for each element that is present. The coupon image can be build the following way:

POST /GetContent

Some content will be generated the requested schedule, and is available for discretionary distribution.

Service: https://api.barcodes.no/v3/GetContent

Request

The service expects the following parameters as part of the JSON body:

Parameter	Description
Culture stringOptional	The culture that should be used for issued instance (Culture should be supported by customer, if not - exception will be thrown).
ExternalRef objectOptional	Custom key - string value JSON object. A reference that identifies the call in a meaningful way for the caller. The value here will be propagated all the way to the reports that gets generated.
MediaType stringRequired	The media type the coupon is going to be used for. Valid values are 'SMS', 'App', 'email' and 'paper'. Use 'paper' for codes campaigns.
ScheduleId integerRequired	Liquid Barcodes' internal Schedule identifier. You can find this in Liquid Barcodes dashboard by clicking on the campaign name on the front page.
TransactionId stringRequired	The transactionID for this transaction. It must be a unique ID defined by you.
UserRef stringRequired	Your reference for the recipient of this coupon. If you use the same ID, some campaigns will return the same coupon for the same UserRef.

The signature is calculated as a SHA-2 256 checksum using string source from the following concatenated parameters:

DateTime (HTTP header)
ScheduleId
TransactionId
MediaType
UserRef
Your secret API Key

Successful Response

A successful call will return a HTTP 200 OK response code and the following JSON object in response body:

Parameter	Description
ScheduleId integerRequired	Liquid Barcodes' internal schedule identifier.
ContentId integerOptional	Liquid Barcodes' internal content identifier. Only set for `ContentType`: Coupon, Game or Survey
TopCouponImageUrl stringOptional	URL to the top image part of the coupon. If present this is a required component of the coupon. Only set for `ContentType`: Coupon
TopCouponText stringOptional	Top text for the coupon which can be 1-3 lines of text. The most common use of this parameter is the text "Valid to ...", but it can have other information as well. If present this is a required component of the coupon. Only set for `ContentType`: Coupon
BarcodeImageUrl stringOptional	Url to a scannable image that represents the UniqueCode. This will have a small rectangular area of white around it. May include the unique coupon code below the barcode. This is a required component of the coupon. Only set for `ContentType`: Coupon
BottomCouponText stringOptional	Bottom text for the coupon. If present this is a required component of the coupon. Only set for `ContentType`: Coupon
BottomCouponImageUrl stringOptional	URL to a bottom image of a coupon. If present this is a required component of the coupon. Only set for `ContentType`: Coupon
ContentUrl stringOptional	The URL to the complete content as a prepackaged html file (this HTML file references the fields: `TopCouponImageUrl`, `TopCouponText`, `BarcodeImageUrl`, `BottomCouponText` and `BottomCouponImageUrl`).
UniqueCode stringOptional	The unformatted unique code. Only set for `ContentType`: Coupon
ContentType stringRequired	Will return the content type. Currently the only allowed values are: Coupon Survey Game HTML
ContentState stringRequired	State of the content. It can take following values: New Existing
Description stringRequired	A textual description of the content.
AmountLeft integerOptional	Shows the number of times this content can be used. Only set for `ContentType`: Coupon
ExpiryDate stringRequired	ISO 8601 formatted time/date after which the content will expire.
CouponType stringOptional	Type of coupon. It can be: Coupon Giftcard Only set for `ContentType`: Coupon
GiftCardBalance numberRequired	Balance of the giftcard (points card). Only set for `ContentType`: Coupon
ResponseStatus objectOptional	Object that contains information about the status of the process.
Message stringOptional	Message that informs about the status of the issue request.
RejectCode stringOptional	A code that can be used to programatically recognize the cause of a rejection. If this field is set it means that the reservation has failed, all other values for this reservation must be disregarded. The following values can occur: NoContentIssued - the content was not issued IncorrectConfiguration - The configuration is incorrect ContentUnavailable - when coupon already expired or is missed
RejectMessage stringOptional	A human readable cause of rejection message in case a rejection occurred. Only set when `RejectCode` is set.

Get report from Liquid Barcodes

The Coupon API – Get Report is a web service that allows you to get various raw data sets for a specific period (day, week, month). The file format is csv.

POST /report

Will fetch the specified report. The standard format of the report is a csv file.

Service: https://api.barcodes.no/v3/Report

Request

The service expects the following parameters as part of the JSON body:

Parameter	Description
ReportName stringRequired	The name of the report. Currently the following reportnames are supported (required parameters in bracket): CouponIssueReport (Period, Date) CouponValidationReport (Period, Date) GameIssueReport (Period, Date) GamesPlayReport (Period, Date) SettlementReport (Period, Date) SubscriptionsReport (none) SubscriptionsSettlementReport (Date) MembersReport (none) CouponCampaignValidationReport (ScheduleId) SurveyCampaignReport (ScheduleId) ShopTransactionReport (ScheduleId or Period, Date) MultiSubscriptionReport (none) ReceiptsReport (Period, Date) PointsTransactionReport (Period, Date) PointsTransactionDetailedReport (Period, Date) PointsBalanceReport (none) ShopSettlementReport (ScheduleId or Period, Date) BlockedMembersDataReport (none) LimitRulesTriggerReport (Period, Date) RecruitingReport (Period, Date)
Period stringOptional	The period for the report. Currently the following options are supported: 'Day', 'Week', 'Month'.
Date stringOptional	The startdate for the report. The date should be the first day in the period you request, e.g. period = 'Month' and Date = '2015-07-01' would give you the report for July 2015.
ScheduleId integerOptional	The ScheduleID for the campaign you want the report for.

The signature is calculated as a SHA-2 256 checksum using string source from the following concatenated parameters:

DateTime (HTTP header)
ReportName
Period
Date
ScheduleId
Your secret API Key

Successful Response

A successful call will return a HTTP 200 OK response code and the following JSON object in response body:

Parameter	Description
ReportLink stringOptional	Link to the requested report.
ResponseCode stringOptional	A code that can be used to programatically recognize the state of response. The following values can occur: Ok - report is ready and field ReportLink should be filled. GeneratingReport - report is not ready yet and is being generated.
ResponseMessage stringOptional	A human readable state of response.

If report does not exist service replies with ResponseCode "GeneratingReport" and report generation will be started, you can either re-try the request in 10 minutes or you can use the Coupon Event API to register a listener and get a callback when the report is ready.

Error response

If the service fails it will reply with a non-HTTP-200 response and the following JSON object in response body:

Parameter	Description
RejectCode stringOptional	A code that can be used to programatically recognize the cause of a rejection. The following values can occur: NotFound - when report can't be found
RejectMessage stringOptional	A human readable message for the cause of rejection.

Ask Liquid Barcodes to issue content purchased in shop

NOTE: this service should only be used when Customer integrates with payment provider.

The following paragraph describes the functionality required to issue a coupon based on a purchase in your app. This functionality consists of three parts:

Shop front-end, this is the virtual store where the consumer can choose which products he wants to buy.
Payment provider, this is a third party or a back-end to a payment provider that handles the transaction of real money. This part needs to communicate with the app once the user has selected a particular offer to purchase. This part is not part of the existing Liquid Barcodes offering
Issuing purchased coupons, this is a function of the Liquid Barcodes Coupon API that enables the payment provider to issue the coupon that was purchased to the user's app. The issued coupon will appear in one of the four sections available through Get /coupons. Only this part of the shop functionality is described in this document

The interaction flow for the while process is as follows (where this document only handles step 5 )

The App calls the function ShopOffers and gets a list of offers that can be bought for a certain price by the consumer. This call will provide all the details necessary for the consumer to make a choice, and all the necessary details for issuing coupons.
The consumer selects which offer he wants by putting them into a basket.
When checkout of the basket is selected, the app sends a request to the App provider's back-end for execution of the order.
The back-end will request the baskets grand total to be reserved by the payment provider (note that this is not the actual payment, but reserving an amount of money on the consumers account).
1. If the step above fails, an appropriate payment-related error message should be provided to the consumer, and the process aborted.
For each item on the order, the App provider should contact LB server to issue each individual coupon. Use the Coupon API for these requests. For each call the response will be either:
1. Coupon has been issued successfully and should be counted towards the final payment.
2. Coupon is not issued successfully and should not be counted towards the final payment.
The App provider's back-end should commit the final transaction value to the payment provider.
Appropriate information should be given to the user that the process has completed, how much was paid and, if any, which coupons could not be issued.

Offer tokens

The offer token will be sent from LIQUID Barcodes to the mobile app (see the section for mobile app services above). The mobile app will forward the offer token to the payment provider for items that the user wants to buy. Encrypted in the offer token are item details that are guaranteed to untampered by a compromised mobile application or any other security concerns the data may be exposed to after leaving LIQUID Barcodes before arriving at the payment provider. The offer token is only decryptable by the payment provider private key. In preparations the payment provider must create a public/private key pair and send LIQUID Barcodes the public key.

The format of the offer token is two BASE64-encoded string separated by a pipe (|) character. The parts are:

An encrypted PAYLOAD-KEY, encrypted with the payment providers public key.
A JSON payload (specifed below) encrypted by key PAYLOAD-KEY.

Thus, the payment providers process to access the payload will be:

Split the offertoken in two pieces, separated by pipe (|): KEY-X, PAYLOAD
BASE64-decode KEY-X. Decrypt (RSA-1024) it with your private key. You now have PAYLOAD-KEY.
Split PAYLOAD-KEY in two pieces, separated by pipe (|), you will get the IV (Initialization Vector) and key needed for payload decryption.
BASE64-decode PAYLOAD. Decrypt (Rijndael) it with the IV and the key from PAYLOAD-KEY.
JSON-deserialize the decrypted payload into model as specified below.

Parameter	Description
Expiration stringRequired	Date and time this offer token expired. Make sure to reject expired offer tokens.
Item objectRequired	Information about the item the user selected.
ShopOfferId integerRequired	The unique ID for this particular offer.
PaymentProviderId stringRequired	Used by Liquid Barcodes to identify which payment provider is requsting us (see POST /transactions/reserved service).
RetailPrice numberRequired	The price to the consumer.
Currency stringRequired	Will always be the currency of the app's country (one app, one country).
MaximumAmount integerOptional	The maximum number of times the offer can be bought. If not present or NULL, it means unlimited.
Type stringRequired	Reserved for future use, will presently always be 'Shop'.
CategoryId integerOptional	ID of shop offer's category.
InternalOfferToken stringRequired	Must be forwarded to LIQUID when payment was successful in POST /transactions/reserved service.

Decrypting offer token in .NET / C#

See the following code example:
https://bitbucket.org/snippets/liquid_barcodes/7Eqkr

POST /transactions/reserved

NOTE: this service should only be used when Customer integrates with payment provider.

After a payment has been completed the payment provider must make a request to this service. Make sure to check paid amount versus product price from Liquid Barcodes. Liquid Barcodes will then issue coupons accordingly.

Service: POST https://api.barcodes.no/v3/transactions/reserved

Request

The service expects the following parameters as part of the JSON body:

Parameter	Description
PaymentProviderId stringRequired	The payment provider ID received in the offertoken from the app.
PaymentRef stringRequired	A reference to the completed transaction in the payment providers system. Will be used when contacting the payment provider for support issues.
InternalOfferTokens array of stringRequired	The list of internal offer tokens, still encrypted, received in the payment providers decrypted offer token. Only the tokens of the items that were successfully paid must be included.

The signature is calculated as a SHA-2 256 checksum using string source from the following concatenated parameters:

DateTime (HTTP header)
PaymentProviderId
all InternalOfferTokens (concatenated, separated by nothing)
Your secret API Key

Successful Response

A successful call will return a HTTP 200 OK response code and the following JSON object in response body:

Parameter	Description
LogReferenceId integerOptional	An ID of our internal logs, the payment provider should ideally link this to the payment. Should be used when contacting LIQUID Barcodes for support issues.
Result array of objectOptional	Array of the following object, with a status result per InternalOfferToken
InternalOfferToken stringRequired	Token to identify payment.
ContentID integerOptional	This is the ID of the content that was bought (normally a coupon) It can be used to navigate to the right content in the appfeed.
StatusCode stringRequired	'OK' for success. Error code when not successful, that can be one of: BadRequest Forbidden Gone InternalServerError
StatusMessage stringOptional	Blank when successful. Error details when not successful. It can be: With StatusCode = BadRequest: InternalOfferToken expired Shop offer is inactive With StatusCode = Forbidden: Duplicate call Maximum amount exceeded With StatusCode = Gone: Campaign is out of codes With StatusCode = InternalServerError: Error on coupon issue InternalServerError
Content array of objectRequired	List with the issued content.
ContentId integerOptional	LIQUID Barcodes internal content identifier.
ContentType stringOptional	Type of the content. Currently the only allowed values are 'Coupon', 'Survey', 'Games' and 'HTML'
RejectCode stringOptional	A code that can be used to programatically recognize the cause of a rejection. If this field is set it means that the reservation has failed, all other values for this reservation must be disregarded. The following values can occur: Unknown
RejectMessage stringOptional	A human readable cause of rejection message in case a rejection occurred. Only set when RejectCode is set.

Orders

Order model

This is the structure of the order object served in the GET /orders/list/{storeref} request:

Parameter	Description
OrderId stringRequired	Order ID
LocalPickUpTime stringRequired	Pick up time (local timezone). Format - yyyy-MM-ddTHH:mm:ss
Comment stringOptional	Comment to order
Products array of objectRequired	Array of products in this order.
Title stringRequired	Title of the ordered product.
Amount integerRequired	Amount of the ordered product.
Price numberRequired	Price of the ordered product.
Currency stringRequired	Currency used to pay the ordered product.
ProductCodes stringOptional	Required Product Codes if configured in 'Order and Pay' campaign. Codes will be separated by comma (,).
Customizations array of objectRequired	Array that contains user customizations for the ordered product.
Type stringRequired	Customization type. It can be: Selection AddOn Removal
ProductCode stringRequired	Code of customization product.
Description stringRequired	Description of customization product.
Amount integerOptional	If type is 'AddOn', it is set to indicate amount of added product.

GET /orders/list/{storeref}

It will fetch sorted by pick up date filtered list of orders for this store.

Request

The service expects the following parameters as part of the URL path:

Parameter	Description
StoreRef stringRequired	The unique store ID.

The service expects the following parameters as part of the URL query-string:

Parameter	Description
IsReceivedByPos integerOptional	Value to filter orders received by POS. It can be: 0: only return not Recieved By POS orders. 1: only return Recieved By POS orders. No value means no filter.
MaxPlaced stringOptional	If set, only return orders placed before this point in time, non-inclusive. Format - yyyy-MM-ddTHH:mm:ss.
MinPlaced stringOptional	If set, only return orders placed after this point in time, inclusive. Format - yyyy-MM-ddTHH:mm:ss.
MaxDelivery stringOptional	If set, only return orders delivered before this point in time, non-inclusive. Format - yyyy-MM-ddTHH:mm:ss.
MinDelivery stringOptional	If set, only return orders delivered after this point in time, inclusive. Format - yyyy-MM-ddTHH:mm:ss.

Note: If none of MaxPlaced, MinPlaced, MinDelivery or MaxDelivery filters is set, only orders with DeliveryDate in future will be returned.

The signature is calculated as an SHA-2 256 checksum using string source from the following concatenated parameters:

DateTime (HTTP header)
StoreRef
Your secret API Key

Successful Response

A successful call will return a HTTP 200 OK response code and the following JSON object in response body:

Parameter	Description
Orders array of objectRequired	Array of order model objects.

Error response

If the service fails it will reply with a non-HTTP-200 response and the following JSON object in response body:

Parameter	Description
RejectCode stringOptional	A code that can be used to programatically recognize the cause of a rejection. The following values can occur: NotFound - Store is not resolved. StoreRef is not recognized Unknown - Server error
RejectMessage stringOptional	A human readable message for the cause of rejection.

POST /orders/received/{StoreRef}

This method is used to mark as received by POS a list of orders for the indicated store with the timestamp of this request.

Request

The service expects the following parameters as part of the URL path:

Parameter	Description
StoreRef stringRequired	The unique store ID.

The service expects the following parameters as part of the JSON body:

Parameter	Description
OrderIds array of stringRequired	Array of orders IDs that will be marked as received by POS

The signature is calculated as a SHA-2 256 checksum using string source from the following concatenated parameters:

DateTime (HTTP header)
StoreRef
Your secret API Key

Successful Response

A successful call will return a HTTP 200 OK response code and the following JSON object in response body:

Parameter	Description
OrdersProcessedCount integerRequired	Number of orders processed

Error response

If the service fails it will reply with a non-HTTP-200 response and the following JSON object in response body:

Parameter	Description
RejectCode stringOptional	A code that can be used to programatically recognize the cause of a rejection. The following values can occur: NotFound - Store is not resolved. StoreRef is not recognized Unknown - Server error
RejectMessage stringOptional	A human readable message for the cause of rejection.

POST /orders/links/{StoreRef}

This service makes it possible to generate unique link to "View orders" page for a single store. To be used on combination with "Order and pay". The webpage gives store merchant overview of incoming orders without need for logging into local dashboard.

Service: POST https://api.barcodes.no/v3/orders/links/{StoreRef}

Request

The service expects the following parameters as part of the URL path:

Parameter	Description
StoreRef stringRequired	The unique store ID.

The signature is calculated as a SHA-2 256 checksum using string source from the following concatenated parameters:

DateTime (HTTP header)
StoreRef
Your secret API Key

Successful Response

A successful call will return a HTTP 200 OK response code and the following JSON object in response body:

Parameter	Description
Link stringOptional	Link to orders page.
JsonLink stringOptional	Link to list of orders in JSON format.
RejectCode stringOptional	A code that can be used to programatically recognize the cause of a rejection. The following values can occur: NotFound
RejectMessage stringOptional	A human readable message for the cause of rejection.

Upload product codes

This service allows uploading product codes list. This is useful for Dashboard product codes deal and categorization for POS. Products can be categorized using up to three category levels.

Let's take the following example:

Oranges:
- ProductCode: 123
- Level1Id: FOOD
- Level2Id: FRUIT
- Level3Id: CITRUS

Blackberries:
- ProductCode: 456
- Level1Id: FOOD
- Level2Id: FRUIT
- Level3Id: BERRIES

Chocolate chip cookies:
- ProductCode: 789
- Level1Id: FOOD
- Level2Id: SNACK
- Level3Id: COOKIES

Full product codes will be formed in the following way:

Oranges:
FOOD-FRUIT-CITRUS-123
Blackberries:
FOOD-FRUIT-BERRIES-456
Chocolate chip cookies:
FOOD-SNACK-COOKIES-789

Then, Dashboard will allow you to introduce expressions like the following examples by selecting the needed category:

To include the whole FOOD category (includes the three products and every other one in the same this category):
FOOD-*
To include the whole FRUIT sub-category (includes Oranges, Blackberries and every other one in the same these two categories):
FOOD-FRUIT-*
To include the whole CITRUS sub-sub-category (includes Oranges and every other one in the same these three categories):
FOOD-FRUIT-CITRUS-*
To include just Chocolate chip cookies:
FOOD-SNACK-COOKIES-789

POST /product-codes/upload

Service URL: https://api.barcodes.no/v3/product-codes/upload

Request

The service expects the following parameters as part of the JSON body:

Parameter	Description
ProductCodes array of objectRequired	Array of product codes that will be uploaded.
ProductCode stringRequired	Unique identifier for the product.
Description stringRequired	Product description.
Level1Id stringOptional	Unique Id of the level 1 of the product hierarchy to which the above product belongs.
Level1Name stringOptional	Description of level 1.
Level2Id stringOptional	Unique Id of the level 2 of the product hierarchy to which the above product belongs.
Level2Name stringOptional	Description of level 2.
Level3Id stringOptional	Unique Id of the level 3 of the product hierarchy to which the above product belongs.
Level3Name stringOptional	Description of level 3.

The signature is calculated as a SHA-2 256 checksum using string source from the following concatenated parameters:

DateTime (HTTP header)
Your secret API Key

Successful Response

A successful call will return a HTTP 200 OK response code and the following JSON object in response body:

Parameter	Description
UploadedRowsCount integerRequired	Number of rows uploaded.

Error response

If the service fails it will reply with a non-HTTP-200 response and the following JSON object in response body:

Parameter	Description
RejectCode stringOptional	A code that can be used to programatically recognize the cause of a rejection. It can take the following values: Unknown - Server error
RejectMessage stringOptional	A human readable message for the cause of rejection.

Set Store Devices Status

PUT /devices/status

Service: PUT https://api.barcodes.no/v3/devices/status

Request

The service expects the following parameters as part of the JSON body:

Parameter	Description
Devices array of objectRequired	An array of device status information.
DeviceId stringRequired	Unique device identifier.
Status stringRequired	New status of device. Support values: Available OutOfService

The signature is calculated as a SHA-2 256 checksum using string source from the following concatenated parameters:

DateTime (HTTP header)
For each device in Devices list:

DeviceId
Status

Your secret API Key

Successful Response

A successful call will return a HTTP 200 OK response code.

GET /campaigns/list

This method will fetch all the active and planned campaigns.

Service: GET https://api.barcodes.no/v3/campaigns/list

Request

The service has no arguments but the standard headers.

The signature is calculated as a SHA-2 256 checksum using string source from the following concatenated parameters:

DateTime (HTTP header)
Your secret API Key

Successful Response

A successful call will return a HTTP 200 OK response code and the following JSON object in response body:

Parameter	Description
Country stringRequired	Customer's country
SectionId integerOptional	Section ID
CategoryId integerOptional	Shop offer category
CampaignName stringRequired	Campaign Name
CampaignId integerRequired	CampaignId
CampaignStartDate stringRequired	Campaign Start Date
CampaignStopDate stringRequired	Campaign Stop Date
ScheduleName stringRequired	Schedule name
ScheduleId integerRequired	Schedule Id
ScheduleStartDate stringRequired	Schedule Start Date
ScheduleStopDate stringRequired	Schedule Stop Date
CouponImageUrl stringRequired	Coupon image url
ThumbImageUrl stringRequired	Thumb image url
BackImageUrl stringRequired	Back image url
Description stringRequired	Description cultured
ContentType stringRequired	Coupon, Survey, Game, ShopOffer
MediaType stringRequired	AppGeneric, Email, Sms, Paper, PushNotification, etc.
Tags array of objectRequired	Array of the tags that campaign has.
Id integerRequired	Id of the tag.
Type ContentTagTypeRequired	Type of the tag. It can be: Category Brand
CustomerId integerRequired	Id of the customer that owns the tag.
ListId integerRequired	Id of the list that the tag belongs to.
Name stringRequired	Name of the tag.
NameCultureData stringRequired	Culture of tag name.
ImageUrl stringRequired	Url of the tag image.
ImageCultureUrls stringRequired	Culture of tag image url.
Likable booleanRequired	Boolean field that indicates if tag is likable.
NoHate booleanRequired	Boolean field that indicates if tag is not hateable.
Dislikable booleanRequired	Boolean field that indicates if tag is dislikable.
Active booleanRequired	Boolean field that indicates if tag is active.
AdditionalInfo1 stringRequired	Additional info 1
AdditionalInfo2 stringRequired	Additional info 2
AdditionalInfo3 stringRequired	Additional info 3
CodesData objectOptional	Only applicable for 'Import codes' campaign. Contains data about imported codes set.
TotalCodes integerOptional	Total number of imported codes.
UsedCodes integerOptional	Used number of imported codes.
RemainingCodes integerOptional	Remaining number of imported codes.
EarliestCodeExpiryDate stringOptional	The earliest expiration date of the imported codes.
ParentScheduleId integerOptional	Schedule ID of parent (only populated if parent is ShopOffer)
FollowUpScheduleIds array of integerOptional	Array of child schedule IDs (only populated for single purchase ShopOffers).
FollowUps array of objectOptional	Array of nested campaign models like the one described in this table (only populated for single purchase ShopOffers).

List of errors

All errors will contain these parameters in their body. Errors may be detected by the presence of RejectCode.

Parameter	Description
Parameter	Description
RejectCode	Logically recognizable problem code.
RejectMessage	English human readable error message.

Change log

Here is a list of all updates to the Coupon API:

version 3.2.9
- Added ShopTransactionReport report name to GetReport

version 3.2.8
– Language is now optional parameter for IssueRequest and GetContent

version 3.2.7
– Replaced X-Liquid-Date header with X-Liquid-Timestamp header to be in line with the other specifications. The X-Liquid-Date header
is now deprecated (but will work for until the next major revision)

version 3.2.6
– Specified standard report format for GetReport (csv)

version 3.2.4
– Changed all signature calculations to SHA-2 256 variant (MD5/SHA-1 will continue to work for a time period)

version 3.2.3
– Added better error response codes
– Changed GetReports logic to initiate a report to be generated when not found
– Removed Yearly as an option when getting reports

version 3.2.1
– Added e-mail as user reference option to IssueRequest function

version 3.2.0
– Added GetContent function, allowing to get coupons, surveys and games
– Deprecated GetCoupon as GetContent replaces the function

version 3.1.0
– Added the functionality to issue content based on what has been purchased in the virtual shop in the app

version 3.0.6
– Clarification that all implementations towards this API should be server-to-server.
– Added requirement that all implementation should implement mechanisms to prevent spamming and allowing 3rd party ‘infinite coupon generators’

Coupon Event API

Introduction

This is a web service that allows you to check the status on coupons and other content from Liquid Barcodes. The API offers a subscription service and after such registration, Liquid Barcodes will post update events for the specified content. This update can also include information to trigger rewards in third party systems, such as tokens, data or bonus points.

This is an extension to the Coupon API.

The purpose of this specification is to describe the mechanisms for how users of the coupon API can get callbacks on specific events in the Liquid Barcodes system. The mechanism consists of two parts:

Registering a listener with the Liquid Barcodes system. This provides Liquid Barcodes with the URL and credentials required for us to send the events to your system in a secure manner
Specifications of endpoints that will receive the events and the format we will send the event information in.

In order to ease the use of this API, a Postman collection can be downloaded here.

To use the APIs, Liquid Barcodes will share credentials including API key. The API Key is strictly confidential and must not be exposed. The customer is responsible to secure the API key. Liquid Barcodes management APIs relies on API keys being handled securely and do not include check for unusual/abusive operations.

Subscribe to events

General principles

All services in this section:

Are hosted on https://api.barcodes.no/v3
Are only to be used via HTTPS
Require HTTP BASIC authentication. The credentials will be provided by Liquid Barcodes.
Require the following headers set:

Header	Description
Header	Description
X-Liquid-Timestamp	Timestamp (format ISO-8601) when you sent the request, old request will be denied.
X-Liquid-Nonce	A unqiue random value.
X-Liquid-Signature	The SHA-2 256 signature of the above timestamp + nonce + your secret API Key. The secret API Key will be given to you by LB.

POST /listener

This method allows to register a listener that will receive events (see next chapter).

NOTE: Based on the authentication we identify which customer you are. You can not register a listener to any schedule ID you do not own.

Request

The service expects the following parameters as part of the JSON body:

Parameter	Description
BaseUrl stringRequired	The base URL we will send the events and where we expect to have a listener ready. HTTPS is required.
BaseUrlAuth objectRequired	Authentication parameters for the BaseUrl that LB must use.
Type stringRequired	Authentication type. It can be: OPEN: no authentication used. BASIC: basic authentication used.
Username stringOptional	In case that BASIC authentication type was chosen, Username to use.
Password stringOptional	In case that BASIC authentication type was chosen, Password to use.
EventTypes array of stringRequired	Event types that should be sent to the listener. Possible values are: Status Usage Rewards Report ImportedCodesLowLevel
ScheduleIds array of integerOptional	Array of schedule IDs that the listener should receive events for. If you specify no schedules, the listener will receive events for all schedules you have access to.
Email stringOptional	Email where "ImportedCodesLowLevel" event will be sent in case of subscribed to it.

The signature is calculated as a SHA-2 256 checksum using string source from the following concatenated parameters:

DateTime (HTTP header)
X-Liquid-Nonce
BaseUrl
BaseUrlAuth.Type
BaseUrlAuth.Username
BaseUrlAuth.Password
All EventTypes concatenated
All ScheduleIds concatenated
Your secret API Key

Successful Response

A successful call will return a HTTP 200 OK response code and the following JSON object in response body:

Parameter	Description
ListenerId integerRequired	The ID of registered listener.

GET /listeners

This method will return the list of your active listeners.

Request

The service has no arguments but the standard headers.

The signature is calculated as a SHA-2 256 checksum using string source from the following concatenated parameters:

DateTime (HTTP header)
X-Liquid-Nonce
Your secret API Key

Successful Response

A successful call will return a HTTP 200 OK response code and the following JSON object in response body:

Parameter	Description
Listeners array of objectRequired	A list of your active listeners.
Id integerRequired	ID of the listener.
BaseUrl stringRequired	Base URL of the Listener.
EventType array of stringRequired	Event types for this listener.
ScheduleIds array of integerOptional	Array of subscribed schedule IDs.

DELETE /listener

This method allows to unsubscribe from an active listener.

Request

The service expects the following parameters as part of the JSON body:

Parameter	Description
ListenerId integerOptional	ID of the listener to unsubscribe.
BaseUrl stringOptional	Listener BaseUrl to unsubscribe (if set, it may unsubscribe more than one listener).

The signature is calculated as a SHA-2 256 checksum using string source from the following concatenated parameters:

DateTime (HTTP header)
X-Liquid-Nonce
Your secret API Key

Successful Response

A successful call will return a HTTP 200 OK response code and the following JSON object in response body:

Parameter	Description
Unsubscribed array of objectRequired	List that contains details of the listeners that were unsubscribed.
Id integerRequired	ID of the listener.
BaseUrl stringRequired	Base URL of the Listener.
EventType array of stringRequired	Event types for this listener.
ScheduleIds array of integerOptional	Array of subscribed schedule IDs.

POST /status-request

This method is used to request the status of content.

Note: The status of the content will be returned asynchronously to your listeners subscribed to "Status" event type through the listener's callback services (see POST /status).

Request

The service expects the following parameters as part of the JSON body:

Parameter	Description
Type stringRequired	Content type. Possible values are: Coupon Survey Game
Id integerOptional	ID of the content of above type you want the status for.
Code stringOptional	For content type "Coupon" we can search by code code instead of the ID.

The signature is calculated as a SHA-2 256 checksum using string source from the following concatenated parameters:

DateTime (HTTP header)
X-Liquid-Nonce
Type
Your secret API Key

Successful Response

Provided the call is well formed, the reply will always be HTTP 200 OK.

Callback services

The following sevices must be implemented for your listener BaseUrl. For events that you are registered to receive LB will send the response in this format to your provided URL.

We will attempt three re-tries to a listener before we will discard the message.

General principles

All requests in this section:

Are sent from LB to you. They they are web-hooks, requests we send to you as certain things happens in our platform.
Will have the following headers set:

Header	Description
Header	Description
X-Liquid-Timestamp	When we generated the request.
X-Liquid-Nonce	A unique random value.
X-Liquid-Signature	The SHA-2 256 signature of the above nonce + the API Key registered with the listener.

POST /status

This returns the state of the content ID (or code) that was passed to Liquid Barcodes in POST /status-request. This happens asynchronously.

Note that if Type/Id was not found, we will still send this request - with the Owner/Status fields left out.

Request

The service will send the following parameters as part of the JSON body:

Parameter	Description
Type stringRequired	The type for the content. Possible values are: Coupon Survey Game
Id integerOptional	The ID of the content of the above type.
Code stringOptional	Coupon code. It only applies for content type "Coupon".
Owner stringOptional	The owner of the content. If the Type/Id was not found, this field will not be set.
Status objectOptional	The following sub-fields may be set to indicate current status of the content. If the Type/Id was not found, this field will not be set.
Depleted booleanRequired	It will be true when it's no longer possible to use content, and false if usage is still possible.
Uses integerOptional	Number of uses.
MaxUses integerOptional	Maximum allowed uses. It only applies for content type "Coupon".
LastUse stringOptional	ISO-8601 formatter Timestamp of last usage. Not set if not yet used. It only applies for content type "Coupon".
Expired booleanRequired	It will be true when content expiration date has passed, and false if not yet.

Successful Response

A 200-OK response means that you confirm that you have received the request.

Error response

If any other code status is received, LB will retry the same request later (max 3 retries).

POST /usage

The system will provide an event every time some content is used (Validated, redeemed, answered, played etc). You can only subscribe to events that are coming from the content you have access to.

Request

The service will send the following parameters as part of the JSON body:

Parameter	Description
Type stringRequired	The type for the content. Possible values are: Coupon Survey Game
Id integerOptional	The ID of the content of the above type.
Code stringOptional	Coupon code. It only applies for content type "Coupon".
Owner stringRequired	The owner of the content.
Status objectRequired	The following sub-fields may be set to indicate current status of the content.
Timestamp stringRequired	ISO-8601 formatter Timestamp of the event
Store integerOptional	LB internal Store ID (when available). It only applies for content type "Coupon".
StoreRefId integerOptional	Numeric POS store reference (when available). It only applies for content type "Coupon".
Uses integerRequired	Number of uses.
RemainingUses integerOptional	Number of uses still left. When 0 no more uses can occur. It only applies for content type "Coupon".
GiftCardBalance numberOptional	Balance of the giftcard (points card). It only applies for content type "Coupon".
Depleted booleanRequired	It will be true when it's no longer possible to use content, and false if usage is still possible.

Successful Response

A 200-OK response means that you confirm that you have received the request.

Error response

If any other code status is received, LB will retry the same request later (max 3 retries).

POST /reward

This service allows Liquid Barcodes to trigger issue of a reward in a third party system.

Request

The service will send the following parameters as part of the JSON body:

Parameter	Description
Id stringRequired	LB transaction ID for this reward.
UserRef stringRequired	A unique and persistent ID that identifies the rewarded User.
Reward stringRequired	A customer specified Reward. This is text that you can set up in the LB campaign. It could for example identify which reward to issue in your system.

Successful Response

A 200-OK response means that you confirm that you have received the request.

Error response

If any other code status is received, LB will retry the same request later (max 3 retries).

POST /report

The system will provide an event every time a report generating process is finished.

Request

The service will send the following parameters as part of the JSON body:

Parameter	Description
ReportName stringRequired	The name of the report as ordered.
ReportPeriod stringRequired	The period for the report. Currently the following options are supported: Day Week Month
Date stringRequired	The startdate for the report.
ReportLink stringRequired	Link to the requested report.

Successful Response

A 200-OK response means that you confirm that you have received the request.

Error response

If any other code status is received, LB will retry the same request later (max 3 retries).

Liquid Barcodes Application Feed Interface JSON/REST

Introduction

General principles

Background

Nomenclature

Preferred API format and HTTP Headers

Signature

Example (pseudo) service call:

General Disclaimer

Register user – Liquid Barcodes user creation & consent handling

Consent update

Register user - external user creation & consent handling

Manage and edit user

User rights

Customer user groups

Select preferred store(s)

User models

The User model

The Consent model

The Consent situation model

User methods

POST /initialize

POST /pin

POST /user

GET /user

PUT /user

DELETE /user

GET /languages

Points program

GET /points-program/{UserId}/log/points

GET /points-program/{UserId}/history/points

GET /points-program/{UserId}/history/store-activity

GET /points-program/{UserId}/tier-status

GET /points-program/{UserId}/history/issues

POST /points-program/points/share

Content management

Sections

Coupon content

Activate content

HTML content

Content model

GET /content

PUT /content/togglestate

GET /preview

Share content

POST /share

Share stamps

POST /content/coupons/{ContentId}/stamps/share

Likes

PUT /content/{ContentId}/like

Tags

Content tag model

GET /content-tags

PUT /content-tags/{TagId}/like

Rating

GET /ratings/categories

POST /rating

GET /ratings/statistics

GET /ratings/statistics/store

Stores management

GET /stores

GET /storetagids

GET /store/{storeId}/status

GET /stores/machines/status

Recruit-a-friend

GET /validreferral

POST /referral

Push notification support

POST /device

Receipts handling

Receipt Model

Receipt

GET /receipts

POST /receipts/forward

PUT /receipts/{ReceiptId}

Shop

Shop offer model

Register payment method

GET /payment/configuration

GET /shopoffers