Working with vouchers

There are three voucher methods: AUTO (automatic), CODE (customer enters a code), and URL. All three are reported via the same discounts structure and can perform the same actions.

Most commonly, vouchers are used to reduce the value of the customer's selection, but they can also be used to give a free product or 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 help you do so.

Different voucher methods

Auto

Applied automatically when the criteria are met.

Code

Applied via a code provided by the customer, used via the following mutation:

mutation {
  addVoucher(code: "discount-1") {
    selection {
      discounts {
        method
      }
    }
    userErrors {
      message
      path
    }
  }
}

URL

Similar to code vouchers in functionality; it uses a separate pool of codes, applied via the following mutation:

mutation
  lookupUri(uri: "uri") {
    selection {
      discounts {
        method
    }
  }
}

Types of discounts given by vouchers

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 reflected directly in unit pricing by default.

Let's take the following example:

An item priced at 100 SEK, quantity 2
A 20% campaign
A 10% discount voucher on order items

Request

mutation {
  addVoucher(code: "discount-1") {
    selection {
      lines {
        unitOriginalPrice {
          formattedValue
        }
        unitPrice {
          formattedValue
        }
        unitPriceReduction {
          formattedValue
        }
        originalLineValue {
          formattedValue
        }
        lineValue {
          formattedValue
        }
      }
      checkout {
        totals {
          type
          price {
            value
            formattedValue
          }
        }
      }
    }
    userErrors {
      message
      path
    }
  }
}

Response

{
  "data": {
    "addVoucher": {
      "selection": {
        "lines": [
          {
            "unitOriginalPrice": {
              "formattedValue": "80.00 SEK"
            },
            "unitPrice": {
              "formattedValue": "72.00 SEK"
            },
            "unitPriceReduction": {
              "formattedValue": "8.00 SEK"
            },
            "originalLineValue": {
              "formattedValue": "160.00 SEK"
            },
            "lineValue": {
              "formattedValue": "144.00 SEK"
            }
          }
        ],
        "checkout": {
          "totals": [
            {
              "type": "ITEMS_SUBTOTAL",
              "price": {
                "value": 72,
                "formattedValue": "144.00 SEK"
              }
            },
            {
              "type": "DISCOUNT",
              "price": {
                "value": 0,
                "formattedValue": "0.00 SEK"
              }
            },
            ...
            {
              "type": "GRAND_TOTAL",
              "price": {
                "value": 72,
                "formattedValue": "144.00 SEK"
              }
            }
          ]
        }
      },
      "userErrors": []
    }
  }
}

Line field	Behaviour	Value
`unitOriginalPrice`	Price from the pricelist after campaign per unit	100 SEK - 20% off = 80 SEK
`unitPrice`	`unitOriginalPrice` minus the voucher discount	80 SEK - 10% off = 72 SEK
`unitPriceReduction`	Voucher discount amount applied to the unit	10% of 80 SEK = 8 SEK
`originalLineValue`	Price from the pricelist after campaign for the whole line	80 SEK x 2 = 160 SEK
`lineValue`	`originalLineValue` minus the voucher discount	160 SEK - 10% off = 144 SEK

Discount vouchers on shipping

Discount vouchers may reduce the value of shipping.

If we take our original example of a 10% discount voucher and apply it at the order level, it will look like:

...
            {
              "type": "DISCOUNT",
              "price": {
                "value": -0.5,
                "formattedValue": "-0.50 SEK"
              }
            },
            {
              "type": "SHIPPING",
              "price": {
                "value": 5,
                "formattedValue": "5.00 SEK"
              }
            },
...

Checkout totals type	Behaviour	Value
`ITEMS_SUBTOTAL`	Sum of all `lineValue`	144 SEK
`SHIPPING`	Shipping before discounts	5 SEK
`DISCOUNT`	Sum of all `order-level discounts`	`SHIPPING` - 10% off = -0.50 SEK
`CREDIT`	Sum of all `credits`	0 SEK
`GRAND_TOTAL`	`ITEMS_SUBTOTAL` + `SHIPPING` + `CREDIT` + `DISCOUNT`	144 SEK + 5 SEK + (-0.50 SEK) = 148.50 SEK

Voucher mode

Voucher mode can be set on any selection field across all API queries and mutations. The default mode is LINES.

selection (voucherMode: LINES) {}
or
selection {}

But you can change this mode to TOTAL:

selection (voucherMode: TOTAL) {}

Behaviours

Voucher mode	Behaviour
`LINES` (default)	Applies line vouchers directly to the respective line items.
`TOTAL`	Applies line vouchers to the cart totals until the order is finalized.

Examples

If we take the same example as above and retrieve selection (voucherMode: TOTAL), the line and total values will be modified:

