Invoice Modifications

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

Per line item, one or more modifications can be added
Per invoice, one or more modifications can be added
No modification group should have the same level attribute, unless they are on different items or on the document
It is only necessary to send taxes on modifications for absolute charges
An invoice or credit note can leave out items or send an empty items array, e.g. when it only has document-level charges. Some receivers can still require at least one line item.

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€.

Getting Started

Endpoints

Documents

Guides

Other

Invoice Modifications

Rules

Examples

Single charge on document-level

Multiple modifications on item- and document-level

​Rules

​Examples

​Single charge on document-level

​Multiple modifications on item- and document-level

Rules

Examples

Single charge on document-level

Multiple modifications on item- and document-level