Skip to content

Promotion Configuration

Promotion configuration should be posted to /RosConnector-1-0/json/PemPublishDirect. Posting a promotion configuration overwrites previous promotion configurations. It may take a few minutes before an updated promotion configuration becomes active.

Request:

{
    "Request": {
        "Label": "string",
        "PemEntries": [
            ...
        ],
        "RosEnvironment": "string",
        "ExternalArticleSets": [
          ...
        ]
    }
}

Properties:

  • Label Promotion configuration label.
  • PemEntries The promotions.
  • RosEnvironment Source environment.
  • ExternalArticleSets Additional article sets. See Get Article Set Summary

Response:

{
  "ReturnCode": "Success",
  "Errors": [
    {
      "Message": "string",
      "Uid": "string"
    }
  ],
  "Message": "string",
  "SequenceNumber": 0
}

Properties:

  • SequenceNumber System assigned promotion configuration number. This configuration number is returned in each calculation response.

Promotions

{
    "Active": true,
    "Code": "string",
    "DayOfWeek": "Every",
    "Description": {
        "Texts": [
            {
                "Text": "string",
                "LanCode": "string"
            }
        ]
    },
    "DisplayLevel": "OnHeader",
    "End": "2024-12-13T15:49:31.817Z",
    "EndTime": "string",
    "LongDescription": {
        "Texts": [
            {
                "Text": "string",
                "LanCode": "string"
            }
        ]
    },
    "MaxReceiptAmt": 0,
    "MinReceiptAmt": 0,
    "Start": "2024-12-13T15:49:31.817Z",
    "StartTime": "string",
    "Tier": 0,
    "DiscountBookingType": "string",
    "ReceiptDescription": {
        "Texts": [
            {
                "Text": "string",
                "LanCode": "string"
            }
        ]
    }
}
  • Active Whether the promotion is active
  • Code Unique promotion code
  • DayOfWeek Days of week
  • Description Promotion description
  • LongDescription Promotion long description
  • ReceiptDescription Promotion receipt description
  • DisplayLevel Whether promotion is displayed on header or line level. This does not impact how promotion is applied, display purpose only.
  • Start Absolute promotion start date/time
  • End Absolute promotion end date/time
  • StartTime Promotion daily start time in format HH:mm:ss
  • EndTime Promotion daily start time in format HH:mm:ss
  • MinReceiptAmt Minimum receipt/total basket amount
  • MaxReceiptAmt Maximum receipt/total basket amount
  • Tier Promotion priority. Lower tiers are processed before higher tiers.
  • DiscountBookingType Discount booking type.

Promotion Filters

Promotion filters determine when a promotion applies. Different filter types exists, indicated by rules.

"PromotionFilters": [
    {
        "Active": true,
        "Identical": true,
        "MaxAmount": 0,
        "MaxOccurs": 0,
        "MinAmount": 0,
        "MinOccurs": 0,
        "Name": "string",

        "PosTypeRules": [],
        "ArticleRules": [],
        "CouponRules": [],
        "CustomerCardRules": [],
        "EmployeeCardRules": [],
        "SiteRules": [],
        "TransactionAttributeRules": []
    }
]

Properties:

  • Active whether the filter is active
  • Identical Whether the filter requires identical items
  • MinOccurs Minimum number of items in filter
  • MaxOccurs Maximum number of items in filter
  • MinAmount Minimum value of items in filter
  • MaxAmount Maximum value of items in filter

Promotion Filters logic

Filters can be combined to create logic. A promotion is rewarded when all filters are valid (And). Or logic must be achieved within a filter and can be achieved by combining multiple rules in a single filter.

Combining rule types

It is not possible to combine different types of rules in a single filter. Variable logic like Item = 001 or has a customer card is not possible.

This promotion applies to either article 001 or 002:

{
    "PromotionFilters": [
        {
            "ArticleRules": [
                {
                    "ArticleId": "001"
                },
                {
                    "ArticleId": "002"
                }
            ]
        }
    ]
}

Promotion requires article 001 and 002:

{
    "PromotionFilters": [
        {
            "ArticleRules": [
                {
                    "ArticleId": "001"
                }
            ]
        },
        {
            "ArticleRules": [
                {
                    "ArticleId": "001"
                }
            ]
        }
    ]
}

Promotion Filter reuse

Promotion filters must be declared on every promotion. Promotion filters cannot be reused. They can be reusable in the source system and mapped to multiple promotions.

Promotion exclusivity

Promotions can be exclusive, ie. at most one promotion is rewarded. This behavior can be influenced with the following properties:

  • Promotion type - different promotion types cannot be exclusive
  • On promotion Tier - different tiers cannot be exlusive

Promotions of the same type and on the same tier are exclusive. The system will determine the most beneficial result for the basket and reward that promotion.

Promotion filter types

Articles

ArticleRules filter for specific items.

