Discounts

Discounts are reductions that are applied to a transaction. You use the Discounts object to model these reductions in your requests. For more information about the fields in the Discount object, see Discount Object Fields.

The service calculates discounts for both inclusive and exclusive prices. The logic used for discounts mirrors how you can provide either type of amount for the transaction (using the total_amount and amount fields). For more information about how to configure amounts, see Configuring Payment Amounts.

You specify tax inclusive or exclusive values. The API returns discount amounts for both types of pricing and the total discount applied.

You can apply discounts to a single transaction line or to an entire transaction.

Tax Inclusive Discounts

Tax inclusive prices include the VAT in the displayed price. To specify a tax inclusive amount for a discount, you use the discount_total_amount field:

"discounts": [{
  "discount_total_amount": 12
  "discount_code": line_discount_1

Tax Exclusive Discounts

Tax exclusive prices exclude VAT from the displayed price. To specify a tax exclusive amount for a discount, you use the discount_amount field. For example:

"discounts": [{
 "discount_amount": 10
 "discount_code": line_discount_2

Transaction Line-Level Discounts

You can apply discounts individually to transaction lines. For example:

"transaction": {
  "currency_code": "GBP"
  "ship_to_address: {
    "country_code": "UK"
},
  "transaction_lines":  [
    {
      "total_amount": 123,  
      "discounts": [{
    			"discount_total_amount": 10
        	"discount_code": line_discount_1
      }],
      "custom_id": "line_1"
      "product_class": "p"
      "ship_from_address": {
        "country_code": "UK"
   			 }
   		 }
     }
 }
      {
      "total_amount":50,
      "custom_id": "line_2"
      "product_class": "p"
      "ship_from_address": {
        "country_code": "UK"
   			 }
   		 }
     }
 }

This returns the following discount information. Note the following:

• The discounts.discount_amount field shows the tax exclusive discount amount for the transaction line.
• The discounts.discount_total_amount field shows the tax inclusive total amount for the transaction line.
• The discounts.discounted_total_amount field shows the total discount for that transaction.

"discounts": [
  {
	"discount_code": line_discount_1
  "discount_total_amount": 10
  "discount_amount": 8.13
  }
 ],
  "custom_id": "line-1"
  "discounted_total_amount": "10.00"

Transaction-Level Discounts

You can also apply the discount at a transaction level. The discount is proportionally distributed across the transaction lines for that transaction. This means that a greater percentage of the discount is applied to the lines with relatively larger amounts.

For example, the following applies a 20 GBP discount across 2 transaction lines:

"transaction": {
  "currency_code": "GBP"
  "ship_to_address: {
    "country_code": "UK"
},
        "discounts": [{
    			"discount_total_amount": 20
        	"discount_code": transaction_discount_1
      }]
  "transaction_lines":  [
    {
      "total_amount": 123,
      "custom_id": "line_1"
      "product_class": "p"
      "ship_from_address": {
        "country_code": "UK"
   			 }
   		 }
     }
 }
     {
      "total_amount":50,
      "custom_id": "line_2"
      "product_class": "p"
      "ship_from_address": {
        "country_code": "UK"
   			 }
   		 }
     }
 }

This returns the following for line-1:

"discounts": [
  {
  "discount_code": transaction_discount_1
  "discount_total_amount": 13.87
  "seller_code": seller_test_1
  "discount_amount": 11.28
   }
 ],
  "custom_id": "line-1"

The following discount information is returned for line-2:

"discounts": [
  {
	"discount_code": transaction_discount_1
  "discount_total_amount": 6.13
  "seller_code": seller_test_1
  "discount_amount": 4.98
  }
 ],
  "custom_id": "line-2"

The total discount amount that is applied is returned in the discounts.discounted_total_amount field:

"discounted_total_amount": "20.00"