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.

  • 0= All customers

  • 1= Specific customer types (requires CustomerType)

  • 2= Voucher (coupon) (requires CustomerType)

  • 3= Payment (not supported)

  • 4= Customer list (use LinkCustomerToDiscountGroup to build list)

  • 5= Condition points

  • 6= Condition points and Customer List

DiscountType

Controls the discount type of the discount group:

  • 0= mix disc (default)

  • 2= amount disc

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.

  • 0= Discount group can be triggered only once for the customer

  • 1= Discount group can be triggered multiple times for the customer

Action

The action that is taken for the discount group

  • 0= deduct (default)

  • 1= Save points (applicable for conditions 0 and 4)

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:

  • 0 = Don't delete points

  • 1 = Delete points

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:

Copy 
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
}

 

Copy 
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]
}

 

Copy 
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]
}

 

Copy 
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
}

 

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

Copy 
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"
}

 

Copy 
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"
}

 

Copy 
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"
}

 

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

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

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

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

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

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

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

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

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

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

Copy 
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.
Support for setting up discountgroups using condition 5.
Support for controlling the discounttype.
CreateDiscountGroup superceeds CreateArticleDiscount and CreateArticleGroupDiscount which are both deprecated.
Changed reply body of GetDiscountId to elementlist for CreateDiscountGroup

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