Invoice modifications can be used to add additional charges or allowances (discounts) to line items or entire documents. For example, you might want to add a handling fee for large items or provide a volume discount for large orders. Modifications can be either absolute (e.g. 5€ handling fee) or relative (e.g. 10% volume discount). Individual modifications are organised in modification groups. Each modification group must have a level which determines which modification group is applied first. Furthermore, modification groups contain a basis attribute. The basis is used to calculate absolute values for relative modifications, e.g. a relative modification of 10% on a basis of 500€ would result in a 50€ modification. Modifications on item-level are applied to the subtotal (quantity * unitPrice) of the item. Document-level modifications are on the other hand applied to the subtotalAmount of the invoice.

​
Rules

  1. Per line item, one or more modifications can be added
  2. Per invoice, one or more modifications can be added
  3. No modification group should have the same level attribute, unless they are on different items or on the document
  4. It is only necessary to send taxes on modifications for absolute charges
Generally for all modifications (discounts or surcharges): Relative (%) does not need tax info (will be distributed equally to all line-items). Example: cash discount, EZHG, partner portal, logistics discount, etc. Absolute (€) needs for:
  • Discounts: no tax info (will be distributed evenly on all line-items). Example: Credit, Coupon, etc.
  • Surcharge: needs tax info (because comparable to an independent line-item). Example: shipping costs, minimum quantity surcharge, packaging surcharge, etc.

​
Examples

​
Single charge on document-level

An invoice with an additional 5€ (net) shipping charge on document-level. 
{
  "header": {...},
  "items": [...],
  "summary": {
    "subtotalAmount": 100,
    "totalCharges": 5,
    "totalAllowances": 0,
    "netAmount": 105,
    "grossAmount": 124.95,
    "dueAmount": 124.95,
    "tax": {...},
    "modificationGroups": [
      {
        "level": 1,
        "basis": 100,
        "modifications": [
          {
            "type": "CHARGE",
            "reasonCode": "SHIPPING",
            "amount": 5,
            "tax": {
              "amount": 0.95,
              "percentage": 19,
              "description": "Umsatzsteuer"
            }
          }
        ]
      }
    ]
  }
}

​
Multiple modifications on item- and document-level

A more complex scenario with one modification on item-level and two modifications on document-level. 
{
  "header": {...},
  "items": [
    {
      "lineNumber": 1,
      "identifiers": [...],
      "isDepositItem": false,
      "isInvoicedItem": false,
      "quantity": 5,
      "unitOfMeasure": "EA",
      "description": "Large Item",
      "unitPrice": 1000,
      "tax": {
        "amount": 190,
        "percentage": 19,
        "description": "Umsatzsteuer"
      },
      "modificationGroups": [
        {
          "level": 1,
          "basis": 5000,
          "modifications": [
            {
              "type": "ALLOWANCE",
              "reasonCode": "DISCOUNT",
              "amount": 500
            }
          ]
        }
      ]
    }
  ],
  "summary": {
    "subtotalAmount": 4500,
    "totalCharges": 50,
    "totalAllowances": 455,
    "netAmount": 4095,
    "grossAmount": 4873.05,
    "dueAmount": 4873.05,
    "tax": {...},
    "modificationGroups": [
      {
        "level": 1,
        "basis": 4500,
        "modifications": [
          {
            "type": "CHARGE",
            "reasonCode": "SHIPPING",
            "amount": 50,
            "tax": {
                "amount": 9.5,
                "percentage": 19,
                "description": "Umsatzsteuer"
            }
          }
        ]
      },
      {
        "level": 2,
        "basis": 4550,
        "modifications": [
          {
            "type": "ALLOWANCE",
            "reasonCode": "DISCOUNT",
            "percentage": 10,
            "description": "Loyal Customer Discount"
          }
        ]
      }
    ]
  }
}
Explanation: First, the modifications on item-level are applied. Since item-level modifications are applied to the subtotal (quantity * unitPrice) of the item, the subtotalAmount of the invoice is 4.500€. Next, the document-level modifications are applied. For the modification with level = 1, we apply the charge to the subtotalAmount of the invoice. Thus, the subtotal (without taxes) is 4.500€+50€ after applying the first modification. Finally, we apply the second modification (level = 2) to the new subtotal and end up with an invoice netAmount of 4.095€.