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.
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.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
}
}
],
...
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
}
}
],
...
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
},
...
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
},
...
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."
}
]
}
Last modified 1yr ago