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 BASKET, commonly known as Basket API, is a REST interface over HTTP(S) that uses either XML or JSON as input and output format
It provides basket and receipt calculation optimized for web and scalability, and makes discounts, etc. work exactly like they do with a regular till.
Key characteristics of Basket API:
-
Exposed as a stateless REST interface
-
No persistence of basket or receipt
-
Possible to run multiple 52ViKING tills, which allows load balancing and scalability
-
Each 52ViKING till has a single import of articles and a single database, but multiple execution threads
-
Useful as a basis for automated test and verification of correct calculations
Basket API is used with retail systems like 52ViKING, and it's part of the 52MASTERPRICER suite of APIs.
HTTP return codes
Basket API uses these HTTP status codes as return codes:
-
200 OK
On GET request with a successful reply.
On POST request with a successful reply.
-
204 No Content
Default return code for POST request with no reply data.
-
400 Bad Request
Returned if request is wrong or if request is missing information.
-
404 Not Found
Returned if request fails, for example because of missing content.
-
50x Internal Server Error
Returned when a server-side error occurs, for example because of a missing instance or a wrong server-side configuration.
Supported encoding
-
UTF-8
CalculateBasket
CalculateBasket is called whenever a receipt is to be calculated. The logic used to calculate the basket is controlled by 52ViKING.
All discounts are applied to articles that are eligible for discount.
Receipts are line-orientated, so an article/line can hold one or more single articles. Articles can be sold either one-by-one or by using quantity. Regardless of which method is used, the lines (articles) are neither collapsed nor expanded.
Example: An article sold with a quantity of 1 followed by a quantity of 2 will be replied as an article with quantity=1 AND another article with quantity=2. In order to combine these articles, the request must hold the article with quantity=3. If a request for expansion is made, the request must hold the article three times (all with quantity=1).
The same applies to discounts: They're neither combined nor expanded, but always applied (calculated) with the number of articles for the current article in mind.
Amount is a regular number that always has 2 decimals.
CalculateBasket input is defined in basketinput.xsd (XML) and basketinput.json (JSON) respectively.
CalculateBasket output is defined in basketoutput.xsd (XML) and basketoutput.json (JSON) respectively.
The .xsd and .json files are provided separately.
When the API refers to coupons in the following, it means vouchers. See also Voucher API.
Content (input)
|
URI |
/CalculateBasket? |
|||
|
Method |
POST |
|||
|
Query string |
Store = Store that must do the calculation (optional) Chain = Chain that the store belongs to (optional) |
|||
|
Example |
/CalculateBasket?Store=3477&Chain=1 |
|||
|
Accept |
text/xml application/json |
|||
|
Content-Type |
text/xml application/xml application/json |
|||
|
Content body |
See tags elements and attributes in the following |
|||
|
Returns |
200 OK |
|||
|
Tag elements |
|||
|
Name |
Description |
Format |
Occurrences |
|
basket |
Root tag |
|
1 |
|
details |
Element for articles (lines) |
|
1 |
|
Item (under details) |
Element for an article (line) |
|
1-* |
|
customerregistered |
Element for customer reg. |
|
0-1 |
|
discountgroupstotrigger |
Element for discount groups with condition customerlist that should be triggered |
|
0-1 |
|
offeridstotrigger |
Element for discount groups with condition customerlist that should be triggered |
|
0-1 |
|
discounts |
Element for a list of discount groups and the articles that they should be triggered for. Used to overload article list of a discount (VK01) with condition customer list, that is triggered/added to discountgroupstotrigger. |
|
0-1 |
|
coupons |
Parent for one or more coupon (voucher) elements |
|
0-1 |
|
coupon |
Element for a coupon (voucher) |
|
1-* |
|
Attributes for discountgroupstotrigger |
|||
|
Name |
Description |
Format |
Occurrences |
|
discountgroup |
The ID of a discount group with condition customerlist that should be triggered |
10-digit number |
1-* |
|
Attributes for offeridstotrigger |
|||
|
Name |
Description |
Format |
Occurrences |
|
offerid |
Offer ID related to discount group with condition customerlist that should be triggered |
10-digit number |
1-* |
|
Attributes for discounts |
|||
|
Name |
Description |
Format |
Occurrences |
|
discountgroup |
A discount group that should be triggered |
|
0-* |
|
items |
Element for list of articles that should be included in the discount group |
|
1 |
|
item (under items) |
Article that should be included in the discount group |
|
0-* |
|
Attributes for basket |
|||
|
Name |
Description |
Format |
Occurrences |
|
disablediscounts |
1 indicates that no discounts will be calculated, except those given under the discounts node (only basic, basic basket, article group, and extended discounts guaranteed to be exempted). 0 or not given indicates normal discount calculation. |
1-digit number |
0-1 |
|
Attributes for item |
|||
|
Name |
Description |
Format |
Occurrences |
|
number |
Article number |
1-13 digit number |
1 |
|
quantity |
Requested quantity of the article |
1-4 digit number with 0-3 decimals. Defaults to 1.00 if omitted |
0-1 |
|
Attributes for customerregistered |
|||
|
Name |
Description |
Format |
Occurrences |
|
id |
The requested account number |
10-digit number |
1 |
|
type |
The customer type |
1-digit number: 0-7=reserved 8=club member 9=reserved |
1 |
|
subtype |
The customer subtype |
Type-dependent |
0-1 |
|
clublist |
Type-dependent. For type=8 (club member): List of clubs that the customer is a member of. Defaults to club ID 1 internally if omitted. |
List of 1-10 clubs in CSV format. Each club ID is in range 1-99. |
0-1 |
|
Attributes for coupon (voucher) |
|||
|
Name |
Description |
Format |
Occurrences |
|
id |
ID of the voucher (type) |
3-digit number |
1 |
|
isunique |
Indicates if the voucher is unique |
0=false 1=true |
1 |
|
value |
Value of the voucher. Only used for unique vouchers, where it's required. |
Amount |
0-1 |
|
Attributes for discountgroup (under discounts) |
|||
|
Name |
Description |
Format |
Occurrences |
|
id |
ID of the discount group |
8-digit number |
1 |
|
Attributes for item (under items) |
|||
|
Name |
Description |
Format |
Occurrences |
|
id |
ID of the article |
13-digit number |
1 |
XML input example:
<?xml version="1.0" encoding="UTF-8"?>
<basket disablediscounts="0">
<details>
<item number="5740500000548"/>
<item number="5710357000183"
quantity="2"/>
<item number="5740700301582"
quantity="3"/>
<item number="210137"
quantity="1.5"/>
</details>
<customerregistered id="1000000925"
type="8"
clublist="1,2,10"/>
<discountgroupstotrigger>
<discountgroup>56</discountgroup>
<discountgroup>1680</discountgroup>
</discountgroupstotrigger>
<discounts>
<discountgroup id="1984">
<items>
<item id="2000"/>
<item id="1234567890123"/>
</items>
</discountgroup>
<discountgroup id="12345678">
<items>
<item id="2000"/>
</items>
</discountgroup>
</discounts>
<coupons>
<coupon id="42"
isunique="0"
value="0"/>
</coupons>
</basket>
Reply (output)
|
Reply format |
XML/JSON with tags. |
|||
|
Reply body |
See tags elements and attributes in the following |
|||
|
Returns |
200 OK |
|||
|
Tag elements |
|||
|
Name |
Description |
Format |
Occurrences |
|
basket |
Root tag |
|
1 |
|
summary |
Element for receipt summary |
|
1 |
|
vat |
Element for VAT specification |
|
1-* |
|
discount |
Element for discount specification |
|
0-* |
|
unclaimedgifts |
Element for unclaimed gifts |
|
0-1 |
|
unclaimedgift |
Element for an unclaimed gift |
|
1-* |
|
potentialdiscount |
Element for an untriggered discounts group |
|
0-1 |
|
customerregistered |
Element for a customer registration |
|
0-1 |
|
details |
Element for articles (lines) |
|
1 |
|
item |
Element for an article (line) |
|
1-* |
|
linkeditem |
Element for linked article |
|
0-* |
|
potentialdiscountgroups |
Contains links to potential discount groups that the article is in |
|
0-1 |
|
discountgroup |
ID of the group of a potential discount that the article is in |
10-digit number |
1-* |
|
coupons |
Parent for one or more coupon (voucher) elements |
|
0-1 |
|
coupon |
Element for a coupon (voucher) |
|
1-* |
|
errors |
Element for article errors |
|
0-1 |
|
itemerror |
|
|
1-* |
|
Attributes for summary |
|||
|
Name |
Description |
Format |
Occurrences |
|
chain |
Chain number |
1-2-digt number |
1 |
|
store |
Store number |
1-5-digit number |
1 |
|
numberofitems |
The number of articles sold |
1-4-digit number |
1 |
|
subtotal |
The total amount |
1-8-digit number |
1 |
|
Attributes for vat |
|||
|
Name |
Description |
Format |
Occurrences |
|
percent |
The VAT percent |
1-2-digt number with up to 2 decimals |
1 |
|
amount |
The VAT amount based on total price for article |
Amount |
1 |
|
Attributes for customerregistered |
|||
|
Name |
Description |
Format |
Occurrences |
|
id |
The account number registered |
10-digit number |
1 |
|
type |
The customer type |
1-digit number: 0-7= reserved 8=club member 9= reserved |
1 |
|
subtype |
The customer subtype |
Type-dependent |
0-1 |
|
clublist |
Only used for type=8 (club member): List of clubs that the customer is a member of. Club ID 1 will be used by default if omitted in request. |
List of 1-10 clubs in CSV format. Each club ID is in range 1-99. |
0-1 |
|
Attributes for item |
|||
|
Name |
Description |
Format |
Occurrences |
|
number |
The EAN number of the article |
1-13 digit number |
1 |
|
quantity |
The quantity of the article |
Amount |
1 |
|
totalprice |
The total price of all articles for the article in question (= unitprice × quantity) |
Amount |
1 |
|
nettotalprice |
The net total price after applying item rule logic |
Amount |
0-1 |
|
description |
The name of the article |
String |
1 |
|
unitprice |
The unit price of a single article |
Amount |
1 |
|
netunitprice |
The net unit price after applying item rule logic |
Amount |
0-1 |
|
agerestricted |
The minimum age required in order to buy the article in question |
Age in years as number |
0-1 |
|
Attributes for discount |
|||
|
Name |
Description |
Format |
Occurrences |
|
discountgroup |
The triggered discount group ID |
10-digit number |
0-1(*) |
|
family |
The discount family |
8-digit number |
0-1(*) |
|
discounttype |
How the discount was defined |
1-2-digit number: 0 – Article-dependent 1 – Tender-dependent 2 – Till-dependent 3 – Total-dependent (4 – reserved) 5 – Combo-dependent 6 – Voucher-dependent 7 – Price match 8 – Markdown 9 – Customer / article 10 – External system 11 – Club-dependent 12 – Gift with purchase 13 - Points 14 - Total discount 15 - Customer list |
0-1 |
|
amount |
The discount amount |
Amount |
1 |
|
couponid |
The ID of the voucher that triggered the discount when discounttype=6 |
1-3-digit number |
0-1 |
|
offerid |
The offer ID |
10-digit number |
0-1(*) |
|
Attributes for linkeditem |
|||
|
Name |
Description |
Format |
Occurrences |
|
Content and structure similar to attributes for item |
|||
|
Attributes for unclaimedgift |
|||
|
Name |
Description |
Format |
Occurrences |
|
discountgroup |
ID that triggered discount group |
10-digit number |
1 |
|
giftlistid |
Gift list ID |
10-digit number |
1 |
|
numberofunclaimedgifts |
Number of unclaimed gifts |
1-4-digit number |
1 |
|
giftsdeserved |
Number of gifts deserved |
int |
1 |
|
giftquantitysold |
Number of potential gifts sold |
decimal |
1 |
|
Attributes for potentialdiscount |
|||
|
Name |
Description |
Format |
Occurrences |
|
discountgroup |
ID of discount group |
10-digit number |
1 |
|
missingquantity |
The extra quantity that needs to be bought to trigger the discount (0 for non-mix discounts or mix discounts where quantity criteria have been met) |
Amount |
1 |
|
missingamount |
The extra amount that needs to be bought to trigger the discount (0 for non-amount discounts or amount discounts where amount criteria have been met |
Amount |
1 |
|
missingcondition |
0 if condition has been met. 1 if a customer card condition hasn't been met. If condition isn't met, and not a customer card condition, there'll be no potential discount. |
|
|
|
Attributes for coupon (voucher) |
|||
|
Name |
Description |
Format |
Occurrences |
|
id |
ID of the voucher (type) |
3-digit number |
1 |
|
isunique |
Indicates if the voucher is unique |
0=false 1=true |
1 |
|
value |
Value of the voucher. Only used for unique vouchers, where it's required. |
Amount |
0-1 |
|
discountamount |
The total discount given for the voucher in question |
Amount |
0-1 |
|
Attributes for itemerror |
|||
|
Name |
Description |
Format |
Occurrences |
|
number |
ID of failed article |
|
1 |
|
description |
Error description |
|
1 |
|
type |
Error type |
0 - unknown article |
1 |
XML reply example:
<?xml version='1.0' encoding='UTF-8'?>
<basket>
<summary store=3477
numberofitems=7
subtotal="30190">
<vat percent="25.00" amount="60.38"/>
<discount amount="12.80"/>
<unclaimedgifts>
<unclaimedgift discountgroup="0000007000"
giftlistid="123"
numberofunclaimedgifts="1"
giftsdeserved="3"
giftquantitysold="2.000"/>
</unclaimedgifts>
<potentialdiscounts>
<potentialdiscount discountgroup"0000000965"
missingquantity="1"
missingamount="0"
missingcondition="1"/>
<potentialdiscount discountgroup="0000001200"
missingquantity="0"
missingamount="30.15"
missingcondition="0"/>
</potentialdiscounts>
</summary>
<customerregistered id="1000000925"
type="8"
clublist="1,2,10"/>
<coupons>
<coupon id="42" isunique="0" value="0"/>
</coupons>
<details>
<item number="5740500000548"
quantity="1"
description="NEUTRAL SOAP"
unitprice="29.95"
totalprice="29.95">
<vat percent="25.00" amount="5.99"/>
<potentialdiscountgroups>
<discountgroup>0000000965</discountgroup>
</potentialdiscountgroups>
</item>
<item number="5710357000183"
quantity="2"
description="CHERRY TOMATOES"
unitprice="14.95"
totalprice="29.90">
<vat percent="25.00" amount="5.98"/>
<discount discountgroup=56
discounttype=12
amount="12.50"/>
<potentialdiscountgroups>
<discountgroup>0000000965</discountgroup>
<discountgroup>0000001200</discountgroup>
</potentialdiscountgroups>
</item>
<item number="5740700301582"
description="STRONG BEER"
quantity="3"
unitprice="10.95"
totalprice="32.85"
agerestricted=18>
<vat percent="25.00" amount="6.57"/>
<linkeditem number="7000"
description="BOTTLE DEPOSIT"
unitprice="1.50"
quantity="1.000"
totalprice="4.50"/>
<discount discountgroup=1680
discounttype=0
amount="2.90"/>
</item>
<item itemnumber="210137"
description="ROAST BEEF"
quantity="1.5"
unitprice="145.00"
totalprice="217.50"
<vat percent="25.00" amount="43.50"/>
<potentialdiscountgroups>
<discountgroup>0000001200</discountgroup>
</potentialdiscountgroups>
</item>
</details>
</basket>
Basket API revision history
| Version | Date | Change | Author |
|---|---|---|---|
|
2.8.1 |
2021-04-26 |
Added information about ability to use JSON in addition to XML. Added information about .xsd and .json schemas. Added information about offeridstotrigger and offerid. Ensured that attribute names consistently use all lower case. |
MOM |
| 2.8 | 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 (including changing article descriptions in response example from Danish to English), and changed revision history sorting to display most recent changes at top of table. |
MOM |
|
2.7.6 |
2020-01-06 |
Layout |
MIE |
|
2.7.5 |
2019-09-18 |
Improved documentation of discountgroupstotrigger /discounts. |
HEB |
|
2.7.4 |
2019-06-13 |
Added couponid to discount element and discountamount to coupon element |
BER |
|
2.7.3 |
2018-12-17 |
Made disablediscounts a separate flag. Renamed exclusivediscounts to discounts |
NNE |
|
2.7.2 |
2018-12-12 |
Fixed quote type and other minor bugs in examples |
NNE |
|
2.7.1 |
2018-12-12 |
Changed names of subelements under exclusivediscounts |
NNE |
|
2.7 |
2018-12-12 |
Added exclusivediscounts (and subelements) to input |
NNE |
|
2.6 |
2018-07-10 |
Details on LinkedItem in response table and xml example |
BER |
|
2.5 |
2018-05-02 |
Changed discountType 13 added type 15 |
NNE |
|
2.4 |
2018-02.22 |
Added error code 500 description |
PEH |
|
2.3 |
2018-01-26 |
Error output and information on XSD |
BER |
|
2.2 |
2018-01-24 |
Expanded possible values of discounttype with 13 and 14 |
NNE |
|
2.1 |
2017-12-29 |
Added Coupon information to CalculateBasket response |
BER |
|
2.0 |
2017-05-19 |
Layout |
PHJ |
|
1.9 |
2017-03-09 |
Moved giftsdeserved and giftquantitysold to unclaimedgift. |
NNE |
|
1.8 |
2017-02-28 |
Added giftsdeserved and giftquantitysold to discount. |
NNE |
|
1.7.1 |
2017-01-19 |
Isunique for a coupon can now only take 0 or 1 as values |
NNE |
|
1.7 |
2017-01-13 |
Added coupons to input |
NNE |
|
1.6.3 |
2017-01-11 |
Minor fixes of potential discounts in output example |
NNE |
|
1.6.2 |
2016-12-21 |
Discountgroup format updated in input example |
NNE |
|
1.6.1 |
2016-12-08 |
Missingcondition can now only be 0 or 1 |
NNE |
|
1.6 |
2016-12-06 |
Added potentialdiscountgroups to items |
NNE |
|
1.5 |
2016-12-02 |
Added discountgroupsidstotrigger |
NNE |
|
1.4 |
2016-12-01 |
Added potential discounts |
NNE |
|
1.3 |
2016-08-30 |
Added unclaimed gifts to output |
NNE |
|
1.2 draft 1 |
2016-08-23 |
Updated details for attributes on discount element |
KIK |
|
1.2 |
2016-08-23 |
Removed draft status after internal review |
KIK |
|
1.1 draft 1 |
2016-08-12 |
Updated details for customerregistered element |
KIK |
|
1.1 |
2016-08-16 |
Removed draft-state after review |
KIK |
|
1.0 |
2016-03-30 |
First revision |
TAR |
© 2024 Fiftytwo A/S • Disclaimer
Last update: 20 December, 2024 13:22:23 CET
Share this page with your colleagues: