Request Elements

This page describes the various request elements.

Sales

"Sales": [
    {
        "Uid": "string",
        "ArticleId": "string",
        "ColorId": "string",
        "GroupId": "string",
        "SizeId": "string",
        "Amount": 0,
        "Count": 0,
        "MaxDiscountPercentage": 0,
        "Attribs": [
            {
                "Type": "string",
                "Value": "string"
            }
        ],
        "Flags": [
            "EmployeeDiscount"
        ],
        "AirmilesPayment": {
            "AirMilesToRedeem": 0
        },
        "Discounts": [
            {
                "Uid": "string",
                "DiscountId": "string",
                "Amount": 0,
                "Percentage": 0,
                "NewPrice": 0,
                "Type": "Amount",
                "MaxIssuedDiscountValue": 0,
                "MaxIssuedDiscountPercentage": 0,
                "ValuePerUnitReceipt": 0,
                "PointsPerUnitReceipt": 0,
                "CustomerOrderGenerated": true
            }
        ]       
    }
]

Name	Commentary	Type	Mandatory
Uid	Unique request element id.	String	Yes
ArticleId		String	Yes
ColorId		String	No
GroupId		String	Yes
SizeId		String	No
Amount	The total gross amount of the sale line. In this value the number of articles (count) is already taking into account. E.g. two items of 50,- gives an amount of 100,-.	Int	Yes
Count	Number of items	Int	Yes
MaxDiscountPercentage	Max percentage of discount allowed on this line item	Int	No
Attribs	Extra item characteristics	Complex	No
Flags	Zero, one or more of EmployeeDiscount (assign employeediscount), AirmilesLoyalty (collect Air Miles for this item) and DenyDiscount (do not assign any discount to this item)	Complex	No
AirmilesPayment	The number or Airmiles that will be used to calculate the actual Airmiles discount/payment	Complex	No

Line discounts

An unconditional promotion gives an item a new price for a certain period. This results in a discount of the difference between the normal and unconditional promotion price. This discount is unconditonal but should nonetheless be included in the basket. This may affect other discount business rules.

Example of a Plu type line discount:

"Sales": [
    {
        "Uid": "Sale001",
        "ArticleId": "10187055003",
        "GroupId": "186",
        "Discounts": [
            {
                "Uid": "PLU001",
                "NewPrice": 2250,
                "Type": "Plu"
            }
        ],
        "Amount": 3000,
        "Count": 3
    }
]

In this example three items of 10,- are in the basket. These items have unconditional promotion prices of 7,50 per item and the new price of the set is 22,50. This value needs to take item quantity into account.

The following result will be given:

"FinancialResults": [
    {
        "Ref": {
            "Uid": "Sale001",
            "Tier": -160000,
            "Gid": 0
        },
        "Amount": 750,
        "Count": 3,
        "Type": "Plu"
    }
]

As seen in the above result the total amount for the sale line is 7,50, divided over three lines, of the type Plu.

NewPrice

With a NewPrice line discount it is possible to specify a new price on line level and get the difference as a discount.

"Sales": [
    {
        "Uid": "Sale001",
        "ArticleId": "10187055003",
        "GroupId": "186",
        "Discounts": [
            {
                "Uid": "manual-discount-new-price",
                "NewPrice": 2250,
                "Type": "NewPrice",
                "DiscountId" : "MyDiscountId"
            }
        ],
        "Amount": 3000,
        "Count": 3
    }
]

Customer cards

Example:

"CustomerCards": [
    {
        "Uid": "LOY001",
        "CustomerLevelId": "VIP"
    }
]

Properties:

Name	Commentary	Type	Mandatory
Uid	Unique request element id.	String	Yes
CustomerLevelId	Type/level of customer card.	String	No
DiscountPercentage	Customer specific discount percentage.	Int	No
PreCalculate	Whether the specified customer card is to be precalculated with this basket. Discounts will not actually be rewarded	Boolean	No

Air Miles cards

Example:

"AirmilesCards": [
    {
        "Uid": "string",
        "Balance": 0,
        "ValuePerUnit": 0,
        "PointsPerUnit": 0,
        "VoucherDiscountPointsPerUnit": 0,
        "VoucherDiscountValuePerUnit": 0
    }
]

Properties:

Name	Commentary	Type	Mandatory
Uid	Unique request element id.	String	Yes
Balance	Available balance for customer. Provide only in case of redemption, not necessary for earn only.	Int	No
ValuePerUnit	Value per unit.	Int	No
PointsPerUnit	Points for unit.	Int	No
VoucherDiscountValuePerUnit	Value per unit.	Int	No
VoucherDiscountPointsPerUnit	Points for unit.	Int	No

Note: Balance is the amount in the local currency (not the total number of points), keep this in mind when setting the parameter. The consuming system needs to translate the number of Airmiles to the amount in the local currency.

The value is used to control the Airmiles payments; the consuming system determines the amount used and validates it against the available number of points.

For example:

• Article A, limited to a 20,- payment through Airmiles
• Article B, limited to a 10,- payment through Airmiles
• Airmiles balance is 25,-

In this case a discount will be applied of 20,- to article ‘A’ and a discount of 5,- to article ‘B’ (together 25,-).

Employee cards

Example:

"EmployeeCards": [
    {
        "Uid": "string",
        "DiscountPercentage": 0,
        "Balance": 0
    }
]

Properties:

Name	Commentary	Type	Mandatory
Uid	Unique request element id.	String	Yes
DiscountPercentage	Employee specific discount percentage.	Int	No
Balance	The available balance for discount. Applied employee discount is limited to this value. When 0 there is no limit.	Int	No

Header discounts

Header discounts are specified on header level - ie. not assigned to specific items.

Example:

"Discounts": [
    {
        "Uid": "string",
        "DiscountId": "string",
        "Amount": 0,
        "Percentage": 0,
        "NewPrice": 0,
        "Type": "Amount",
        "MaxIssuedDiscountValue": 0,
        "MaxIssuedDiscountPercentage": 0,
        "ValuePerUnitReceipt": 0,
        "PointsPerUnitReceipt": 0,
        "CustomerOrderGenerated": true
    }
]

Properties:

Name	Commentary	Type	Mandatory
Uid	Unique request element id.	String	Yes
DiscountId		String	No
Type	Type of discount	String	No
Amount	The value when discount type is fixed	Int	No
Percentage	The value when discount type is percentage	Int	No
NewPrice	The value when discount type is new price	Int	No
MaxIssuedDiscountValue	Limits the discount rewarded by value	Int	No
MaxIssuedDiscountPercentage	Limits the discount rewarded by percentage	Int	No
ValuePerUnitReceipt	For Air Miles	Int	No
PointsPerUnitReceipt	For Air Miles	Int	No
CustomerOrderGenerated	Indicates the discount is already rewarded by another system and cannot be modified	Boolean	No

An example, to an article of 100,- a discount of 15,- and 10% is applied:

{
    "Request": {
        "CalculationMoment": "2024-11-07T17:43:19.924Z",
        "LanCode": "nl-NL",
        "Sales": [
            {
                "Uid" : "Sale001",
                "ArticleId" : "10187055003",
                "GroupId" : "GROUP001",
                "Amount" : 10000,
                "Count" : 1,
                "Discounts" : [
                    {
                        "Type" : "Amount",
                        "DiscountId" : "CustomDiscount-1",
                        "Uid" : "Discount001",
                        "Amount" : 1500
                    },
                    {
                        "Type" : "Percentage",
                        "DiscountId" : "CustomDiscount-2",
                        "Uid" : "Discount002",
                        "Percentage" : 1000
                    }
                ]
            }
        ],
        "SiteId": "9999"
    }
}

The result of the operation:

