52API PROMOTION

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

HTTP return codes

• 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.

Supported encoding

• ISO-8859-1

• UTF-8

API functions

When the API itself refers to coupons in the following, it means vouchers. See also 52API VOUCHER.

Creation of discount group

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:

 

 

 

 

 

Get created discount group

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:

 

 

 

 

Link vouchers to customer ID

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

 

Get vouchers linked to customer ID

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:

 

Link discount groups to customer ID

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:

 

Unlink discount groups from customer ID

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:

 

Link customer IDs to discount group

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:

 

Unlink customer IDs from discount group

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:

 

Get linked discount groups for customer ID

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:

 

Delete discount group

URL	/DeleteDiscountId
Method	POST
Example query	/DeleteDiscountId
Content-Type		application/json
Content		DiscountId=	Discount group ID (8 digits)
Returns	204 OK 404 Not Found

 

Get discount groups for voucher ID

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 discount groups for voucher

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:

 

Create store group

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:

 

Delete store group

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

 

Get store group

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:

 

Promotion API revision history

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