"ArticleRules": [
  {
    "ArticleId": "string",
    "ColorId": "string",
    "Exclude": true,
    "GroupId": "string",
    "GroupLevelOffset": 0,
    "MaxPrice": 0,
    "MinPrice": 0,
    "PluRequirement": "DontCare",
    "SaleAttributes": [
      {
        "Type": "string",
        "Value": "string"
      }
    ],
    "SizeId": "string"
  }
]
  • ArticleId ID of article, or *
  • ColorId ID of color, or *
  • Size ID of size, or *
  • Exclude Whether this rule is excluding items
  • GroupId ID of item group, or *. This has to be the item group level (leaf). Groups higher up the tree require to be expanded in multiple leaf group levels.
  • GroupLevelOffset Level of initial group specification. This information is used for rule prioritising.
  • MaxPrice Item maximum price. Ignored when 0
  • MinPrice Item minimum price. Ignored when 0
  • PluRequirement one of DontCare, Required (conditional promo required) or Disallowed (conditional promo not allowed)
  • SaleAttributes One or more sale attributes and values.

Article rules are applied in priority. More specific rules have more priority.

Coupons

CouponRules indicate coupons are required for this promotion.

"CouponRules": [
  {
    "CouponId": "string",
    "CouponDefinitionType": "Generic",
    "UnlimitedUse": true
  }
]
  • CouponId Coupon identifier
  • CouponDefinitionType Generic or unique coupon
  • UnlimitedUse

Customer cards

CustomerCardRules indicate customer cards are required for this promotion.

"CustomerCardRules": [
  {
    "CustomerCardRequirement": "DontCare",
    "CustomerLevelIds": [
      "string"
    ],
    "LimitCount": 0,
    "UnRegistered": true
  }
]

Properties:

  • CustomerCardRequirement one of DontCare, Required (customer card required) or Disallowed (customer card not required)
  • CustomerLevelIds One or more specific customer levels
  • LimitCount The number of times the promotion may be rewarded in total to this specific customer card. Use in conjunction with PriorUse and Customer Voucher API.
  • UnRegistered Whether this promotion is limited to reqistered cards (false), unregistered cards (true) or both (omit)

Employee cards

EmployeeCardRules indicate employee cards are required for this promotion.

"EmployeeCardRules": [
  {
    "EmployeeCardRequirement": "DontCare",
    "EmployeeDiscountType": "Any"
  }
]

Properties:

  • EmployeeCardRequirement one of DontCare, Required or Disallowed
  • EmployeeDiscountType Type of employee discount

Sites / Stores

SiteRules indicate specifics sites are required for this promotion.

"SiteRules": [
  {
    "Sites": [
      {
        "Id": "string"
      }
    ]
  }
]

Properties:

  • Sites Request site is any of the Id specified

Pos types

PosTypeRules indicate specific pos types are required for this promotion.

"PosTypeRules": [
  {
    "PosTypes": [
      {
        "Id": "string"
      }
    ]
  }
]

Properties:

  • PosTypes Request pos type is any of the Id specified

Transaction Attributes / Vouchers

TransactionAttributeRules indicate transaction attributes/vouchers are required for this promotion.

"TransactionAttributeRules": [
  {
    "Value": "string",
    "UnlimitedUse": true
  }
]

Properties:

  • Value The voucher/transaction attribute logical code
  • UnlimitedUse Whether the voucher can be used only once in calculation. Set to true to use the same voucher multiple times for the same promotion.

Promotion Setting types

Promotion settings indicate the reward of the promotion.

Financial promotion

FinancialPromotionSettings Indicates this promotion results in a financial discount.

"FinancialPromotionSettings": {
    "FinancialPromotionType": "NewPriceSet",
    "AssignTo": "Ratio",
    "CalculateOver": "All",
    "Amount": 0,
    "MaxIssueCount": 0,
    "CalculateOverCount": 0,
    "CalculateOverFilterArticleSet": "string",
    "AssignToFilterArticleSet": "string",
    "StackTiers": [
        {
            "TierName": "string",
            "Value": 0,
            "MinOccurs": 0,
            "MaxOccurs": 0,
            "ReceiptDescription": {
                "Texts": [
                    {
                        "Text": "string",
                        "LanCode": "string"
                    }
                ]
            },
            "Description": {
                "Texts": [
                    {
                        "Text": "string",
                        "LanCode": "string"
                    }
                ]
            }
        }
    ]
}

Properties:

  • FinancialPromotionType Type of financial promotion. One of NewPriceSet (new item price), Percentage (relative discount) or AbsoluteAmount (fixed discount value).
  • MaxIssueCount Limits the number of times this promotion can be rewarded
  • Amount Discount value

The following properties indicate how discount should be assigned:

  • AssignTo Where the discount should be assigned to. One of Ratio (divide evenly), MostCheap (cheapest items), MostExpensive (most expensive items), FilterArticleSet (specific article filter) or AllItemsInTransaction (entire basket)
  • AssignToFilterArticleSet The filter to assign the discount to, when CalculateOverFilterArticleSet

When AssignTo is MostCheap or MostExpensive discount is rewarded to the cheapest/most expensive item. When discount is greater than item price it will overflow to the next item.