{
    "FinancialResults": [
        {
            "Ref": {
                "Uid": "Sale001",
                "Tier": 150,
                "Gid": 0
            },
            "Amount": 1500,
            "Count": 1,
            "Type": "ReceiptAmount",
            "DiscountId": "CustomDiscount-1"
        },
        {
            "Ref": {
                "Uid": "Sale001",
                "Tier": 160,
                "Gid": 0
            },
            "Amount": 850,
            "Count": 1,
            "Type": "ReceiptPercentage",
            "DiscountId": "CustomDiscount-2"
        },
        {
            "Ref": {
                "Uid": "Sale001",
                "Tier": 200,
                "Gid": 0
            },
            "Amount": 956,
            "Count": 1,
            "Code" : "Bonus_10187055003",
            "Type": "Promotion",
            "Desc" : "Bonus op 10187055003"
        }
    ],
    "ConfigurationSequenceNumber": 3367,
    "Code": "Success",
    "Warnings": []
}

The following discounts are applied:

• 15,00; the 15,- (amount) discount
• 8,50; 10% on the remaining 85,- (100,- minus the 15,- amount discount)
• Promotional discount of 9,56; 12,5% discount on the remaining 76,50 (85,- minus 8,50; the previously applied 10% discount)

Coupons

Example:

"Coupons": [
    {
        "CouponId": "string",
        "Uid": "string",
        "Type": "Generic"
    }
]

Properties:

Name	Commentary	Type	Mandatory
Uid	Unique request element id.	String	Yes
CouponId	Coupon identifer. This is generic coupon code, unique coupons have to be status checked/converted to generic coupon code	String	Yes
Type	Coupon type	String	Yes

Vouchers (Transaction Attributes)

It is possible to have promotions trigger on certain (customer) characteristics provided by the consuming system. For example, having a promotion trigger on the birthday of a customer. The service does not keep track of any of these events, they have to be provided (in a TransactionAttribute element) and configured in order to trigger correctly.

The process can be described as below:

1. In the promotion configuration a discount has been configured to trigger if the voucher TODAY_BIRTHDAY exists.
2. A transaction is created on the consuming system.
3. The consuming system knows today is the birthday of the customer and adds the voucher TODAY_BIRTHDAY to the transaction and thus the request to Treazure Promo.

Example:

"TransactionAttributes": [
    {
        "Uid": "string",
        "Value": "string",
        "PreCalculate": true,
        "AirMilesToRedeem": 0
    }
]

Properties:

Name	Commentary	Type	Mandatory
Uid	Unique request element id.	String	Yes
Value	Voucher identifier. Please note this is not the barcode/unique voucher id	String	Yes
PreCalculate	Whether the specified voucher is to be precalculated with this basket. Discounts will not actually be rewarded	Boolean	No
AirMilesToRedeem	Price of voucher in Air Miles	Int	No

Shipping costs

Shipping costs can be provided with the basket. It is possible to give discount on shipping costs. Note that shipping costs cannot be issued by basket calculation, only discount can be rewarded on provided shipping costs.

Example:

"ShippingCosts": [
    {
        "Uid": "string",
        "Amount": 0
    }
]

Properties:

Name	Commentary	Type	Mandatory
Uid	Unique request element id.	String	Yes
Amount	Shipping costs amount.	Int	Yes

Prior uses

A promotion can be limited to a fixed number of times it can trigger per customer. Treazure Promo, being stateless, does not keep track of this. Meaning that the consuming system must keep track of how many times a promotion is used by a certain customer. In the configuration it is possible to take prior uses and limitations into account.

The process can be described as below:

1. The constuming system retrieves prior uses, for example by using the CustomerVoucher API
2. For each previously used promotion a PriorUses element is registered in the request

Example:

"PriorUses": [
    {
        "Uid": "string",
        "PemEntryCode": "string",
        "Count": 0
    }
]

Properties:

Name	Commentary	Type	Mandatory
Uid	Unique request element id.	String	Yes
PemEntryCode	Promo code	String	Yes
Count	The number of times the promotion triggered before.	Int	Yes