> ## Documentation Index
> Fetch the complete documentation index at: https://docs.procuros.io/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

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.

<CodeGroup>
  ```json json theme={null}
  {
    "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"
              }
            }
          ]
        }
      ]
    }
  }
  ```
</CodeGroup>

### Multiple modifications on item- and document-level

A more complex scenario with one modification on item-level and two modifications on document-level.

<CodeGroup>
  ```json json theme={null}
  {
    "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"
            }
          ]
        }
      ]
    }
  }
  ```
</CodeGroup>

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