Calculations

Quick links

• Creating and Updating Invoices
• Disable Invoice Calculations
• How Calculations are Performed
• An Example of Invoice Calculations
• Getting a Summary

1. Creating and Updating Invoices

When creating a new invoice you can specify its lines. Each line of the invoice can be associated with one product (it's not compulsory though). A product is equivalent with an item type and is usually configured before starting to produce invoices. Part of the product configuration is considered to be the tax definitions related to the item that will be later on associated at the invoice line level.

When specifying a new product inside a line, this is also created in the database along with its relevant information. The created product can inherit data from the line like the name, taxes and amount. If the product already exists then it is not created again. The only requirement to identify an existing product is to provide its existing id (like the first line in the example below). If an existing product contains different information than the one that resides in the database, then it is not updated.

Let's see an actual payload of an invoice create request (The update request is quite similar but omitted for brevity):

{
  "date": "2017-10-04T19:02:36+03:00",
  "lines": [
    {
      "description": "Software development services",
      "product": {
        "id": "cfac9001-bf66-4d0a-95e0-2f64fe70432b"
      },
      "quantity": 1,
      "taxes": [
        { "isSalesTax": true, "name": "ΦΠΑ", "rate": 0.24 },
        { "inclusive": true, "name": "ΕΦΚΑ", "rate": -0.0922 },
        { "inclusive": true, "name": "ΦΟΡ. ΠΑΡΑΚ.", "rate": -0.2 }
      ],
      "taxesDescription": "ΦΠΑ (24%), ΕΦΚΑ (-9.22%), ΦΟΡ. ΠΑΡΑΚ. (-20%)",
      "unitAmount": 1000
    },
    {
      "description": "Software support services",
      "product": {
        "amount": 10,
        "id": "f610c39f-cd48-4190-a808-7cfdbf22608d",
        "name": "Software support services",
        "taxes": [
          { "isSalesTax": true, "name": "ΦΠΑ", "rate": 0.24 },
          { "inclusive": true, "name": "ΕΦΚΑ", "rate": -0.0922 },
          { "inclusive": true, "name": "ΦΟΡ. ΠΑΡΑΚ.", "rate": -0.2 }
        ]
      },
      "quantity": 1,
      "taxes": [
        { "isSalesTax": true, "name": "ΦΠΑ", "rate": 0.24 },
        { "inclusive": true, "name": "ΕΦΚΑ", "rate": -0.0922 },
        { "inclusive": true, "name": "ΦΟΡ. ΠΑΡΑΚ.", "rate": -0.2 }
      ],
      "taxesDescription": "ΦΠΑ (24%), ΕΦΚΑ (-9.22%), ΦΟΡ. ΠΑΡΑΚ. (-20%)",
      "unitAmount": 600
    },
    {
      "description": "Design services",
      "discountRate": 0.05,
      "quantity": 4,
      "taxes": [
        { "isSalesTax": true, "name": "ΦΠΑ", "rate": 0.24 },
        { "inclusive": true, "name": "ΕΦΚΑ", "rate": -0.0922 },
        { "inclusive": true, "name": "ΦΟΡ. ΠΑΡΑΚ.", "rate": -0.2 }
      ],
      "taxesDescription": "ΦΠΑ (24%), ΕΦΚΑ (-9.22%), ΦΟΡ. ΠΑΡΑΚ. (-20%)",
      "unitAmount": 350
    }
  ],
  "recipient": {
    /* recipient information omitted for brevity */
  },
  "serverCalculations": true,
  "status": "Draft"
}

During updating you have the ability to disassociate lines from a particular invoice. However, this will not delete any products. Moreover, as with creating invoices, edited products are not updated. So the only way to update a product is from the corresponding endpoints of the API.

2. Disable Invoice Calculations

When creating a new invoice, the API has the ability to perform calculations on the server for its totals. This behaviour is enabled by default, but a user can disable it by setting the serverCalculations property to false. This property is included in the JSON object that is posted during the new invoice creation.

3. How Calculations are Performed

Mandatory values

An invoice can have one or more lines. When calculations are performed on the server the invoice payload must at minimum provide the amount, the quantity (defaults to 1 if not specified otherwise), the discount (rate that defaults to zero) at the line level as well as inclucive (defaults to false), isSalesTax (defaults to false), rate, type (defaults to unitrate) at the tax level.

This is what a Tax payload looks like:

{ "isSalesTax": true, "inclusive": false, "name": "VAT", "rate": 0.24, "type": "UnitRate" }

A tax can be distinguished through the TaxType enumeration. This has three possible values:

• UnitRate: the amount of this type of tax is calculated by multiplying the tax's rate with the sub total. This is the default type.
• FixedRate: the amount of this type of tax is calculated by multiplying the tax's rate with the quantity.
• Fixed: the amount of this type of tax is equal to the tax's rate.

A Tax is marked as inclusive when the amount of the line already contains the taxes. You may also notice that some taxes may have a negative sign. These taxes are subtracted from the total payable.

The math

As a result the following 4 main values are calculated:

1. sub total: The sub total is calculated by multiplying the unit amount of the product with the quantity. If a discount rate is defined, then it is also calculated and subtracted from the initial value.
2. total tax: Total tax is the summary of the taxes that are included in a line or product. A product/line can have one or more taxes.
3. total sales tax: Total sales tax is the summary of the taxes of a product that are marked as sales tax.
4. total: Total is found by adding the total sales tax to the sub total.

The above four values are also calculated for the invoice as a whole. Each of these values is the summary of the equivalent value in the lines. For instance, the sub total of the invoice is the summary of all sub totals of the lines.

Invoice has a fifth value that is calculated, which is total payable. Total payable is equal to the total if there are no inclusive taxes. In case there are, they are added to the total payable.

4. An Example of Invoice Calculations

The invoice has 3 lines. Let's do the calculations for each one and also for the invoice.

• Line 1:
  • sub total = 1000 unit amount × 1 quantity = 1000
  • total tax = tax1 + tax2 + tax3 = 240 - 92.2 - 200 = -52.2
    • tax1 = 1000 sub total × 0.24 rate = 240`
    • tax2 = 1000 sub total × -0.0922 rate = -92.2 inclusive tax
    • tax3 = 1000 sub total × -0.2 rate = -200 inclusive tax
  • total sales tax = tax1 (which is sales tax) = 240
  • total = 1000 sub total + 240 total sales tax = 1240
• Line 2:
  • sub total = 600 unit amount × 1 quantity = 600
  • total tax = tax1 + tax2 + tax3 = 144 - 55.32 - 120 = -31.32
    • tax1 = 600 sub total × 0.24 rate = 144
    • tax2 = 600 sub total × -0.0922 rate = -55.32 inclusive tax
    • tax3 = 600 sub total × -0.2 rate = -120 inclusive tax
  • total sales tax = tax1 (which is sales tax) = 144
  • total = 600 sub total + 144 total sales tax = 744
• Line 3:
  • sub total = 350 unit amount × 4 quantity = 1400 - (1400 * 0.05 discount rate) = 1400 - 70 = 1330
  • total tax = tax1 + tax2 + tax3 = 319.2 - 122.626 - 266 = -69.426
    • tax1 = 1330 sub total × 0.24 rate = 319.2
    • tax2 = 1330 sub total × -0.0922 rate = -122.626 inclusive tax
    • tax3 = 1330 sub total × -0.2 rate = -266 inclusive tax
  • total sales tax = tax1 (which is sales tax) = 319.2
  • total = 1330 sub total + 319.2 total sales tax = 1649.2
• Invoice:
  • sub total = 1000 + 600 + 1330 = 2930
  • total tax = -52.2 - 31.32 - 69.426 = -152.946
  • total sales tax = 240 + 144 + 319.2 = 703.2
  • total = 1240 + 744 + 1649.2 = 3633.2
  • total payable = 3633.2 - 856.145 sum of all inclusive taxes = 2777.055

5. Getting a Summary

When retrieving the list of invoices for a given subscription there is the option to display a summary of the totals for all the invoices. To enable this feature you need to append summary=true to the query string (https://api.incontrl.io/subscriptions/{subscription-id}/invoices?summary=true) along with any other desired option. You will receive a response as shown in the example below.

{
  "summary": {
    "currencyCode": "EUR",
    "total": 14832.501,
    "subTotal": 13215.3414,
    "totalOtherTax": 1617.1596
  },
  "count": 366,
  "items": [
    /* invoice objects omitted for brevity */
  ]
}