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.

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):

 

  1. Execute POST /initialize

    2. 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. 

     

  2. Execute POST /pin

    3. 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)

     

  3. Execute POST /user

    4. 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).

     

     

  4. If still missing user information, execute PUT /user

    5. 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.

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:

  1. Register user and consent in your system and create a unique and persistent UserID
  2. 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.
  3. 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.
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.
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).

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.

 

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

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.

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.

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:

 

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).

 

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. Normally this is the phone number of the friend (MSN).
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. Normally this is the phone number of the friend (MSN).

 

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.

 

Tags

 

Makes it possible for users to prefer particular types of content. We support Category tags and Brand tags.

Content tag model

The content tag object is used in a several places and has next fields:

 

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

GET /content-tags

Returns the list of available Tags in the app. Can be used for filtering.

 

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 tags 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 an array of the following JSON object in response body:

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

 

PUT /content-tags/{TagId}/like

Allow set/remove like/dislike for Tag. Note: Method only works for Tags with flag Likable set to true.

 

Request

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

Parameter Description
TagId
integerRequired 		Id of the target Tag.

 

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 content tag will be liked/disliked for.
Like
booleanOptional 		New 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
  • TagId
  • Your secret API Key

 

Successful Response

A successful call will return a HTTP 200 response code.

 

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.

 

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.

 

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.

 

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.
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):

  1. 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.
  2. 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.
  3. When checkout of the basket is selected, the app sends a request to the shop back-end using the ProcessShopBasket call.
  4. 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
  5. 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.
  6. 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
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).
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)
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 )

  1. 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.
  2. The consumer selects which offer he wants by putting them into a basket.
  3. When checkout of the basket is selected, the app sends a request to the App provider's back-end for execution of the order.
  4. 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.
  5. 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.
  6. The App provider's back-end should commit the final transaction value to the payment provider.
  7. 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:

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

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

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

 

Offer token payload model:

 

Parameter
Description
Expiration Date and time this offer token expired. Make sure to reject expired offer tokens.
Item Information about the item the user selected:

Parameter
Description
ShopOfferId The unique ID for this particular offer.
PaymentProviderId Used by Liquid Barcodes to identify which payment provider is requsting us (see above).
RetailPrice The price to the consumer.
Currency Will always be the currency of the app's country (one app, one country).
Description A textual description of the shop offer.
Type Reserved for future use, will presently always be 'Shop'.
InternalOfferToken Must be forwarded to LIQUID when payment was successful in the /transactions/reserved service (see above).

 

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

Parameter
Description
PaymentProviderId The payment provider ID received in the offertoken from the app.
PaymentRef A reference to the completed transaction in the payment providers system. Will be used when contacting the payment provider for support issues.
InternalOfferTokens 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 SHA-2 256 signature is calculated from X-Liquid-Date header + PaymentProviderId + all InternalOfferTokens (concatenated, separated by nothing) + Your secret API Key

 

The service replies with a status per InternalOfferToken.

 

RESPONSE

 

Parameter
Description
LogReferenceId 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 the following object:

Parameter
Description
InternalOfferToken Token to identify payment.
ContentID Optional: 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 OK for success. Error code when not successful.
StatusMessage Optional: Blank when successful. Error details when not successful.
RejectCode Optional. 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 Optional. A human readable cause of rejection message in case a rejection occurred. Only set when RejectCode is set.

 

List of errors:

HttpStatusCode.BadRequest, "InternalOfferToken expired";
HttpStatusCode.BadRequest, "Shop offer is inactive";
HttpStatusCode.Forbidden, "Duplicate call";
HttpStatusCode.Forbidden, "Maximum amount exceeded";
HttpStatusCode.Gone, "Campaign is out of codes";
HttpStatusCode.InternalServerError, "Error on coupon issue"; - other generic error on coupon issue
HttpStatusCode.InternalServerError, "InternalServerError"; - unknown generic error

 

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 - when report can't be found
  • Unknown - Server error
RejectMessage
stringOptional 		A human readable message for the cause of rejection.

 

POST /orders/received/{storeref}

 

Set ReceivedByPOS date in the list of orders for this store

Parameter
Description
StoreRef The unique store ID
OrderIds Array of orders ids received by POS

 

Checksum calculated from: X-Liquid-Date header + StoreRef + Your secret API Key

A successful call to this function will return the following:

 

 

Parameter
Description
OrdersProcessedCount Number of orders processed

 

If the service fails it will reply with a non-HTTP-200 response or a response where RejectCode is set:

 

 

Parameter Description
RejectCode Optional. 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 Optional. A human readable message for the cause of rejection.

Upload product codes

 

Will upload product codes list.

POST  /product-codes/upload

 

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

 

REQUEST

Parameter
Description
ProductCodes Array of products, see Product model below.

 

 

Product model specification

Parameter
Description
ProductCode Unique identifier for the product
Description Product description
Level1Id Optional. Unique Id of the level 1 of the product hierarchy to which the above product belongs
Level1Name Optional. Description of level 1
Level2Id Optional. Unique Id of the level 2 of the product hierarchy to which the above product belongs
Level2Name Optional. Description of level 2
Level3Id Optional. Unique Id of the level 3 of the product hierarchy to which the above product belongs
Level3Name Optional. Description of level 3

Checksum calculated from: X-Liquid-TimeStamp header + Your secret API Key

 

RESPONSE

A successful call to this function will return the following:

Parameter
Description
 
UploadedRowsCount
Number of rows uploaded

 

If the service fails it will reply with a non-HTTP-200 response or a response where RejectCode is set:

Parameter Description
RejectCode Optional. A code that can be used to programatically recognize the cause of a rejection.

The following values can occur:

  • Unknown - Server error
RejectMessage Optional. 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

 

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

 

Will fetch all the active and planned campaigns

This api call doesn't need any input parameter. It will take the necessary parameter from the authentication headers

A successful call to this function will return a list of the following object

Campaigns list model specification:

 

Parameter
Description
Country Customer's country
SectionId Section ID
CategoryId Shop offer category
CampaignName Campaign Name
CampaignId CampaignId
CampaignStartDate Campaign Start Date
CampaignStopDate Campaign Stop Date
ScheduleName Schedule name
ScheduleId Schedule Id
ScheduleStartDate Schedule Start Date
ScheduleStopDate Schedule Stop Date
CouponImageUrl Coupon image url
ThumbImageUrl Thumb image url
BackImageUrl Back image url
Description Description cultured
ContentType Coupon, Survey, Game, ShopOffer
MediaType AppGeneric, Email, Sms, Paper, PushNotification, etc.
Tags Array of tags:

  • Id
  • Type
  • CustomerId
  • ListId
  • NameCultureData
  • ImageCultureUrls
  • Likable
  • NoHate
  • Dislikable
  • Active
AdditionalInfo1 Additional info 1
AdditionalInfo2 Additional info 2
AdditionalInfo3 Additional info 3
CodesData Only applicable for 'Import codes' campaign. Contains data about imported codes set:

  • TotalCodes
  • UsedCodes
  • RemainingCodes
  • EarliestCodeExpiryDate (can be in the past if there is unused expired code)
ParentScheduleId Schedule ID of parent (only populated if parent is ShopOffer)
FollowUpScheduleIds Array of child schedule IDs (only populated for single purchase ShopOffers)
FollowUps Array of nested campaign models (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
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
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
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).