The following properties indicate how discount should be calculated:

  • CalculateOver Where the discount should be calculated over. One of All (all items in filter), MostCheap (cheapest items), MostExpensive (most expensive items), FilterArticleSet (specific article filter) or AllItemsInTransaction (entire basket)
  • CalculateOverFilterArticleSet The filter to calculate the discount over, when CalculateOver is FilterArticleSet
  • CalculateOverCount The number of items to calculate over, when CalculateOver is MostCheap or MostExpensive

Stack Tier promotions

Use this to create a variable discount value.

Example:

  • 20% off when you purchase 2 items
  • 30% off when you purchase 3 or 4 items
  • 50% off when you purchase 5 or more items

For every stack tier it is possible to specify a deviating code, description and receipt description.

Monetary discount voucher

DiscountVoucherSettings Indicates this promotion results in a monetary discount voucher to be printed and given to the customer. This discount voucher can be used on a next purchase.

"DiscountVoucherSettings": {
    "DiscountVoucherType": "Percentage",
    "Percentage": 0,
    "MaxIssueCount": 0
}

Extra article

ExtraArticleSettings Indicates this promotion results in 1 or more extra articles, either for free or at a discounted price.

"ExtraArticleSettings": {
    "Options": [
        {
            "ArticleId": "string",
            "ColorId": "string",
            "SizeId": "string",
            "AddWithoutQuestion": true
        }
    ],
    "Price": 0,
    "MaxIssueCount": 0,
    "BenefitCount": 0
}
  • Options Extra article options.
  • Price Price of the rewarded extra article. Can be 0 to give the item for free.
  • MaxIssueCount Limits the number of times this promotion can be rewarded.
  • BenefitCount The number of extra articles to be rewarded.

Issue coupon

IssueCouponSettings Indicates this promotion results in a coupon to issue.

"IssueCouponSettings": {
    "CouponIdentifier": "string",
    "PaperCut": true,
    "Print": true,
    "ImageId": "string",
    "ReceiptTextId": "string",
    "MaxIssueCount": 0,
    "ValidAfterDaysIssued": 0,
    "DaysValid": 0,
    "StartDate": "2024-12-13T15:49:31.817Z",
    "EndDate": "2024-12-13T15:49:31.817Z"
}
  • CouponIdentifier Coupon identifier
  • PaperCut Whether coupon requires paper cut and is printed on separate slip
  • Print Whether coupon is to be printed
  • ImageId Reference to coupon image
  • ReceiptTextId Reference to receipt text
  • MaxIssueCount Max number of times to issue this promotion
  • StartDate Coupon validity start
  • EndDate Coupon validity end
  • ValidAfterDaysIssued Number of days this coupon is valid after start date
  • DaysValid Number of days this coupon is valid

Loyalty / bonus points

LoyaltySettings Indicates this promotion results in loyalty points.

"LoyaltySettings": {
    "AllowPartial": true,
    "Amount": 0,
    "AmountPer": 0,
    "LoyaltyAwardType": "PerAmount",
    "LoyaltyProgramType": "Generic",
    "MaxPoints": 0,
    "PointType": "Regular",
    "ProgramId": "string",
    "ThresholdPoints": 0,
    "LoyaltyProgramId": "string",
    "CardThreshold": 0,
    "PrintAlways": true,
    "IsHybrid": true,
    "MaxIssueCount": 0
}

Message

MessageSettings indicates this promotion results in a message.

"MessageSettings": {
    "Message": {
        "Texts": [
            {
                "Text": "string",
                "LanCode": "string"
            }
        ]
    },
    "MessageKey": 0
}
  • Message Message texts
  • MessageKey Message key/reference

Shipping cost discount

ShippingCostSettings indicates this promotion results in financial discount on shipping costs.

"ShippingCostSettings": {
    "ShippingCostDiscountType": "NewPrice",
    "Amount": 0
}
  • ShippingCostDiscountType One of NewPrice, Percentage or AbsoluteAmount
  • Amount Discount value

Receipt text

ReceiptTextSettings indicates this promotion results in additional receipt texts.

"ReceiptTextSettings": {
    "ReceiptTextId": "string"
}
  • ReceiptTextId Id of receipt text.

Remove sale lock

RemoveLockSettings indicates this promotion results in the unlocking of a blocked sale.

"RemoveLockSettings": {
    "UnlockCode": "string",
    "MaxIssueCount": 0
}
  • UnlockCode Code to unlock.
  • MaxIssueCount Max number of times to issue this promotion.

External article sets

Allows specifying article sets. These can be used to determine the value of items in this set on a basket. See Get Article Set Summary

"ExternalArticleSets": [
{
  "Code": "string",
  "ArticleRules": [
    {
      "ArticleId": "string",
      "ColorId": "string",
      "Exclude": true,
      "GroupId": "string",
      "GroupLevelOffset": 0,
      "MaxPrice": 0,
      "MinPrice": 0,
      "PluRequirement": "DontCare",
      "SaleAttributes": [
        {
          "Type": "string",
          "Value": "string"
        }
      ],
      "SizeId": "string"
    }
  ]
}
]
  • Code Article set code
  • ArticleRules One or more item rules. See article rules for promotion configuration.

Promotion suggestion

  • Financial Promotion
  • Message promotion with reference to financial promotion linkedPromotionName. Set suggestion trigger in promotion filters.