52API PROMOTION
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 PROMOTION, commonly known as Promotion API, is typically used with retail systems like 52ViKING, and makes it possible to manage personal discounts through customer segmentation in external systems.
It provides features such as:
-
Creation and deletion of discount groups
-
Viewing of discount group master data
-
Linking to customer ID discount groups and vouchers
-
Store group management
Promotion API is part of the 52MASTERPRICER suite of APIs.
-
200 OK
On GET request with a successful reply.
On POST request with a successful reply, when content is returned.
-
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, such as a discount group that wasn't found.
-
ISO-8859-1
-
UTF-8
When the API itself refers to coupons in the following, it means vouchers. See also 52API VOUCHER.
URL |
/CreateDiscountGroup /CreateArticleDiscount (deprecated) /CreateArticleGroupsDiscount (deprecated) |
|
Method |
POST |
|
Example query |
/CreateDiscountGroup |
|
Content-Type |
application/json |
|
Content |
DiscountId= |
Discount group ID where the discounts are stored (8 digits) |
Text |
Discount group description text, shown in 52ViKING (max. 30 characters). |
|
ReceiptText |
Discount text to display on receipt (max. 20 characters). If undefined, receipt will display the text “Discount”. |
|
CouponId |
Voucher type ID (3 digits), condition to trigger the discount (excludes CustomerType) |
|
DiscountPercentage |
Percentage discount on article (integer) (excludes DiscountAmount, DiscountTotalPrice) |
|
DiscountAmount |
Amount discount on article (excludes DiscountPercentage, DiscountTotalPrice) |
|
DiscountTotalPrice |
The total price of article in question (excludes DiscountPercentage, DiscountAmount) |
|
StartTime |
Start date+time for discount (YYYY-MM-DD HH:MM:SS) |
|
EndTime |
End date+time for discount (YYYY-MM-DD HH:MM:SS) |
|
Ean |
Article EAN (13 digits) (applies to CreateArticleDiscount only) |
|
Eans |
List of article EANs (13 digits). Use Ean or Eans field, not both. |
|
Families |
List of families (8 digits) |
|
ArticleGroups |
List of article groups (6 digits) |
|
Departments |
List of departments (6 digits) |
|
AllArticles |
Boolean, if 1 adds all articles |
|
ArticleListIds |
List of ArticleListsIds (8 digits). ArticleLists must be present. |
|
ExcludeEans |
Eans excluded from triggering the discount group |
|
ExcludeFamilies |
Families excluded from triggering the discount group |
|
ExcludeArticleGroups |
ArticleGroups excluded from triggering the discount group |
|
ExcludeDepartments |
Departments excluded from triggering the discount group |
|
ExcludeArticleListIds |
ArticleLists excluded from triggering the discount group |
|
Max |
Max. article quantity per customer to receive a discount (optional, no maximum if undefined) |
|
Min |
Min. article quantity to buy before receiving a discount (optional, no minimum if undefined) |
|
StoreId |
Storeid or storegroupid (4 digits/ string) |
|
Condition |
Defaults to 2 (voucher) if CouponId is present.
|
|
DiscountType |
Controls the discount type of the discount group:
|
|
CustomerType |
Customer type (integer) condition before discount group is triggered (optional) |
|
Days |
List of day IDs (0 for Monday, 6 for Sunday). If not defined, the discount is valid on all days. |
|
OfferHourStart |
Starting time for hour offer, in the format HH:MM:SS If present, OfferHourEnd must also be present. If not present, offer is valid the entire day. |
|
OfferHourEnd |
Ending time for hour offer, in the format HH:MM:SS If present, OfferHourStart must also be present. If not present, offer is valid the entire day. |
|
OfferHourMargin |
Hour margin in minutes to extend the hour offer with. Defaults to 0 if not specified . |
|
MultiUse |
Applicable for Condition=4 (Customerlist) only.
|
|
Action |
The action that is taken for the discount group
|
|
PointType |
Point type (applicable for conditions 1 and 4) |
|
NumberOfPoints |
Number of points to deduct/save (applicable for conditions 1 and 4) |
|
Quantity |
Number of articles needed to trigger the discount (applicable for condtions 1 and 4) |
|
DeletePoints |
If the discount group earns or uses points, delete points of type PointType from all customers? This field is optional. If present values are:
|
|
Returns |
204 OK 400 Bad Request |
Existing discount groups created with the same DiscountId will be overwritten with the new information.
Active vouchers on discount groups created earlier with the same DiscountId will be deleted.
Examples:
Post: /CreateDiscountGroup
{
"DiscountId": 200102,
"Text": "Group102",
”CouponId”: 102,
"DiscountPercentage": 20,
"Max" : 6,
"Min" : 2,
"StartTime": "2015-07-03 06:00:00",
"EndTime": "2015-07-04 20:00:00",
"OfferHourStart": "20:00:00",
"OfferHourEnd": "23:00:00",
"OfferHourMargin": 15,
"Ean": 1234567890123
}
Post: /CreateDiscountGroup
{
"DiscountId": 200102,
"Text": "Group102",
"ReceiptText": "ReceiptText",
”CouponId”: 102,
"DiscountPercentage": 20,
"StartTime": "2015-07-03 06:00:00",
"EndTime": "2015-07-04 20:00:00",
"Days": [0,1,2,3,4,5],
"Eans": [1234567890123, 1234567890124, 1234567890125]
}
Post: /CreateDiscountGroup
{
"DiscountId": 200101,
"Text": "ArticleGroup101",
"ReceiptText": " ReceiptText ",
”CouponId”: 101,
"DiscountPercentage": 20,
"StartTime": "2015-12-31 06:00:00",
"EndTime": "2015-12-31 20:00:00",
"ArticleGroups": [4,5,6,7]
}
Post: /CreateDiscountGroup
{
"DiscountId": 200102,
"Text": "Group102",
”CouponId”: 102,
"DiscountAmount": 15.00,
"Max" : 6,
"Min" : 2,
"StartTime": "2015-07-03 06:00:00",
"EndTime": "2015-07-04 20:00:00",
"Ean": 1234567890123
}
Post: / CreateDiscountGroup
{
"DiscountId": 200102,
"Text": "Group102",
”CouponId”: 102,
"DiscountAmount": 15.00,
"Max" : 6,
"Min" : 2,
"StartTime": "2015-07-03 06:00:00",
"EndTime": "2015-07-04 20:00:00",
"Ean": 1234567890123
"StoreId": “1234”
}
URL |
/GetDiscountId |
Method |
GET |
Query string |
DiscountId= Rabatgruppe id |
Examples of Query |
/GetDiscountId?DiscountId=200102 |
Returns |
200 OK 400 Bad Request 404 Not found |
Reply format |
application/json |
Reply body |
Same elements as those used for creating the article group using CreateDiscountGroup |
Examples:
Get: /GetDiscountId?DiscountId=200000
{
"Condition" : 2,
"CouponID" : 102,
"DiscountId" : 200000,
"DiscountPercentage" : 20,
"Eans" : [ 1234567890125 ],
"EndTime" : "2015-12-31 20:00:00",
"Max" : 2,
"Min" : 2,
"ReceiptText" : "That was cheap",
"StartTime" : "2015-12-31 06:00:00",
"StoreId" : 32,
"Text" : "% discount Event Night"
}
Get: /GetDiscountId?DiscountId=12340987
{
"AllArticles" : 1,
"Condition" : 4,
"DiscountId" : 12340987,
"EndTime" : "2019-12-31 20:00:00",
"Max" : 0,
"Min" : 1,
"ReceiptText" : "example receipt",
"StartTime" : "2018-12-31 06:00:00",
"StoreId" : 32,
"Text" : "Example text"
}
Get: /GetDiscountId?DiscountId=12340987
{
"ArticleGroups" : [ 21, 22 ],
"ArticleListIds" : [ 51, 52 ],
"Condition" : 4,
"Departments" : [ 31, 32 ],
"DiscountId" : 12340987,
"Eans" : [ 1234, 1234567890123, 1234567890124, 1234567890125 ],
"EndTime" : "2019-12-31 20:00:00",
"ExcludeEans" : [ 2345678901234, 2345678901245, 2345678901256 ],
"Families" : [ 11, 12 ],
"Max" : 0,
"Min" : 1,
"ReceiptText" : "example receipt",
"StartTime" : "2018-12-31 06:00:00",
"StoreId" : 32,
"Text" : "Example receipt"
}
Get: /GetDiscountId?DiscountId=12345678
{
"Action" : 0,
"ArticleGroups" : [ 21, 22 ],
"ArticleListIds" : [ 51, 52 ],
"Condition" : 0,
"Departments" : [ 31, 32 ],
"DiscountId" : 12345678,
"Eans" : [ 1, 2, 1234 ],
"EndTime" : "2019-12-31 20:00:00",
"Families" : [ 11, 12 ],
"Max" : 0,
"Min" : 1,
"NumberOfPoints" : 2,
"PointType" : 9,
"ReceiptText" : "example receipt",
"StartTime" : "2018-12-31 06:00:00",
"StoreId" : 32,
"Text" : "Example receipt"
}
URL |
/LinkCustomerToCoupons |
|
Method |
POST |
|
Query string |
|
|
Example query |
/LinkCustomerToCoupons |
|
Content-Type |
application/json |
|
Content |
CustomerId= Coupons= |
Customer ID (24 char) Voucher type IDs (1-999) |
Returns |
204 OK 400 Bad Request |
URL |
/GetCustomerCoupons |
|
Method |
GET |
|
Query string |
CustomerId= |
Customer ID (24 chars) |
Example query |
/GetCustomerCoupons?CustomerId=ABCD1234 |
|
Accept |
application/json |
|
Accept-Charset |
ISO8859-1 UTF-8 |
|
Returns |
200 OK & JSON reply 400 Bad Request |
|
Reply format |
application/json |
|
Reply body |
JSON with the following tags: |
|
CustomerId= |
Customer ID (24 char) |
|
Coupons= |
Voucher type IDs (1-999) |
Example:
Get: GetCustomerCoupons?CustomerId=ABCD1234
{
"CustomerId" : "ABCD1234",
"Coupons" : [99,100,101,102]
}
URL |
/LinkCustomerToDiscountGroups |
|
Method |
POST |
|
Query string |
|
|
Example query |
/ LinkCustomerToDiscountGroups |
|
Content-Type |
application/json |
|
Content |
CustomerId= DiscountGroups= |
Customer ID (24 char) List of DiscountGroupIds (8 digits) |
Returns |
204 OK 400 Bad Request |
Example:
POST / LinkCustomerToDiscountGroups
{
"CustomerId": "2222222222",
"DiscountGroups": [200000,200003,200004]
}
Will remove the links created by LinkCustomerToDiscountGroups, described in the previous.
URL |
/UnlinkCustomerFromDiscountGroups |
|
Method |
POST |
|
Query string |
|
|
Example query |
/ LinkCustomerToDiscountGroups |
|
Content-Type |
application/json |
|
Content |
CustomerId= DiscountGroups= |
Customer ID (24 char) List of DiscountGroupIds (8 digits) |
Returns |
204 OK 400 Bad Request |
Example:
POST / UnlinkCustomerFromDiscountGroups
{
"CustomerId": "2222222222",
"DiscountGroups": [200000,200003,200004]
}
URL |
/LinkCustomersToDiscountGroup |
|
Method |
POST |
|
Query string |
|
|
Example query |
/ LinkCustomerToDiscountGroups |
|
Content-Type |
application/json |
|
Content |
CustomerIds= DiscountGroup= |
List of Customer IDs (24 char) DiscountGroupId (8 digits) |
Returns |
204 OK 400 Bad Request |
Example:
Post: /LinkCustomersToDiscountGroup
{
"CustomerIds": ["ABCD1234","EFGH5678"],
"DiscountGroup": 20000001
}
Will remove links created by LinkCustomersToDiscountGroup, descibed in the previous.
URL |
/UnlinkCustomersFromDiscountGroup |
|
Method |
POST |
|
Query string |
|
|
Example query |
/ LinkCustomerToDiscountGroups |
|
Content-Type |
application/json |
|
Content |
CustomerIds= DiscountGroup= |
List of Customer IDs (24 char) DiscountGroupId (8 digits) |
Returns |
204 OK 400 Bad Request |
Example:
Post: /UnlinkCustomersFromDiscountGroup
{
"CustomerIds": ["ABCD1234","EFGH5678"],
"DiscountGroup": 20000001
}
URL |
/GetCustomerDiscountGroups |
|
Method |
GET |
|
Query string |
CustomerId= |
Customer ID (24 char) |
Example query |
/GetCustomerDiscountsGroups?CustomerId=ABCD1234 |
|
Accept |
application/json |
|
Accept-Charset |
ISO8859-1 UTF-8 |
|
Returns |
200 OK & JSON reply 400 Bad Request |
|
Reply format |
application/json |
|
Reply body |
JSON with the following tags: |
|
CustomerId= |
Customer ID (24 char) |
|
DiscountGroups= |
Discount group ID (8 digits) |
Example:
Get: GetCustomerDiscountGroups?CustomerId=ABCD1234
{
"CustomerId" : "ABCD1234",
"DiscountsGroups" : [12345678,90002]
}
URL |
/DeleteDiscountId |
||
Method |
POST |
||
Example query |
/DeleteDiscountId |
||
Content-Type |
application/json |
||
Content |
DiscountId= |
Discount group ID (8 digits) |
|
Returns |
204 OK 404 Not Found |
This function is used to get discount groups with a specific voucher type ID.
URL |
/GetCouponIdDiscountGroups |
||||
Method |
GET |
||||
Query string |
CouponId |
ID of voucher |
|||
Example query |
/GetCouponIdDiscountGroups?CouponId=123 |
||||
Content-Type |
application/json |
||||
Returns |
200 OK & JSON reply 404 Not Found |
||||
Reply format |
application/json |
||||
Reply body |
JSON with the following tags: |
||||
CouponId= |
Voucher ID (3 digits) |
||||
DiscountGroups= |
List of discount group IDs (8 digits) |
Example:
Get: GetCouponIdDiscountGroups
{
"CouponId" : 123,
"DiscountGroups" : ["20001","200002","200003"]
}
This function is used to get discounts groups conditioned by a specific voucher barcode.
URL |
/GetCouponDiscountGroups |
||||
Method |
GET |
||||
Query string |
Coupon |
Voucher barcode |
|||
Example query |
/GetCouponDiscountGroups?Coupon=9891001123400000001794 |
||||
Content-Type |
application/json |
||||
Returns |
200 OK & JSON reply 404 Not Found |
||||
Reply format |
application/json |
||||
Reply body |
JSON with the following tags: |
||||
CouponId= |
Voucher ID (3 digits) |
||||
DiscountGroups= |
List of discount group IDs (8 digits) |
Example:
Get: GetCouponDiscountGroups
{
"CouponId" : 123,
"DiscountGroups" : ["20001","200002","200003"]
}
This function is used to create store groups. Store groups can be used in conjunction with discount groups to specify a given set of stores. It’ll overwrite StoreGroupId if that exists.
URL |
/CreateStoreGroup |
|
Method |
POST |
|
Example query |
/CreateStoreGroup |
|
Content-Type |
application/json |
|
Content |
StoreGroupId |
Store group ID (max. 4 characters) This ID can be used in the StoreId field in CreateArticleDiscount/CreateArticleGroupDiscount Must begin with capital letter B-Z |
StoreGroupText |
Store group description (max. 32 characters) |
|
StoreIds |
List of stores or store ranges in the store group A range of stores is indicated as 1111..1234 |
|
Returns |
204 OK 400 Bad Request |
Example:
Post: CreateStoreGroup
{
"StoreGroupId" : "BCDE",
"StoreGroupText":"Store group area 1"
"StoreIds" : ["2201","2204..2210","2250"]
}
Deleting a store group does not affect discount groups to which the store group is related.
URL |
/DeleteStoreGroup |
Method |
DELETE |
Query string |
StoreGroupId |
Example query |
/DeleteStoreGroup?StoreGroupId=1234 |
Returns |
204 OK 404 Not Found |
Gets a previously created store group.
URL |
/GetStoreGroup |
|
Method |
GET |
|
Query string |
StoreGroupId |
|
Example query |
/GetStoreGroup?StoreGroupId=1234 |
|
Returns |
200 OK 400 Bad Request 404 Not found |
|
Reply format |
application/json |
|
Reply body |
StoreGroupId |
Store group ID (max. 4 characters) This ID can be used in the StoreId field in CreateArticleDiscount/CreateArticleGroupDiscount |
StoreGroupText |
Store group description (max. 32 characters) |
|
StoreIds |
List of stores or store ranges in the store group A range of stores is indicated as 1111..1234 |
Example:
Get: GetStoreGroup
{
"StoreGroupId" : "BCDE",
"StoreGroupText":"Store group area 1"
"StoreIds" : ["2201","2204..2210","2250"]
}
Version |
Date |
Change |
Author |
---|---|---|---|
1.18 |
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 translating sporadic occurrences of Danish text into English), and changed revision history sorting to display most recent changes at top of table. |
MOM |
1.17 |
2020-01-06 |
Layout |
MIE |
1.16 |
2019-09-20 |
Added DiscountTotalPrice (Total Price) |
PEH |
1.15 |
2019-08-13 |
Added DeletePoints element to CreateDiscountGroup |
BER |
1.14 |
2019-06-22 |
Reintroduce condition 5 (Condition points) and added new condition 6 (Condition Points & Customer List) i.e. a combination of condition 5 and 6. Removed action 4. |
BER |
1.13 |
2019-05-08 |
Added Unlink functions UnlinkCustomersFromDiscountGroup and UnlinkCustomerFromDiscountGroups |
BER |
1.12 |
2019-04-12 |
Condition 5 is from now obsolete. New action 4 (Use points) added. CreateDiscountGroup description updated to reflect this. |
BER |
1.11 |
2019-02-05 |
Added Quantity field in CreateDiscountGroup. |
BER |
1.10 |
2018-12-20 |
Improved support for discount group article management. |
BER |
1.9 |
2018-11-07 |
Moved issue unique coupons to Voucher API |
PEH |
1.8 |
2018-10-10 |
Added option MultiUse for multiple triggering of discountgroup when using customer list (condition=4) |
BER |
1.7 |
2018-03-20 |
Added support for specific Day and hours offers |
PEH/BER |
1.6 |
2017-09-26 |
Added LinkCustomersToDiscountGroup |
BER |
1.5 |
2017-05-19 |
Layout and translation |
PHJ |
1.4 |
2016-11-16 |
Support for RecieptText (bontxt) in CreateArticleDiscount, CreateArticleGroupsDiscount and GetDiscountId |
BER |
1.3 |
2016-10-19 |
Added IssueCoupons |
APE/PEH |
1.1 |
2016-09-01 |
Added GetCouponIdDiscountGroups |
BER |
1.2 |
2016-09-02 |
Added GetCouponDiscountGroups |
BER |
1.0 |
2016-07-05 |
Limitation of discount group id removed and other small adjustments |
BER |
0.9 |
2016-05-19 |
New methods for administration of discount groups. |
BER |
0.8 |
2016-04-04 |
Extended discountgroup with discount amount and store groups/store ids |
PEH |
0.7 |
2016-03-17 |
Support for customertype and article ”points” |
PEH |
0.6 |
2016-02-02 |
Layout adjustments |
PEH |
0.5 |
2015-10-29 |
Extend API to support article list, added min/max quantity pr. Customer. Added method DeleteDiscountId |
PEH |
0.4 |
2015-08-07 |
Change of tags and added CouponId |
APE |
0.2 |
2015-07-03 |
Added Text and information about existing discount groups to CreateArticleXXXDiscount |
BER |
0.3 |
2015-07-06 |
Formatted response layout |
BER |
0.1 |
2015-04-06 |
Initial version |
PEH |
© 2024 Fiftytwo A/S • Disclaimer
Last update: 29 November, 2024 13:22:48 CET
Share this page with your colleagues: