52API VOUCHER
This topic is primarily for administrators and other people who manage a Fiftytwo solution
This topic is about an API for on-premise use. To learn about Fiftytwo cloud-based APIs, go to https://api.fiftytwo.com/ .
52API VOUCHER, commonly known as Voucher API, is a REST-based web API. It's typically used with retail systems like 52ViKING to ensure ability to use vouchers across physical stores, web, and other channels as well as to batch-issue unique vouchers (for example for e-mail marketing).
It provides features such as:
-
Ability to use vouchers across physical stores, web, and other channels
-
Reservation
-
Redemption
-
Viewing of individual voucher values
-
Issuing of unique vouchers
-
Can be used in conjunction with Order API and Basket API
Voucher API is part of the 52MASTERPRICER suite of APIs.
In general, 52ViKING operates with two types of vouchers (also referred to as coupons in the API and in 52ViKING):
-
Generic vouchers, which can be used several times and distributed in various ways to a large amount of people. Generic vouchers trigger a certain discount, and the vouchers themselves carry no value.
-
Unique vouchers, which have a value attached and can only be used once. The value can be either a fixed discount amount or a percentage. For example, a comeback voucher giving 5 euros off the next purchase above a certain amount.
Both voucher types can be printed as barcodes. It's also possible to map the barcodes to a more user-friendly short code for entering the voucher on a webshop.
In order to use a 52ViKING voucher from a webshop, a connection needs to be established between the web application and the 52ViKING voucher server. This connection runs via the 52ViKING omnichannel controller (OC).
The API methods exposed in this API are general web methods as well as unique voucher methods that are only relevant for unique vouchers because generic vouchers can be used multiple times and don't contain a value.
Voucher API uses these HTTP status codes as return codes:
-
200 OK
XML tag status that shows if request has gone well or not.
Can have the values OK or NOK.
-
400 Bad Request
Returned if request is wrong or if request is missing information.
-
401 Unauthorized
52ViKING-KEY missing or incorrect.
-
404 Not Found
Resource not available.
-
500 Internal Server Error
Unknown error or configuration on the server.
-
UTF-8
When the API itself refers to coupons in the following, it means vouchers.
To make it easy to enter vouchers on web stores, 52ViKING provides a mapping table that shortens the amount of characters to type.
Example: Instead of having to enter the unique voucher number 9891001123400000001794, the customer can enter a short name, like PFMQWZ.
The mapping table is also used for validating if a voucher is correctly entered by the user. Note, however, that even if a voucher has been entered correctly, it may not necessarily trigger a discount if selling conditions aren't met.
Use to check if a voucher is valid and optionally its value if it’s a unique voucher.
URI |
/Coupon/{CouponNumber|CouponName} |
|||
Method |
GET |
|||
Example |
/Coupon/9891001123400000001794 /Coupon/JUL2018 |
|||
Reply body |
Tag elements |
|||
Name |
Description |
Format |
Occurrences |
|
CouponStatus |
Root tag |
|
1 |
|
Coupon |
Voucher number |
10-22 digits |
1 |
|
CouponName |
Mapping voucher name. Name will only be returned if it exists. |
string |
0-1 |
|
Value |
The value of the voucher (amount/percentage) Only returned for unique coupons. |
1-8-digit number with 2 decimals |
0-1 |
|
Type |
Generic/unique |
string |
1 |
|
DiscountCouponId |
Discount group ID for Basket API |
3 digits |
1 |
|
Returns |
200 OK & XML reply |
XML reply example:
<?xml version='1.0' encoding='UTF-8'?>
<Coupon>
<Coupon>1001123400000001794</Coupon>
<CouponName>JUL2018</CouponName>
<Value>25</Value>
<Type>unique</Type>
<DiscountCouponId>123</DiscountCouponId>
</Coupon>
The function may return 400 if CouponName doesn't comply with the allowed format. The format is configurable, defaulting to between 6 and 20 characters containing capital letters and digits.
If the voucher is unique, a value is returned, otherwise it’s a generic voucher. For unique vouchers that are reserved or completed, the value field will be empty.
CouponNumber can be passed with or without the 989 prefix. The returned Coupon element is always without the 989 prefix.
Use to create a link in the mapping table between a voucher barcode and an easy-to-enter short name.
URI |
/Coupon/{CouponNumber}/link/{CouponName} |
Method |
PUT |
Example |
/Coupon/9891001123400000001794/link/PMQZXJ
|
Returns |
200 OK |
The voucher ID can either be a unique or a generic voucher.
Use to check if a voucher is valid, and to check its value.
URI |
/CouponValue? |
Method |
GET |
Querystring |
Coupon= Voucher number Store= Store ID (optional) |
Example |
/CouponValue?Coupon= 9891001123400000001794 |
Returns |
200 OK & XML reply |
XML reply example:
<?xml version='1.0' encoding='ISO-8859-1'?>
<CouponValue>
<status>OK</status>
<Coupon>1001123400000001794</Coupon>
<Value>25</Value>
</CouponValue>
Unique vouchers are accepted both for 22 digits and 19 digits. When using 22 digits, the prefix must be 989. The returned voucher ID is only 19 digits.
The voucher isn't reserved, as that will be handled by the following call.
If the voucher isn't valid, the status NOK is returned.
To check if a voucher is valid and create a reservation:
URI |
/CouponRedeem? |
Method |
GET |
Querystring |
Coupon= Voucher number Store= Store ID |
Example |
/CouponRedeem?Coupon= 9891001123400000001794 |
Returns |
200 OK & XML reply |
XML reply example:
<?xml version='1.0' encoding='ISO-8859-1'?>
<CouponRedeem>
<status>OK</status>
<Coupon>1001123400000001794</Coupon>
<Value>25</Value>
</CouponRedeem>
CouponRedeem reserves the voucher, so it can't be used again (only valid for unique vouchers). This is relevant when a webshop has added the voucher to the basket, but not completed the transaction yet.
To cancel voucher reservation:
URI |
/CouponCancel? |
Method |
GET |
Querystring |
Coupon= Voucher number Store= Store ID |
Example |
/CouponCancel?Coupon= 9891001123400000001794 |
Returns |
200 OK & XML reply |
XML reply example:
<?xml version='1.0' encoding='ISO-8859-1'?>
<CouponCancel>
<status>OK</status>
<Coupon>1001123400000001794</Coupon>
</CouponCancel>
CouponCancel will remove the reservation of a voucher so it can be used again.
To capture a voucher for use (can be reserved):
URI |
/CouponComplete? |
Method |
GET |
Querystring |
Coupon= Voucher number Store= Store ID Amount = The amount the voucher gives in discount |
Example |
/CouponComplete?Coupon= 9891001123400000001794 |
Returns |
200 OK & XML reply |
XML reply example:
<?xml version='1.0' encoding='ISO-8859-1'?>
<CouponComplete>
<status>OK</status>
<Coupon>1001123400000001794</Coupon>
</CouponComplete>
CouponComplete should be used then the voucher is marked as used, that is when the order is shipped of completed.
Use to create a number of vouchers and a link in the mapping table.
URI |
/CouponsCreate |
|||
Method |
POST |
|||
Example |
/CouponsCreate |
|||
Request body |
Name |
Description |
Format |
Occurrences |
Tag-elements |
||||
CreateCoupons |
Roottag |
|
1 |
|
CouponId |
CouponId as created in 52ViKING |
3 digits |
1 |
|
NamePrefix |
The prefix of the mapping name. A mapping will only be created if NamePrefix is provided. |
string |
0-1 |
|
Value |
The value of the voucher (amount/percentage)
|
1-8-digit number with 2 decimals |
1 |
|
Start |
Start date of the voucher |
YYYY-MM-DDThh:mm:ssTZD
|
1 |
|
End |
End date of the voucher |
YYYY-MM-DDThh:mm:ssTZD
|
1 |
|
Quantity |
Number of vouchers to be created |
1..5000 |
1 |
|
Returns |
200 OK & XML reply |
|||
Reply body |
Name |
Description |
Format |
Occurrences |
Tag-elements |
||||
Coupons |
Root tag |
|
1 |
|
Coupon |
Element for Coupons |
|
|
|
Barcode |
The full barcode of the voucher |
22 digits |
1 |
|
Name |
The mapping name of the voucher NamePrefix+6-digit random number Only present if NamePrefix was provided in the request |
string |
0-1 |
Use to generate unique vouchers that may, for example, be used in conjunction with e-mail campaigns.
URI |
/IssueCoupons? |
Method |
GET |
Querystring |
Type= Discount voucher n type (3 digits) used to link with discount group Qty= Number of vouchers to be issued Value= Amount or percentage depending on discount group Start= Valid from YYMMDD End= Valid until (including) YYMMDD. Must be larger or equal to Start. |
Accept |
text/xml application/json text/csv |
Example |
/IssueCoupons?Type=1&Qty=2&Value=10&Start=161001&End=161031 |
Returns |
200 OK & XML reply |
XML reply example:
<?xml version='1.0' encoding='ISO-8859-1'?>
<IssueCoupons>
<Coupon>
<CouponId value='627'/>
<Start value='161005'/>
<Slut value='161010'/>
<Value value='15'/>
<CV2 value='921'/>
<Barcode value='9891001000100000627921'/>
</Coupon>
<Coupon>
<CouponId value='628'/>
<Start value='161005'/>
<Slut value='161010'/>
<Value value='15'/>
<CV2 value='525'/>
<Barcode value='9891001000100000628525'/>
</Coupon>
</IssuedCoupons>
Up to 5000 discount vouchers can be issued per request. Upon a completed successful request, the vouchers are created in the database and are ready for use (subject to start and end dates).
All fields are mandatory, otherwise HTTP status 400 is returned. 400 is also returned for invalid parameters.
Example of JSON output:
{
"IssuedCoupons": {
"Coupon": [
{
"CouponId": 629,
"Start": 161005,
"Slut": 161010,
"Value": 15,
"CV2": 408,
"Barcode": "9891001000100000629408"
},
{
"CouponId": 630,
"Start": 161005,
"Slut": 161010,
"Value": 15,
"CV2": 528,
"Barcode": "9891001000100000630528"
}
]
}
}
Example of CSV output:
Coupon,611,161005,161010,15,448,"9891001000100000611448"
Coupon,612,161005,161010,15,231,"9891001000100000612231"
The Voucher API functions listed in the previous, except CreateCoupons, can return:
-
OK – when successful
-
NOK – when not successful, with the following supplementary error code text:
-
Unknown number
-
Already used
-
Coupon not active
-
Coupon expired
-
Unknown coupon
-
52ViKING uses two types of vouchers.
Type 0 - Generic voucher: These are typically used in advertising materials or handed out as part of marketing campaigns.
Type 1 - Unique voucher: These are typically created as comeback vouchers, and each one has a unique voucher number and a value.
Generic voucher barcode structure
-
2-digit flag code (=98: voucher)
-
1-digit marking for discount voucher (=9: 52ViKING discount voucher)
-
1-digit discount voucher type (0=generic)
-
5-digit (always 0)
-
3-digit discount voucher ID
-
1 check digit
In total 13 digits.
Unique voucher barcode structure
-
2-digit flag code (=98: voucher)
-
1-digit marking for discount voucher (=9: 52ViKING discount voucher)
-
1-digit discount voucher type (1=unique)
-
3-digit discount voucher ID
-
4-digit shop ID
-
8-digit discount voucher number
-
3-digit security code
In total 22 digits.
Version |
Date |
Change |
Author |
---|---|---|---|
1.10 |
2021-04-06 |
Transfer to Fiftytwo help & knowledge center. Applied layout changes, added introduction text, introduced copyable examples in online versions, performed minor language optimizations, and changed revision history sorting to display most recent changes at top of table. |
MOM |
1.09 |
2020-01-22 |
Shortname clarification in link |
BER |
1.08 |
2020-01-06 |
Layout |
MIE |
1.07 |
2018-02-09 |
Added Coupon clarification description |
PEH |
1.06 |
2018-01-05 |
Added information on barcode structure |
BER |
1.05 |
2017-05-19 |
Layout and translation |
PHJ |
1.04 |
2017-05-09 |
Split Voucher and Giftcard in 2 API descriptions |
PEH |
1.03 |
2016-01-11 |
GiftVoucherAvailable |
APE |
1.02 |
2014-10-21 |
52RETAIL-Key -> 52RETAIL-KEY (as in code) |
BER |
1.01 |
2014-09-08 |
New resources – DiscountVoucherValue |
APE |
1.00 |
|
Creation of document |
APE |
© 2024 Fiftytwo A/S • Disclaimer
Last update: 29 November, 2024 13:22:48 CET
Share this page with your colleagues: