Dev Docs

Promotions API

Promotions API

On the POS and in the Management Console, you have the possibility to use promotions to create discount actions linked to predefined rules

If you need more information about contacts, please have a look for the user documentation.

Endpoint

The importconfigkey for the simple item import defaultimportPromotionsV1.

Body

The valid json looks like that:

[
{
"__id": "{{__id}}",
"__organizationalId": "{{__organizationalId}}",
"ident": "{{ident}}",
"name": {
"i18nVariants": {
"en_US": "{{name_en_US}}",
"de_DE": "{{name_de_DE}}"
}
},
"relationOn": [
"{{relationOn}}"
],
"triggerSlot": {
"triggerCouponNeeded": {{CouponNeeded}},
"triggerSerial": "{{triggerSerial}}"
},
"typeSlot": {
"typeItem": [
"{{typeItem}}"
]
},
"valueSlot": {
"unit3": [
"{{Unit_1}}"
],
"unit2": [
"{{Unit_2}}"
],
"value": {{Value}}
},
"negativePriceAllowedSlot": {
"negativePriceAllowed": {{negativePriceAllowed}}
},
"validTimeSlot": {
"validFrom": "{{ValidFrom}}",
"validTill": "{{ValidTill}}"
},
"redemptionTimeframesSlot": {
"redemptionTimeframes": [
{
"start": "{{RedemptionStart}}",
"end": "{{RedemptionEnd}}",
"weekday": [
"{{RedemptionDay}}"
]
}
]
},
"buyXPayYSlot": {},
"intervalSlot": {},
"maxRedemptionSlot": {
"maxRedemptionPerReceipt": {{maxRedemptionPerReceipt}}
},
"taxHandlingSlot": {
"taxHandling": [
"{{taxHandling}}"
]
},
"minTurnoverSlot": {},
"sequenceResolutionSlot": {
"sequence": {{Sequence}},
"resolution": {{Resolution}}
},
"promotionGroupSlot": {
"promotionGroups": [
[
"{{PromotionGroups}}"
]
]
},
"contactGroupSlot": {
"contactGroups": [
"{{ContactGroups}}"
]
},
"roundingSlot": {
"rounding": [
"{{Rounding}}"
],
"prorate": [
"{{Prorate}}"
]
},
"itemIdSlot": {
"itemIdentifier": [
[
"{{ItemIdentifier}}"
]
]
},
"itemGroupSlot": {
"itemGroups": [
"{{ItemGroups}}"
]
},
"blacklistedIdSlot": {
"blackListedItems": [
[
"{{blackListedItems}}"
]
]
},
"blacklistedGroupSlot": {
"blackListedItemGroups": [
"{{blackListedItemGroups}}"
]
}
}
]



Definition

Field


__id

Type: "NNNNN" - string

Sample: "12345"

Description: The internal, unique ID of the promotion

__organizationalId

Type: -

Sample: "-1"

Description: The unique ID for the concerning organization structure. By default "-1".

ident

Type: -

Sample: "1"

Description: Numbering of the sequence.

name_de_de
name_en_us

Type: "TEXT" - string

Sample: "Happy Hour Sunday Night"

Description: The name of the promotion.

relationOn

Type: "TEXT" - string

Sample: "Item" or "Receipt"

Description: What should this promotion refer to.

CouponNeeded

Type: boolean

Sample: "True" or "False"

Description: Specifies whether the promotion should be triggered automatically (false) or by a coupon (true).

Serial

Type: "NNNNN" - string

Sample: "12345"

Description: 

TypeItem

Type: "TEXT" - string

Sample: "Item" or "Receipt"

Description: What should this promotion refer to.

Unit_1

Type: "TEXT" - string

Sample: "Currency" or "Percentage"

Description: In which unit should the value selected under "Value" be granted as a discount? Currency or Percentage.

Unit_2

Type: "TEXT" - string

Sample: "Currency" or "Percentage"

Description: In which unit should the value selected under "Value" be granted as a discount? Currency or Percentage.

Value

Type: "NN.NN" - string

Sample: "7.77"

Description: The discount value of this promotion.

NegativePriceAllowed

Type: boolean

Sample: "True" or "False"

Description: Flag which reflects if operating in training mode (true) or not (false).

ValidFrom

Type: Timestamp

Sample: "2023-05-29T13:00:16.726Z"

Description: Specifies the time from which the promotion should be valid.

ValidTill

Type: Timestamp

Sample: "2023-05-29T13:00:16.726Z"

Description: Specifies the time from which the promotion should be invalid.

RedemptionStart

Type: Timestamp

Sample: "09:00pm"

Description: Specifies the time from which the promotion should be enabled.

RedemptionEnd

Type: Timestamp

Sample: "01am"

Description: Specifies the time from which the promotion should be disabled.

RedemptionDay

Type: "TEXT" - string

Sample: "sunday"

Description: What should this promotion refer to.

Interval

Type: "N" - string

Sample: "1"

Description:

maxRedemptionPerReceipt

Type: "N" - string

Sample: "1"

Description: Number of maximum redemptions per receipt.

taxHandling

Type: "TEXT" - string

Sample: "asRebate"

Description:

Sequence

Type: "N" - string

Sample: "1"

Description: The position of this promotion in the sequence of several promotions.

Resolution

Type: "N" - string

Sample: "1"

Description: 

PromotionGroups

Type: "NNNNN" - string

Sample: "12345"

Description: The unique ID of the promotion group to which this promotion should be assigned.

ContactGroups

Type: "NNNNN" - string

Sample: "12345"

Description: The unique IDs of the contact groups for which the promotion is to be used.

Rounding

Type: "TEXT" - string

Sample: "Item" or "Receipt"

Description: What should this promotion refer to.

Prorate

Type: "TEXT" - string

Sample: "default"

Description: What should this promotion refer to.

ItemIdentifier

Type: "NNNNN" - string

Sample: "12345"

Description: The unique IDs of the items for which the promotion is to be used.

ItemGroups

Type: "NNNNN" - string

Sample: "12345"

Description: The unique IDs of the ItemGroups for which the promotion is to be used.

blackListedItems

Type: "NNNNN" - string

Sample: "12345"

Description: The unique IDs of the items which are NOT to be used for the promotion.

blacklistedItemGroups

Type: "NNNNN" - string

Sample: "12345"

Description: The unique IDs of the itemgroups which are NOT to be used for the promotion.

Example case

The Postman project below contains all the necessary files to illustrate an example use-case.

Download postman project "Promotions Import (API)"

  1. Import all the existing .json files into postman.

  2. Enter the following data in the included environments:

    - baseURL

    - username

    - password

    Leave all other entries unchanged.

  3. Open the imported "R7 API | Promotions"-Collection in the postman app.

  4. On the top right corner, assign the imported "R7 API | Promotions"-Environment to the opened collection.

  5. Click the "Send"-Button to send the post to your management console.



Result: The promotion should now appear under the menu point "Master data" - "Promotions" - "Promotion list".