Coupon Api Implementation Manual
Table of contents
- 1. Change Log
- 2. Authentication
- 3. User/Account Identification
- 3.1 Card Identification
- 3.2 User Search
- 3.3 Getting Account Details
- 3.4 Getting Basic Account Information
- 3.5 Getting Membership Details
- 3.6 Getting User Details
- 4. Couponing
This manual describes how to implement an interface for couponing with Convercus. With this documentation, it should be more intuitive and straight-forward to map all relevant information and processes to calls of the Convercus Api.
Technical information about the Convercus Api can be found at the following sites
-
https://staging.convercus.io/api-docs/swagger-ui.html (Staging Environment)
-
https://api.convercus.io/api-docs/swagger-ui.html (Production Environment)
and on the Developer Page
Change Log
|
Version |
Change Date |
Change Log |
|---|---|---|
|
v1.1.1 |
2021-09-14 |
|
|
v1.1.0 |
2020-11-24 |
|
|
v1.0.0 |
2020-06-10 |
|
Authentication
Every request requires a JWT-Token for authentication. The token can be obtained with the following request:
curl --location --request POST '{{api_url}}/auth/login' \
--header 'Content-Type: application/json' \
--data-raw '{
"org": "{{org}}",
"userName": "{{userName}}",
"password": "{{password}}"
}'
where the following variables have been used:
|
Variable |
Description |
|---|---|
|
|
Endpoint of the api.
|
|
|
Organization code for correct mapping. This value will be given by Convercus. |
|
|
User-Name of the api-user. This value will be given by Convercus. |
|
|
User-Password of the api-user. This value will be given by Convercus. |
The JWT-Token can be found in the body of the response.
Note, that the token expires after 24 hours. To have a valid token at all times, it is necessary to generate the token on a regular basis.
User / Account Identification
For all loyalty-related processes it is important to identify the person the system is interacting with. The central object for this identification is the account you can collect points on. This account can be linked to user-data, transactions, bookings, etc. Every account has an unique identifier, the account_id (e.g. 7d123457-bfa1-4a83-8213-123456789763), which is the technical ID all those connections are made with.
Additionally, every account can have multiple identifiers (i.e. card-codes, external identification-codes, etc.), which allow to make a connection to an account without the need to extract the account-id. We will explore both identifier-related api-calls and account-id-related api-calls in this chapter. The handling in later chapters in anlogue.
Card identification
All connections of transactions, bookings, account-coupons, etc. to accounts can be performed using the account_id (or alternatively the identifier codes). Thus, there has to be a mechanism to identify the account you want to connect to.
This is usually done, by scanning / typing / etc. the predefined identifier code (card number) of the customer. This card code can then be used in the api analogously to the account-id (see in the respective chapters for examples).
Note, that for this process, it is not necessary to get any user-information. It is possible to perform the whole purchase and payment process without requesting additional user-information (like name, birthdate, optins, etc.) as only the account-identification (account_id or identifier-code) is important for the relevant api processes. If there is no need to view user-data on the cash register, you can simplify and speed up the whole process by skipping it altogether.
User Search
If a registered customer forgot to bring his card, there is the option to search for him via search api. This api is performing an elastic search over various domain objects (including accounts) and responds an array with results. You can perform an elastic search in the following way
curl --location --request POST '{{api_url}}/search' \
--header 'Authorization: {{jwt_token}}' \
--header 'interaction-id: {{interactionId}}' \
--header 'Content-Type: application/json' \
--data-raw '{{body}}'
with variables
|
Variable |
Description |
|---|---|
|
|
Endpoint of the api.
|
|
|
JWT-token, which has been generated by authentication. |
|
|
Unique Identifier of the cash machine (or virtual equivalent, e.g. online-shop), which produced the receipt. This ID has to be listed in the Convercus System as with this ID, the connection bon-to-store is made. |
|
|
Body with search parameters, specified in the following. |
The body with search parameters looks like this:
{
"searchTerm": "Example",
"type": "ACCOUNT"
}
with
|
Attribute |
Description |
Relevance |
|---|---|---|
|
|
Text to be matched with indexed search fields. Multiple values can be separated by spaces (e.g. The following fields are indexed
|
Mandatory |
|
|
Domain filtering. |
Optional Filtering to |
In general, this api may search over various domains, giving results like this
{
"searchTerm": "Example",
"nrOfResults": 3,
"results": {
"COUPON": [
{
"preview": "Title: Title of Coupon,Type: REWARD",
"refId": "a1e52b7a-5cd4-4580-a0f7-7f602b27ba6e",
"type": "COUPON"
},
{
"preview": "Title: Title of Coupon,Type: DISCOUNT",
"refId": "abad53e5-bd86-48df-858c-1bcce3af41fb",
"type": "COUPON"
}
],
"ACCOUNT": [
{
"preview": "name: Name of Person,email: E-Mail of Person",
"refId": "2f081e91-1346-4ef6-82b2-fcdecd3c190b",
"type": "ACCOUNT"
}
]
}
}
Important Note about Filtering to Domains:
Usually, the ACCOUNT domain search is the weapon of choice here (as we are normally not interested in information about backend settings here). Applying the filtering on ACCOUNT responds the following result (same setup as before, but filtered):
{
"searchTerm": "Example",
"nrOfResults": 1,
"results": {
"ACCOUNT": [
{
"preview": "name: Name of Person,email: E-Mail of Person",
"refId": "2f081e91-1346-4ef6-82b2-fcdecd3c190b",
"type": "ACCOUNT"
}
]
}
}
After identifying the user, the refId of the correct ACCOUNT-result can be used as accountId for all further processes.
Getting Account Details
If you are interested in more detail about the person standing at the POS, you can use an identifier code or accountid to get more information about the account like its bookings, transactions, current balance, membership information or user-data. All those options are explained in Swagger Documentation (spec: account). We will focus here on personal user-data.
Note, that due to structure of the platform, there are essentially three objects which contain information about the user, his account and membership.
-
account:
-
This is the central element of the loyalty system.
-
Every account has its unique
accountId. All relevant loyalty-processes can be linked to this id. -
N identifiers of different
id-typemay serve as additional external identifiers for an account. Usually, these identifiers are Cardcodes or external numbers (like a online-shop-id). -
Accounts can be anonymous, if they don’t have user-information connected (see membership).
-
-
user:
-
This is the object which contains personal user-data like name, address, etc.
-
User data may be created independently from an account. Without the connection to an account (see membership) however, there is no way to interact with this data in a loyalty context (e.g. you cannot earn points on a user, but an account.
-
-
membership:
-
This object connects an account to a user object.
-
The creation of a membership is typically the result of a completed registration.
-
Optins for the program are related to this object.
-
Depending on the set of information you are interested in, you may need to get all of them. We will explain a straight-forward way to do this in the following.
Getting basic Account Information
As stated out before, the account is the center of the whole loyalty system. The accountId can be used as common connection id for practically all loyalty connections.
You can get the basic account information with the following request:
curl --location --request GET '{{api_url}}/accounts/{{accountId}}' \
--header 'Authorization: {{jwt_token}}' \
--header 'interaction-id: {{interactionId}}' \
--header 'Content-Type: application/json' \
--header 'id-type: {{idType}}' \
with variables
|
Variable |
Description |
|---|---|
|
|
Endpoint of the api.
|
|
|
ID of the account that will receive the transaction. The ID has to be given in the format, that is dictated by the |
|
|
The JWT-token, which has been generated by authentication. |
|
|
Unique Identifier of the cash machine (or virtual equivalent, e.g. online-shop), which produced the receipt. This ID has to be listed in the Convercus System as with this ID, the connection bon-to-store is made. |
|
|
Identifier-Type (corresponding to the Available values:
|
Note, that it’s possible to get the account-object using the identifier code (e.g. {{idType}}=CARDCODE, {{accountId}}=V1W2X3Y4Z5) or the accountId itself (e.g. {{idType}}=ID, {{accountId}}=7d123457-bfa1-4a83-8213-123456789763). Thus, the request may also be used to extract an accountId from a given Identifier.
The account-object per se is rather slender, only containing an id (accountId), a program reference and a status of the account.
{
"id": "550e8400-e29b-11d4-a716-446655440000",
"program": "Pgr-A",
"status": "ACTIVE"
}
If your program allows deactivation or locking of accounts, you should make sure, that accounts that don’t have the status ACTIVE cannot proceed with the following earn- and burn-processes. Deleted Accounts will not be responded at all.
Getting Membership Details
If you are interested in optins and / or user data of a given account, you need to check if the account has an active membership by requesting
curl --location --request GET '{{api_url}}/accounts/{{accountId}}/memberships' \
--header 'Authorization: {{jwt_token}}' \
--header 'interaction-id: {{interactionId}}' \
--header 'Content-Type: application/json' \
--header 'id-type: {{idType}}' \
with variables
|
Variable |
Description |
|---|---|
|
|
Endpoint of the api.
|
|
|
ID of the account that will receive the transaction. The ID has to be given in the format, that is dictated by the |
|
|
The JWT-token, which has been generated by authentication. |
|
|
Unique Identifier of the cash machine (or virtual equivalent, e.g. online-shop), which produced the receipt. This ID has to be listed in the Convercus System as with this ID, the connection bon-to-store is made. |
|
|
Identifier-Type (corresponding to the Available values:
|
Note again, that you can use the identifier code directly (e.g. {{idType}}=CARDCODE, {{accountId}}=V1W2X3Y4Z5) at this point.
The returned object looks like this:
[
{
"accountId": "550e8400-e29b-11d4-a716-446655440000",
"memberRole": "OWNER",
"membershipId": "550e8400-e29b-11d4-a716-446655440000",
"optins": [
{
"flag": true,
"type": "email"
}
],
"partnerId": "550e8400-e29b-11d4-a716-446655440000",
"userId": "550e8400-e29b-11d4-a716-446655440000"
}
]
where
|
Attribute |
Description |
|---|---|
|
|
Technical account-Id connected to this membership. |
|
|
Role of the membership. In general, it is possible to have multiple memberships, one account owner ( In the standard setup however, there is only one membership (with |
|
|
Technical ID of the membership. |
|
|
List of optins that this membership has. Optin names are denoted by |
|
|
Technical ID of the partner, the membership is belonging to. |
|
|
Technical ID of the user connected to an account via the membership. |
If no membership is returned, the returned array is empty []. Depending on the specific program setup, these users may not be allowed to earn and/or burn their points if there are not registered. This logic has to be adopted here if that’s the case.
Getting User Details
Given the userId of the membership, user data can be received by requesting:
curl --location --request GET '{{api_url}}/users/{{userId}}' \
--header 'Authorization: {{jwt_token}}' \
--header 'interaction-id: {{interactionId}}' \
--header 'Content-Type: application/json' \
with
|
Variable |
Description |
|---|---|
|
|
Endpoint of the api.
|
|
|
Technical User-ID of the user (usually given by the membership connection). |
|
|
The JWT-token, which has been generated by authentication. |
|
|
Unique Identifier of the cash machine (or virtual equivalent, e.g. online-shop), which produced the receipt. This ID has to be listed in the Convercus System as with this ID, the connection bon-to-store is made. |
An exemplary response looks like this
{
"birthDate": "1965-03-05",
"city": "München",
"countryCode": "DE",
"customProperties": [
{
"name": "string",
"value": "string"
}
],
"emailAddress": "member1@172.31.52.70",
"familyName": "Mustermann",
"genderCode": "MALE",
"givenName": "Max",
"phone": 654324563,
"streetHouseNo": "Bahnhofstraße 1",
"userId": "550e8400-e29b-11d4-a716-446655440000",
"zipCode": 80469
}
Note, that the content of this response may differ with the program. There may be multiple customProperties, which are completely program-specific. Furthermore, it is possible that in future versions, the response will be expanded by more fields, so you should make sure to be able to accept more output.
Couponing
A very common process in cash registers and online shops is the basic couponing. There are various options to get and redeem coupons that certain users have connected with their accounts.
Getting Coupon Information
Get all account-coupons
To view all coupons a customer has access to, the following request must be sent:
curl --location --request GET '{{api_url}}/v2/accounts/{{accountId}}/accountcoupons' \
--header 'interaction-id: {{interactionId}}' \
--header 'Authorization: {{jwt_token}}' \
--header 'id-type: {{idType}}' \
--header 'Content-Type: application/json' \
with
|
Variable |
Description |
|---|---|
|
|
Endpoint of the api.
|
|
|
ID of the account that will receive the transaction. The ID has to be given in the format, that is dictated by the |
|
|
The JWT-token, which has been generated by authentication. |
|
|
Unique Identifier of the cash machine (or virtual equivalent, e.g. online-shop), which produced the receipt. This ID has to be listed in the Convercus System as with this ID, the connection bon-to-store is made. |
|
|
Identifier-Type (corresponding to the Available values:
|
This will return an array of all coupons accessable for the given accountId, e.g.
[
{
"accountCouponId": "YmZlOGNjNzgtMDIxZC00NTI2LThjMGMtZjhhYzUwYzE3MmIxfGExNDVlMTJkLTk4NjItNDQxOC1hM2RkLWM3NjJjNzk3ZGY2Nw",
"accountId": "a145e12d-9862-4418-a3dd-c762c797df67",
"couponId": "bfe8cc78-021d-4526-8c0c-f8ac50c172b1",
"usageType": "REWARD",
"externalReference": "ExternalReferenceExample",
"externalCode": {
"value": "EXCODE",
"type": "TEXT"
},
"maxRedeemCount": 1,
"maxRedeemCountGlobal": 1,
"redeemCount": 0,
"redeemCountGlobal": 0,
"pointsOfRedemption": [
{
"unitType": "INTERACTIONPOINT",
"value": "app"
}
],
"validFrom": "2020-11-01T00:00:00",
"validTo": "2020-11-30T23:59:00",
"stateLevel": null,
"couponValue": 100,
"customProperties": [
{
"name": "CustomProperty1",
"value": "Example"
}
],
"images": [
{
"id": 552a1c66-45e8-442c-8fdc-29eb175f3a01,
"name": exampleimage.jpg,
"tags": [
"contentPicture"
],
"path": "https://image-repository.point4more.com/1605623285936-exampleimage.jpg"
}
],
"i18nFields": {
"de": {
"title": "Example Coupon",
"subTitle": "Example subtitle",
"description": "Example description",
"bookingText": "Example booking text"
}
},
"activation": {
"activatable": false,
"activated": null,
"lastActivationDate": null
}
}
]
with
|
Attribute |
Description |
|---|---|
|
|
Unique identification string generated from the |
|
|
Technical account-Id connected to this membership. |
|
|
Unique identifier for every coupon. |
|
|
Specifies the type of coupon.
|
|
|
Unique Reference of the coupon, that may be interpreted by the cash register to execute predefined actions. Note: This value has to be stored before redemption as it will not be part of the redemption response. |
|
|
Maximum number of times a coupon can be redeemed for the given |
|
|
Maximum number of times a coupon can be redeemed for all accounts. |
|
|
Number of times a coupon has been redeemed for given |
|
|
Number of times a coupon has been redeemed for all accounts. |
|
|
Partners and interaction points the coupon can be redeemed at. |
|
|
Starting date the coupon will be valid from. Note: If |
|
|
End date the coupon will be valid until. Note: If |
|
|
States the registered value of the coupon. For the different types of coupons that specifies:
|
|
|
Custom parameters with their respective values. |
|
|
Descriptive texts of the coupon, partitioned in all generated langueages with 4 subcategories, see below for more details. |
|
|
Detailed information about the coupon’s activation, partitioned in 3 subcategories, see below for more details. |
The detailed attributes of i18nFields are (one set per language (e.g. de):
|
Attribute |
Description |
|---|---|
|
|
Title of the coupon. |
|
|
Additional title of the coupon. |
|
|
A more expressive description of the coupon. |
|
|
Booking text of the coupon redemption. |
The attributes of activation can be described as:
|
Attribute |
Description |
|---|---|
|
|
Describes if a coupon can be manually activated, where Note: Activatable coupons are only redeemable if they have been activated. |
|
|
Indicates, if an activatable coupon is currently activated on given This parameter will be |
|
|
Indicates the last date the coupon was activated for given This parameter will be |
Get information for a specific account-coupon
By encoding the accountCouponId as QR-Code (or similar), the required account information can be retrieved without requesting all account coupons again. By inputting the Code at the cash register, either through scanning the code or manual input, the coupon can be used directly without further requests, since the accountCouponId is a unique ID for the combination between accountId and couponId.
Get AccountCoupon Details
By using the unique accountCouponId, the coupons properties can be observed in greater detail.
curl --location --request GET '{{api_url}}/v2/accountcoupons/{{accountCouponId}}' \
--header 'interaction-id: {{interactionId}}' \
--header 'Authorization: {{jwt_token}}' \
--header 'Content-Type: application/json' \
again with
|
Attribute |
Description |
|---|---|
|
|
Unique identification string generated from the |
|
|
The JWT-token, which has been generated by authentication. |
|
|
Unique Identifier of the cash machine (or virtual equivalent, e.g. online-shop), which produced the receipt. This ID has to be listed in the Convercus System as with this ID, the connection bon-to-store is made. |
This will return the coupon properties (equivalent to the array elements of the full account-coupon view) in detail:
{
"accountCouponId": "YmZlOGNjNzgtMDIxZC00NTI2LThjMGMtZjhhYzUwYzE3MmIxfGExNDVlMTJkLTk4NjItNDQxOC1hM2RkLWM3NjJjNzk3ZGY2Nw",
"accountId": "a145e12d-9862-4418-a3dd-c762c797df67",
"couponId": "bfe8cc78-021d-4526-8c0c-f8ac50c172b1",
"usageType": "REWARD",
"externalReference": "ExternalReferenceExample",
"externalCode": {
"value": "EXCODE",
"type": "TEXT"
},
"maxRedeemCount": 1,
"maxRedeemCountGlobal": 1,
"redeemCount": 0,
"redeemCountGlobal": 0,
"pointsOfRedemption": [
{
"unitType": "INTERACTIONPOINT",
"value": "app"
}
],
"validFrom": "2020-11-01T00:00:00",
"validTo": "2020-11-30T23:59:00",
"stateLevel": null,
"couponValue": 100,
"customProperties": [
{
"name": "CustomProperty1",
"value": "Example"
}
],
"images": [
{
"id": 552a1c66-45e8-442c-8fdc-29eb175f3a01,
"name": exampleimage.jpg,
"tags": [
"contentPicture"
],
"path": "https://image-repository.point4more.com/1605623285936-exampleimage.jpg"
}
],
"i18nFields": {
"de": {
"title": "Example Coupon",
"subTitle": "Example subtitle",
"description": "Example description",
"bookingText": "Example booking text"
}
},
"activation": {
"activatable": false,
"activated": null,
"lastActivationDate": null
}
}
with the same attributes as before:
|
Attribute |
Description |
|---|---|
|
|
Unique identification string generated from the |
|
|
Technical account-Id connected to this membership. |
|
|
Unique identifier for every coupon. |
|
|
Specifies the type of coupon.
|
|
|
Unique Reference of the coupon, that can be interpreted by the cash register to execute predefined actions. Note: This value has to be stored before redemption as it will not be part of the redemption response. |
|
|
Maximum number of times a coupon can be redeemed for the given |
|
|
Maximum number of times a coupon can be redeemed for all accounts. |
|
|
Number of times a coupon has been redeemed for given |
|
|
Number of times a coupon has been redeemed for all accounts. |
|
|
Partners and interaction points the coupon can be redeemed at. |
|
|
Starting date the coupon will be valid from. Note: If |
|
|
End date the coupon will be valid until. Note: If |
|
|
States the registered value of the coupon. For the different types of coupons that specifies:
|
|
|
Custom parameters with their registered values. |
|
|
Descriptive texts of the coupon, partitioned in all generated langueages with 4 subcategories, see below for more details. |
|
|
Detailed information about the coupon’s activation, partitioned in 3 subcategories, see below for more details. |
The detailed attributes of i18nFields are (one set per language (e.g. de):
|
Attribute |
Description |
|---|---|
|
|
Title of the coupon. |
|
|
Additional title of the coupon. |
|
|
A more expressive description of the coupon. |
|
|
Booking text of the coupon redemption. |
Similarly, the attributes of activation can be described as:
|
Attribute |
Description |
|---|---|
|
|
Describes if a coupon can be manually activated, where Note: Activatable coupons are only redeemable if they have been activated. |
|
|
Indicates, if an activatable coupon is currently activated on given This parameter will be |
|
|
Indicates the last date the coupon was activated for given This parameter will be |
Coupon Activation / Deactivation
With a unique accountCouponId, a specific coupon available for given account can be activated or deactivated manually. This only works for activatable coupons, marked by the property "activatable": true in the accountCouponId Details (see above).
curl --location --request PATCH '{{api_url}}/v2/accountcoupons/{{accountCouponId}}/activation' \
--header 'interaction-id: {{interactionId}}' \
--header 'Authorization: {{jwt_token}}' \
--header 'Content-Type: application/json' \
--header 'id-type: {{idType}}' \
--data-raw '{
"activated": true
}'
with
|
Variable |
Description |
|---|---|
|
|
Endpoint of the api.
|
|
|
ID of the account that will receive the transaction. The ID has to be given in the format, that is dictated by the |
|
|
The JWT-token, which has been generated by authentication. |
|
|
Unique Identifier of the cash machine (or virtual equivalent, e.g. online-shop), which produced the receipt. This ID has to be listed in the Convercus System as with this ID, the connection bon-to-store is made. |
|
|
Identifier-Type (corresponding to the Available values:
|
|
|
Unique identifier generated by combining a coupon-ID and a unique user-ID, to which the coupon is accessable to. |
|
|
This boolean requests the coupon to be activated ( |
This will return no body, but will activate or deactivate the coupon for given user. Activatable coupons have to be activated for them to be redeemable.
Note that this is not relevant if the coupon is permanently valid. Activatable coupons are automatically redeemed when redemption conditions are met.
Coupon Redemption
To redeem a coupon, the unique accountCouponId has to be sent using
curl --location --request PATCH '{{api_url}}/v2/accountcoupons/{{accountCouponId}}' \
--header 'interaction-id: {{interactionId}}' \
--header 'Authorization: {{jwt_token}}' \
--header 'Content-Type: application/json' \
with
|
Variable |
Description |
|---|---|
|
|
Endpoint of the api.
|
|
|
The JWT-token, which has been generated by authentication. |
|
|
Unique Identifier of the cash machine (or virtual equivalent, e.g. online-shop), which produced the receipt. This ID has to be listed in the Convercus System as with this ID, the connection bon-to-store is made. |
|
|
Unique identifier generated by combining a coupon-ID and a unique user-ID, to which the coupon is accessable to. |
In the current version of the interface, the response does not contain any body information, thus any information about the coupon (especially the externalReference ) has to be stored before the redemption (they cannot be reproduced).
After the coupon has been redeemed sucessfully, the respective action / pricing rule / ect. (for which the original externalReference may be needed) may be applied.
Note about Extra-Incentivation Coupons
The coupon categories EXTRAPOINT and MULTIPLIER will be triggered automatically by the transaction itself (if all conditions are fulfilled) and therefore cannot be redeemed manually. Keep in mind however, that if the coupons are activatable, they need to be activated by the customer first.
A manual redemption of coupons is only necessary / possible for manual coupon categories DISCOUNT and REWARD.
Coupon Redemption Preview
To preview the redemption of a coupon, the unique accountCouponId can be used with the preview request. This will generate the exact same output as an actual coupon redempton request, but does not finally redeem the coupon.
curl --location --request PATCH '{{api_url}}/v2/accountcoupons/{{accountCouponId}}/preview' \
--header 'interaction-id: {{interactionId}}' \
--header 'Authorization: {{jwt_token}}' \
--header 'Content-Type: application/json' \
with
|
Variable |
Description |
|---|---|
|
|
Endpoint of the api.
|
|
|
The JWT-token, which has been generated by authentication. |
|
|
Unique Identifier of the cash machine (or virtual equivalent, e.g. online-shop), which produced the receipt. This ID has to be listed in the Convercus System as with this ID, the connection bon-to-store is made. |
|
|
Unique identifier generated by combining a coupon-ID and a unique user-ID, to which the coupon is accessable to. |
In the current version of the interface, the coupon redemption response does not contain any body information, as the coupon redemption itself currently only contains a response code, based on the success of the operation.
Likewise, the preview will respond with the following codes:
|
Code |
Description |
|---|---|
|
202 |
Accepted This means, the coupon can be manually redeemed with the actual |
|
400 |
Bad Request Redeeming the coupon would cause an error and is therefore not possible. This could be, because the accountCouponID belongs to an |
|
401 |
Forbidden The authorization token is either invalid, or the user does not have sufficient permissions. |
Note about Extra-Incentivation Coupons
The Redemption Preview previews the Coupon Redemption function mentioned above. Therefore the same constraints apply, see Note about Extra-Incentivation Coupons above.