Vouchers
Last updatedWorking with vouchers#
Vouchers come in 2 primary methods, Automatic and Code these are reported separately in our APIs but both can do the same things.
Most commonly vouchers are used to reduce the value of the customers selection, but they can also be used to give a free product or give free shipping. You will want to display information about these benefits to the customer in different ways, and this article will show you the data we provide to you to do so.
Types of discount given by voucher#
Note that a single voucher might give multiple different discounts.
Discount#
Discount vouchers reduce the value of items and shipping in the selection, for selections this is always reported as a reduction value, so priceEach and totalPrice in line data is price from pricelist minus campaign. How much voucher have reduced a specific line can be found under the discounts object in the totalDiscount field. If you prefer to list this discount on order instead of per line (which is more common) you can either just show the totals.totalDiscountPrice or to list each applied code individually loop discounts.vouchers.
Discount vouchers may reduce the value of shipping, how much is reported in the shippingDiscount field.
The reason we do not provide the percentage a voucher has been configured with is that it can easily be confusing if we have more than 1 voucher with a percentage being applied. Percentages may also be used to only apply to a small collection of the products.
Free product vouchers#
Free product vouchers will either add an item into the selection, or convert an already existing item to be free. Be aware that this means the same item might end up on multiple lines with different prices. There might be some special rules applied to this item making it impossible to add more of it or remove it. This should be reflected in the FE. Adds a param to discount object called freeProductAdded this object has information about which line is the free line as well as if customer is allowed to add more (none free) or remove it.
Free Shipping vouchers#
Reduces the shippingPrice to 0, adds a field to discount object called freeShippingFor which is a list of shipping options that will be free. If an external shipping provider is used such as Ingrid the free shipping is sent on to that system which then sets the shipping cost. So it is possible to have a free shipping voucher but still have to pay for shipping.
Order vs order-item#
Vouchers can be configured end up on order or be spread on items when they become an order. The most common is to have this as “order-items” since it is very helpful for processing returns. And effect of this is that to the customer the prices on receipt look different than it did in the checkout. the final price is the same but instead of seeing a bigger negative number after all the items each item has had the price reduced. if you do not wish to have this behaviour there are some ways around it.
Follow the voucher settings, show voucher on order for selection and spread to item on receipt#
This is the default way, so use totalPrice for row total discount for automaticDiscount total and priceOff per voucher.
Always show voucher value as a total after the items#
For line total use totalPriceAfterCampaign instead of totalPrice, and use totalOriginalDiscountPrice from totals as your discount. Alternatively if you list each voucher individually you can show originalPriceOff instead of priceOff. And for automaticDiscount sum up originalPriceOff and display that. You may want to show discount affecting shipping separately, if so you can use totalOriginalItemDiscountPrice and shippingDiscount individually, these 2 values summed together will always equal totalOriginalDiscountPrice.
Always show voucher value per line#
Use priceEachBeforeDiscount as unit price, use totalPriceBeforeDiscount as line total before any discount, totalPriceAfterCampaign to show price after campaign and totalPriceAfterDiscount for line price after all discounts. To list campaign and voucher reductions separately use line level discounts.totalOriginalDiscount for voucher and item level campaign.discount for campaign. When listing your shipping and totals you can choose to use shippingAfterDiscount to show the discounted shipping, or show shippingValue and shippingDiscount separately.
Can I show discounts on order level and item level at the same time?#
Yes, just make sure to display in a way to not confuse customers.
Different voucher methods#
Auto
Applied automatically when criteria are fulfilled, shows up under automaticDiscounts.
Code
Applied via a code provided by the customer, used via endpoints.
CheckoutAPI: POST vouchers
ShopAPI: POST selections/{selection}/vouchers/
URL
Identical to Code vouchers in functionality, just a separate pool of codes, used via endpoint.
ShopAPI: POST selections/{selection}/voucher-uri/.
Voucher data#
Order level data#
Root level data
1
2
3
4
5
6
7
8
9
{
"discounts": {
"anyDiscount": false,
"discount": "0.00 SEK",
"discountAsNumber": 0,
"vouchers": [],
"automaticDiscounts": []
}
}
| name | type | description |
|---|---|---|
| anyDiscount | boolean | Does any of the objects under “vouchers” give a monetary discount. |
| discount | string | Formatted summary of priceOff given by objects in automaticDiscounts. |
| discountAsNumber | number | Unformatted version of discount. |
| vouchers | array/object | Lists all code an url vouchers applied to the selection. |
| automaticDiscounts | array/object | Lists all auto vouchers applied to the selection. |
Each object under vouchers have some unique information
1
2
3
4
5
{
"voucher": "test-voucher",
"type": "code",
"description": "Test Voucher 140 SEK",
}
| name | type | description |
|---|---|---|
| voucher | string | The vouchers code or url. |
| type | string | Will contain either “code” or “url”. |
| description | string | The name of the voucher. |
Objects under automaticDiscounts also have some unique fields
1
2
3
4
{
"automaticDiscount": "506",
"name": "My Test Auto",
}
| name | type | description |
|---|---|---|
| automaticDiscount | string | The id of the voucher. |
| name | string | The name of the voucher. |
Objects under vouchers and automaticDiscounts share some fields
1
2
3
4
5
6
7
8
9
10
{
"priceOff": "-140.00 SEK",
"priceOffAsNumber": -140,
"isCredit": false,
"originalPriceOff": "-140.00 SEK",
"originalPriceOffAsNumber": -140,
"expiryDate": "2099-10-07 14:20:00",
"attributes": [],
"hasAffectedOrder": true
}
| name | type | description |
|---|---|---|
| priceOff | string | Formatted value for how much is this voucher is actively reducing the total item value by, can change between selection and receipt. |
| priceOffAsNumber | number | Unformatted version of priceOff. |
| originalPriceOff | string | Formatted value for how much discount was given to the order, does not change between selection and receipt. |
| originalPriceOffAsNumber | number | Unformatted version of originalPriceOff. |
| isCredit | boolean | False for discount vouchers, true for credit vouchers (such as gift certificates). |
| expiryDate | string | Date the voucher expires. |
| attributes | array | List of all voucher custom attributes. |
| hasAffectedOrder | boolean | Has this discount affected the order (changed the total price, shipping price or added items). |
Additionally if the voucher gives a discount you will find the following fields
1
2
3
4
5
6
7
{
"lines": [
"fb4c32262fe47308773760fd4e0ac7b2"
],
"shippingDiscountAsNumber": 0,
"shippingDiscount": "0.00 SEK",
}
| name | type | description |
|---|---|---|
| lines | array | A list of all the line IDs this voucher has affected. |
| shippingDiscount | string | Formatted value of how much this discount has reduced the shipping value of the selection. |
| shippingDiscountAsNumber | number | Unformatted version of shippingDiscount. |
If the voucher has added a free product
1
2
3
4
5
6
7
{
"freeProductAdded": {
"line": "4651adcaedb16f1ab275ae889c2c354f",
"allowRemove": true,
"allowAddMore": true
},
}
| name | type | description |
|---|---|---|
| freeProductAdded | object | Object containing some information about the free product added. |
| freeProductAdded.line | string | Line ID of the item that was added for free. |
| freeProductAdded.allowRemove | boolean | Is the customer allowed to remove this line. |
| freeProductAdded.allowAddMore | boolean | Is the customer allowed to add more quantity of this product, note: the added items will not be free, and instead will get the original price of the product. |
for a voucher giving free shipping
1
2
3
4
5
6
{
"freeShippingFor": [
"sek",
"usd"
],
}
| name | type | description |
|---|---|---|
| freeShippingFor | array | List of shipping groups this will give free shipping to. |
Item level voucher data#
The discounts object is null when no vouchers have been applied to the line
1
2
3
4
5
6
7
8
9
10
{
"discounts": {
"totalDiscount": "-140.00 SEK",
"totalDiscountAsNumber": -140,
"totalOriginalDiscount": "-140.00 SEK",
"totalOriginalDiscountAsNumber": -140,
"vouchers": null,
"automaticDiscounts": null
},
}
| name | type | description |
|---|---|---|
| totalDiscount | string | Formatted total discount currently given to line by all vouchers. |
| totalDiscountAsNumber | number | Unformatted version of totalDiscount. |
| totalOriginalDiscount | string | Formatted total of how much discount vouchers have given to this line. |
| totalOriginalDiscountAsNumber | number | Unformatted version of totalOriginalDiscount. |
| vouchers | array | null |
| automaticDiscounts | array | null |
Voucher object data
1
2
3
4
5
6
{
"voucher": "remain-ladder",
"priceOff": "-140.00 SEK",
"priceOffAsNumber": -140,
"hasAffectedItemPrice": false
}
| name | type | description |
|---|---|---|
| voucher | string | Code or url of the voucher, use this to lookup details for voucher in order level data. |
| priceOff | string | Formatted total for how much this voucher lowers the price of the line. |
| priceOffAsNumber | number | Unformatted version of priceOff. |
| hasAffectedItemPrice | boolean | Has this voucher reduced the price of the line already, (always false for selections, true on receipt for “order items” vouchers). |
automaticDiscount object data
1
2
3
4
5
6
{
"automaticDiscount": 516,
"priceOff": "-72.00 SEK",
"priceOffAsNumber": -72,
"hasAffectedItemPrice": false
}
| name | type | description |
|---|---|---|
| automaticDiscount | number | Id of the voucher, use this to lookup details in the order level automaticDiscounts data. |
| priceOff | string | Formatted total for how much this voucher lowers the price of the line. |
| priceOffAsNumber | number | Unformatted version of priceOff. |
| hasAffectedItemPrice | boolean | Has this voucher reduced the price of the line already, (always false for selections, true on receipt for “order items” vouchers). |
Summarized data#
the totals object has a few fields that relate to discounts.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
{
"totals": {
"totalDiscountPrice": "-100.00 SEK",
"totalDiscountPriceAsNumber": -100,
"shippingDiscount": false,
"shippingDiscountAsNumber": false,
"shippingAfterDiscount": "10.00 SEK",
"shippingAfterDiscountAsNumber": 10,
"itemTotalPriceAfterCampaign": "300.00 SEK",
"itemTotalPriceAfterCampaignAsNumber": 300,
"itemTotalPriceAfterDiscount": "200.00 SEK",
"itemTotalPriceAfterDiscountAsNumber": 200,
"totalOriginalItemDiscountPrice": "-100.00 SEK",
"totalOriginalItemDiscountPriceAsNumber": -100,
"totalOriginalDiscountPrice": "-100.00 SEK",
"totalOriginalDiscountPriceAsNumber": -100
}
}
| name | type | description |
|---|---|---|
| totalDiscountPrice | number | The total discount to reduce item + shipping cost by to get grand total. |
| totalDiscountPriceAsNumber | string | Number version of totalDiscountPrice. |
| shippingDiscount | string or false | How much vouchers have reduced the shipping cost. (false if no voucher has affected). |
| shippingDiscountAsNumber | number or false | Number version of shippingDiscount. |
| shippingAfterDiscount | string | Shipping cost after discounts have been applied. |
| shippingAfterDiscountAsNumber | number | Number version of shippingAfterDiscount. |
| itemTotalPriceAfterCampaign | string | The total value of all items after campign discount. |
| itemTotalPriceAfterCampaignAsNumber | number | Number version of itemTotalPriceAfterCampaign. |
| itemTotalPriceAfterDiscount | string | The total value of all items afer all discounts. |
| itemTotalPriceAfterDiscountAsNumber | number | Number version of itemTotalPriceAfterDiscount. |
| totalOriginalItemDiscountPrice | string | How much voucher discount was given to items. (totalOriginalItemDiscountPrice = totalOriginalDiscountPrice - shippingDiscount). |
| totalOriginalItemDiscountPriceAsNumber | number | Number version of totalOriginalItemDiscountPrice. |
| totalOriginalDiscountPrice | string | How much voucher discount was given to items and shipping. (totalOriginalDiscountPrice = totalOriginalItemDiscountPrice + shippingDiscount). |
| totalOriginalDiscountPriceAsNumber | number | Number version of totalOriginalDiscountPrice. |