Links

Applying a discount

Learn how to apply discounts.
When building a checkout or creating an invoice, you can apply multiple types of discounts to the transaction. You should also be aware of validation errors thrown by zero-value discounts.

Types of discounts

Using the Checkout or Invoice resource, you can apply product, order-level, and shipping cost discounts to transactions. You can also combine discount types.
Each discount type follows the same basic rules. You specify an amountOff or percentOff. Digital River first applies the discount and then the transaction's taxes are determined based on the discounted price. In the response, we return the totalDiscount applied to the transaction.

Product discounts

For each line item that you want to discount, set either a percentOff or amountOff.
You can also provide an optional discount.quantity. This indicates how many products the discount should be applied to. If you don't specify a discount.quantity, we assume you want to apply the discount to all the products in that line item. For example, if theitems[].quantity is 3 and you don't specify a discount.quantity, then, by default, the discount is applied to all three products.
The following POST /checkouts demonstrates both types of item-level discounts. In the percent off request, the discount.quantity is set to 1, so the discount will be applied to only one of the three products. For the amount off request, discount.quantity is not specified, so the discount will be applied to all three products.:
Percent off request
Amount off request
curl https://api.digitalriver.com/checkouts \
-u sk_test_db9682a2-b04a-4e94-8e11-35fe8ec0b324: \
-d currency=usd \
...
-d items[0][skuId]=09062016 \
-d items[0][price]=10.00 \
-d items[0][quantity]=3
-d items[0][discount][percentOff]=10
-d items[0][discount][quantity]=1
curl https://api.digitalriver.com/checkouts \
-u sk_test_db9682a2-b04a-4e94-8e11-35fe8ec0b324: \
-d currency=usd \
...
-d items[0][skuId]=09062016 \
-d items[0][price]=10.00 \
-d items[0][quantity]=3
-d items[0][discount[amountOff]]=2
In each POST /checkouts response, the items[].amount value is adjusted to reflect the discount and the totalDiscount value shows the discount for the entire order.
Percent off response
Amount off response
...
"totalAmount": 31.18,
"subtotal": 29.0,
"totalFees": 0.0,
"totalTax": 2.18,
"totalDuty": 0.0,
"totalDiscount": 1.0,
"totalShipping": 0.0,
"items": [
{
"skuId": "09062016",
"amount": 29.0,
"quantity": 3,
"discount": {
"percentOff": 10.0,
"quantity": 1
},
"tax": {
"rate": 0.07525,
"amount": 2.18
}
}
],
...
...
"totalAmount": 25.81,
"subtotal": 24.0,
"totalFees": 0.0,
"totalTax": 1.81,
"totalDuty": 0.0,
"totalDiscount": 6.0,
"totalShipping": 0.0,
"items": [
{
"skuId": "09062016",
"amount": 24.0,
"quantity": 3,
"discount": {
"amountOff": 2.0,
"quantity": 3
},
"tax": {
"rate": 0.07525,
"amount": 1.81
}
}
],
...

Order-level discounts

You can use either the discount.percentOff or discount.amountOff parameter to create a discount on the entire order.
Percent off request
Amount off request
curl https://api.digitalriver.com/checkouts \
-u sk_test_db9682a2-b04a-4e94-8e11-35fe8ec0b324: \
-d currency=usd \
...
-d discount[percentOff]=20
-d items[0][skuId]=09062016 \
-d items[0][price]=10.00 \
-d items[0][quantity]=4 \
-d items[1][skuId]=11141976 \
-d items[1][price]=20.00 \
-d items[1][quantity]=2 \
curl https://api.digitalriver.com/checkouts \
-u sk_test_db9682a2-b04a-4e94-8e11-35fe8ec0b324: \
-d currency=usd \
...
-d discount[amountOff]=10
-d items[0][skuId]=09062016 \
-d items[0][price]=10.00 \
-d items[0][quantity]=4 \
-d items[1][skuId]=11141976 \
-d items[1][price]=20.00 \
-d items[1][quantity]=2 \
For all line items, Digital River first aggregates their amount values, applies the discount to arrive at a subTotal and then uses that figure to compute a totalTax. This is illustrated in the following POST /checkouts responses.
Percent off response
Amount off response
...
"totalAmount": 68.82,
"subtotal": 64.0,
"totalFees": 0.0,
"totalTax": 4.82,
"totalDuty": 0.0,
"totalDiscount": 16.0,
"totalShipping": 0.0,
"discount": {
"percentOff": 20.0
},
"items": [
{
"skuId": "09062016",
"amount": 40.0,
"quantity": 4,
"tax": {
"rate": 0.07525,
"amount": 2.41
}
},
{
"skuId": "11141976",
"amount": 40.0,
"quantity": 2,
"tax": {
"rate": 0.07525,
"amount": 2.41
}
}
],
...
...
"totalAmount": 75.26,
"subtotal": 70.0,
"totalFees": 0.0,
"totalTax": 5.26,
"totalDuty": 0.0,
"totalDiscount": 10.0,
"totalShipping": 0.0,
"discount": {
"amountOff": 10.0
},
"items": [
{
"skuId": "09062016",
"amount": 40.0,
"quantity": 4,
"tax": {
"rate": 0.07525,
"amount": 2.63
}
},
{
"skuId": "11141976",
"amount": 40.0,
"quantity": 2,
"tax": {
"rate": 0.07525,
"amount": 2.63
}
}
],
...

