Discounts

There are two types of discounts: Line Item and Transaction Level. Line Item discounts are applied to individual items in the sale, while Transaction Level discounts are applied to the entire sale.

Examples of Line Item discounts include:

• 10% off all shoes
• $5 off a specific item
• Buy one get one free

Examples of Transaction Level discounts include:

• 10% off the entire sale
• $5 off the entire sale

Discount Object

{
  "totalGrossAmount": {
    "currency": "EUR",
    "amount": "4.20"
  },
  "unitGrossAmount": {
    "currency": "EUR",
    "amount": "0.42"
  },
  "quantity": {
    "quantity": "10",
    "unit": "pieces"
  },
  "percentage": "25",
  "description": {
    "contentType": "text/markdown",
    "content": "**-25% on organic milk**"
  },
  "discountCode": "123456"
}

Field	Type	Description
totalGrossAmount	Money	The total gross amount of the discount. This is required
unitGrossAmount	Money	The gross amount of the discount per unit. Only applicable when the discount applies on a per unit basis.
quantity	Quantity	The quantity of the discount. Only applicable when the discount applies on a per unit basis. Some discounts may be restricted by quantity (e.g. first 10 items, household quantities)
percentage	String	The percentage of the discount.
description	FormattedText	The description of the discount.
discountCode	String	The discount code. This should be supplied to identify which discounts were applied.

Line Item Discounts

Line Item discounts are applied to individual items in the sale. Thus they are sent in the $.lineItems[*].discounts array. Every line item can have multiple discounts and all discounts only applicable to that line item MUST be sent in the $.lineItems[*].discounts array. Line Item discounts MUST NOT be repeated in the top level $.discounts array. Discounts that are applied to a line item MUST be accounted for in the $.lineItems[*].grossTotal field (see Amounts).

Example

Imagine buying 10 cartons of organic milk, with a discount of 25% off each carton. If a carton costs €1.69 then each carton would be discounted by €0.42. The total discount would be €4.20. If instead the discount was applied not on a per unit but total basis, the discount would be $10 \cdot €1.69 \cdot 25\% = €4.23$. The discounted price have to be reflected in grossUnitPrice and grossTotal as well as taxes and totalTax fields of the line item. The original prices can be sent in the baseGrossUnitPrice and baseGrossTotal fields.

{
  "lineItems": [
    {
      "lineItemId": "1",
      "name": "Organic milk",
      "articleId": "934392",
      "quantity": {
        "quantity": "10",
        "unit": "pieces"
      },
      "discounts": [
        {
          "totalGrossAmount": {
            "currency": "EUR",
            "amount": "4.20"
          },
          "unitGrossAmount": {
            "currency": "EUR",
            "amount": "0.42"
          },
          "quantity": {
            "quantity": "10",
            "unit": "pieces"
          },
          "percentage": "25",
          "description": {
            "contentType": "text/markdown",
            "content": "**-25% on organic milk**"
          },
          "discountCode": "123456"
        }
      ],
      "gtin": {
        "format": "GTIN-13",
        "content": "1234567890123"
      },
      "baseGrossUnitPrice": {
        "currency": "EUR",
        "amount": "1.69"
      },
      "grossUnitPrice": {
        "currency": "EUR",
        "amount": "1.27"
      },
      "baseGrossTotal": {
        "currency": "EUR",
        "amount": "16.90"
      },
      "grossTotal": {
        "currency": "EUR",
        "amount": "12.70"
      },
      "totalTax": {
        "currency": "EUR",
        "amount": "1.15"
      },
      "netTotal": {
        "currency": "EUR",
        "amount": "11.55"
      },
      "taxes": [
        {
          "taxType": "VAT",
          "percentage": "10",
          "grossAmount": {
            "currency": "EUR",
            "amount": "12.70"
          },
          "taxAmount": {
            "currency": "EUR",
            "amount": "1.15"
          },
          "netAmount": {
            "currency": "EUR",
            "amount": "11.55"
          }
        }
      ]
    }
  ]
}

Transaction Level Discounts

Discounts that do not apply to individual line items, but to the entire sale, should be sent in the $.discounts array. These discounts are applied "after" the line item discounts, since they are already included in the $.lineItems[*].grossTotal field.

Example

Imagine a 10% discount on the entire sale. If one carton of organic milk costing €1.69 is bought, the sale would look like tis. The discounted price have to be reflected in totals.grossAmount as well as totals.taxAmount and totals.netAmount fields of the sale.

{
  "lineItems": [
    {
      "lineItemId": "1",
      "name": "Organic milk",
      "articleId": "934392",
      "quantity": {
        "quantity": "10",
        "unit": "pieces"
      },
      "gtin": {
        "format": "GTIN-13",
        "content": "1234567890123"
      },
      "baseGrossUnitPrice": {
        "currency": "EUR",
        "amount": "1.69"
      },
      "grossUnitPrice": {
        "currency": "EUR",
        "amount": "1.69"
      },
      "baseGrossTotal": {
        "currency": "EUR",
        "amount": "1.69"
      },
      "grossTotal": {
        "currency": "EUR",
        "amount": "1.69"
      },
      "totalTax": {
        "currency": "EUR",
        "amount": "0.15"
      },
      "netTotal": {
        "currency": "EUR",
        "amount": "1.54"
      },
      "taxes": [
        {
          "taxType": "VAT",
          "percentage": "10",
          "grossAmount": {
            "currency": "EUR",
            "amount": "1.69"
          },
          "taxAmount": {
            "currency": "EUR",
            "amount": "0.15"
          },
          "netAmount": {
            "currency": "EUR",
            "amount": "1.54"
          }
        }
      ]
    }
  ],
  "discounts": [
    {
      "totalGrossAmount": {
        "currency": "EUR",
        "amount": "0.17"
      },
      "percentage": "10",
      "description": {
        "contentType": "text/markdown",
        "content": "**-10% on the entire sale**"
      },
      "discountCode": "123456"
    }
  ],
  "totals": {
    "grossAmount": {
      "currency": "EUR",
      "amount": "1.52"
    },
    "taxAmount": {
      "currency": "EUR",
      "amount": "0.14"
    },
    "netAmount": {
      "currency": "EUR",
      "amount": "1.38"
    }
  }
}