Line field	Behaviour	Value
`unitOriginalPrice`	Price from the pricelist after campaign per unit	100 SEK - 20% off = 80 SEK
`unitPrice`	`unitOriginalPrice`	80 SEK
`unitPriceReduction`	Voucher discount amount applied to the unit	0 SEK
`originalLineValue`	Price from the pricelist after campaign for the whole line	80 SEK x 2 = 160 SEK
`lineValue`	`originalLineValue`	160 SEK

Checkout totals type	Behaviour	Value
`ITEMS_SUBTOTAL`	Sum of all `lineValue`	160 SEK
`SHIPPING`	Shipping before discounts	5 SEK
`DISCOUNT`	Sum of all `order-level discounts`	`SHIPPING` - 10% off + `lineValue` - 10% off = -16.50 SEK
`CREDIT`	Sum of all `credits`	0 SEK
`GRAND_TOTAL`	`ITEMS_SUBTOTAL` + `SHIPPING` + `CREDIT` + `DISCOUNT`	160 SEK + 5 SEK + (-16.50 SEK) = 148.50 SEK

As you can see, GRAND_TOTAL does not change, but ITEMS_SUBTOTAL, DISCOUNT, and line prices change.

Free product vouchers

Free product vouchers will either add an item to the selection or convert an 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 special rules applied to this item, making it impossible to add more of it or remove it. The frontend should use allowAddMore and allowRemove to disable or enable the corresponding UI buttons for that specific line item.

Request fragment

selection {
    discounts {
        actions {
          type
        }
        ... on FreeProductAddedAction {
          lineId
          allowAddMore
          allowRemove
        }
    }
}

Note the value FreeProductAddedAction in selection.discounts.actions.type.

Field	Behaviour
`lineId`	Line ID of the item that was added for free.
`allowAddMore`	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.
`allowRemove`	Is the customer allowed to remove this line.

Free shipping vouchers

Reduces SHIPPING to 0. If an external shipping provider is used, such as Ingrid, the free-shipping information is sent to that system, which then sets the shipping cost. Therefore, it is possible to have a free-shipping voucher but still have to pay for shipping.

Request fragment

selection {
    discounts {
        actions {
            type
        }
        ... on FreeShippingAction {
            shippingMethods
        }
    }
}

Field	Behaviour
`shippingMethods`	List of shipping groups this will give free shipping to.

Applied discounts data

We have already looked at selection.checkout.totals and line item values. We can also view applied discounts in detail:

Request fragment

selection {
  discounts {
    name
    appliedOn
    method
    type
    value {
      formattedValue
    }
    orderReduction {
      formattedValue
    }
    totalItemReduction {
      formattedValue
    }
    totalShippingReduction {
      formattedValue
    }
    lineIds
    actions {
      type
    }
    expiryDate
    giftCard {
      lastFourDigits
    }
    isExternal
  }
}

Response fragment

      "selection": {
        "discounts": [
          {
            "name": "discount-1",
            "appliedOn": [
              "LINES",
              "SHIPPING"
            ],
            "method": "CODE",
            "type": "DISCOUNT",
            "value": {
              "formattedValue": "-16.50 SEK"
            },
            "orderReduction": {
              "formattedValue": "0.00 SEK"
            },
            "totalItemReduction": {
              "formattedValue": "-16.00 SEK"
            },
            "totalShippingReduction": {
              "formattedValue": "-0.50 SEK"
            },
            "lineIds": [
              "5c063a8eb5c34ed499c332cf01878cb4"
            ],
            "actions": [],
            "expiryDate": "2034-07-04 14:05:00",
            "giftCard": null,
            "isExternal": false
          }
        ],

Field	Behaviour
`name`	Name of the discount.
`appliedOn`	Multiple choice values: `ORDER`, `LINES`, `ADDED_LINE`, `SHIPPING`
`method`	As we saw previously, `AUTO`, `CODE` or `URL`
`value`	Total value applied
`orderReduction`	Total reduction applied on the order (for order-level discounts)
`totalItemReduction`	Reduction applied on items
`totalShippingReduction`	Reduction applied on shipping
`lineIds`	All the line IDs concerned by the discount
`actions`	Special actions of the discount: `FreeProductAddedAction` or `FreeShippingAction`
`expiryDate`	Discount expiry date
`giftCard`	Last four digits of the gift card, if applied
`isExternal`	Is the discount external

Different voucher methods​

Auto​

Code​

URL​

Types of discounts given by vouchers​

Discount​

Request​

Response​

Discount vouchers on shipping​

Voucher mode​

Behaviours​

Examples​

Free product vouchers​

Request fragment​

Free shipping vouchers​

Request fragment​

Applied discounts data​

Request fragment​

Response fragment​

Different voucher methods

Auto

Code

URL

Types of discounts given by vouchers

Discount

Request

Response

Discount vouchers on shipping

Voucher mode

Behaviours

Examples

Free product vouchers

Request fragment

Free shipping vouchers

Request fragment

Applied discounts data

Request fragment

Response fragment