Shipping cost discounts

You can also apply discounts to shipping costs. The following POST /checkouts demonstrates how to use shippingDiscount to specify either a percentOff or amountOff:
Percent off request
Amount off request
curl https://api.digitalriver.com/checkouts \
-u sk_test_db9682a2-b04a-4e94-8e11-35fe8ec0b324: \
-d currency=usd \
...
-d items[0][skuId]=09062016 \
-d items[0][price]=10.00 \
-d items[0][quantity]=3
-d shippingChoice[amount]=8.00 \
-d shippingChoice[description]="USPS: Priority (1 day delivery)" \
-d shippingChoice[serviceLevel]= "SG"
-d shippingDiscount[percentOff]=25
curl https://api.digitalriver.com/checkouts \
-u sk_test_db9682a2-b04a-4e94-8e11-35fe8ec0b324: \
-d currency=usd \
...
-d items[0][skuId]=09062016 \
-d items[0][price]=10.00 \
-d items[0][quantity]=3
-d shippingChoice[amount]=8.00 \
-d shippingChoice[description]="USPS: Priority (1 day delivery)" \
-d shippingChoice[serviceLevel]= "SG"
-d shippingDiscount[amountOff]=3.00
Once again, Digital River applies the discount before calculating taxes. In the following POST /checkouts responses, totalDiscount includes the shipping cost discount.
Percent off response
Amount off response
...
"totalAmount": 38.71,
"subtotal": 36.0,
"totalFees": 0.0,
"totalTax": 2.71,
"totalDuty": 0.0,
"totalDiscount": 2.0,
"totalShipping": 8.0,
"items": [
{
"skuId": "09062016",
"amount": 30.0,
"quantity": 3,
"tax": {
"rate": 0.07525,
"amount": 2.26
}
}
],
"shippingChoice": {
"amount": 8.0,
"description": "USPS: Priority (1 day delivery)",
"serviceLevel": "SG",
"taxAmount": 0.45
},
"shippingDiscount": {
"percentOff": 25.0
},
...
...
"totalAmount": 37.64,
"subtotal": 35.0,
"totalFees": 0.0,
"totalTax": 2.64,
"totalDuty": 0.0,
"totalDiscount": 3.0,
"totalShipping": 8.0,
"items": [
{
"skuId": "09062016",
"amount": 30.0,
"quantity": 3,
"tax": {
"rate": 0.07525,
"amount": 2.26
}
}
],
"shippingChoice": {
"amount": 8.0,
"description": "USPS: Priority (1 day delivery)",
"serviceLevel": "SG",
"taxAmount": 0.38
},
"shippingDiscount": {
"amountOff": 3.0
},
...

Combined discounts

If you send multiple discounts in a request, Digital River first applies product discounts and then order-level discounts. Product and order-level discounts do not reduce shipping costs. If you want to give customers a break on their shipping costs, you'll need to apply a shipping discount.
The following POST /checkouts response shows a transaction with multiple discounts applied to it:
Response
...
"totalAmount": 35.48,
"subtotal": 33.0,
"totalFees": 0.0,
"totalTax": 2.48,
"totalDuty": 0.0,
"totalDiscount": 15.0,
"totalShipping": 8.0,
"discount": {
"percentOff": 25.0
},
"items": [
{
"skuId": "09062016",
"amount": 36.0,
"quantity": 4,
"discount": {
"percentOff": 10.0,
"quantity": 4
},
"tax": {
"rate": 0.07525,
"amount": 2.03
}
}
],
"shippingChoice": {
"amount": 8.0,
"description": "USPS: Priority (1 day delivery)",
"serviceLevel": "SG",
"taxAmount": 0.45
},
"shippingDiscount": {
"percentOff": 25.0
},
...

Validation errors generated by zero-value discounts

Your integration must send a discount value greater than zero. This applies to product, order-level, and shipping cost discounts. If you submit a POST /checkouts, POST /checkouts/{id} or POST /invoices and amountOff or percentOff is 0 or less, a 400 Bad Request is returned.
Percent off
Amount off
{
"type": "bad_request",
"errors": [
{
"code": "invalid_discount_percent",
"parameter": "discount",
"message": "The value must be an integer between 0.01 and 100.00 inclusive."
}
]
}
{
"type": "bad_request",
"errors": [
{
"code": "invalid_discount_amount",
"parameter": "discount",
"message": "The value 0.0 is not permitted."
}
]
}