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

# Invoice computation

# Subscription Invoice Computation

This document explains how UniBee generates subscription invoices, including data structure, key fields, and computation logic.

## Invoice Overview

A subscription invoice is composed of the following components:

* **Subtotal**: The original subscription amount before discounts and tax.
* **Discount**: Calculated based on the applied discount code.
* **VAT**: Computed using the applicable tax percentage.
* **Total**: The final payable amount after discount and VAT.

### Sample Summary

```
SUBTOTAL:                € 29.00  
TOTAL DISCOUNTED:        € -14.50 (code: Ex006)  
VAT (5.0%):              € 0.72  
TOTAL:                   € 15.22  
```

## Data Structure

Each invoice includes a list of `lines`, representing items billed for the subscription. A typical `line` item contains:

```json theme={null}
{
  "unitAmountExcludingTax": 2900,
  "quantity": 1,
  "amountExcludingTax": 2900,
  "tax": 72,
  "originAmount": 2972,
  "discountAmount": 1450,
  "amount": 1522,
  "taxPercentage": 500,
  "pdfDescription": "1 * Starter Monthly (2024-11-06 - 2024-12-06)"
}
```

## Formula Reference

### Item-Level Calculations

Each `line` item in the invoice follows these computation rules:

```
item.unitAmountExcludingTax = Plan or Add-on amount  
item.amountExcludingTax = item.unitAmountExcludingTax × item.quantity  
item.tax = item.amountExcludingTax × (item.taxPercentage / 10000)  
item.originAmount = item.amountExcludingTax + item.tax  
item.amount = item.originAmount - item.discountAmount  
```

> ⚠️ Note: `item.amount` does not necessarily equal `amountExcludingTax + tax`\
> because `discountAmount` is computed **externally** and distributed back into the items (e.g., for proration or code-level discounting).

### Invoice-Level Aggregations

Outside the items, the system computes total values using the following logic:

```
subscriptionAmountExcludingTax = sum of all item.amountExcludingTax  

discountAmount =
  if discount type = percentage:
    subscriptionAmountExcludingTax × discountPercentage  
  if discount type = fixed:
    min(fixedAmount, subscriptionAmountExcludingTax)  

totalAmountExcludingTax = subscriptionAmountExcludingTax - discountAmount  

taxAmount = totalAmountExcludingTax × (taxPercentage / 10000)  

totalAmount = totalAmountExcludingTax + taxAmount  

subscriptionAmount = subscriptionAmountExcludingTax + taxAmount  

originAmount ≈ subscriptionAmount  
```

## Fields Summary

| Field                    | Description                                  |
| ------------------------ | -------------------------------------------- |
| `subscriptionAmount`     | Original total including VAT                 |
| `discountAmount`         | Calculated based on discount code            |
| `taxAmount`              | Total VAT applied                            |
| `totalAmount`            | Final amount user needs to pay               |
| `lines[n].amount`        | Final amount of each item after discounts    |
| `lines[n].originAmount`  | Amount before discount                       |
| `lines[n].taxPercentage` | Represented in basis points (e.g., 500 = 5%) |

***

## Notes

* VAT is computed at invoice level based on total taxable amount **after** discounts.
* Proration logic may adjust `discountAmount` and reflect it across individual items.
* All amounts are stored in **minor units** (e.g., cents), and formatted into standard currencies when rendering the PDF.

## Proration Explanation

Proration occurs when a customer upgrades, downgrades, starts, or cancels a subscription in the middle of a billing cycle. UniBee calculates prorated amounts to ensure fair billing based on the actual usage time.

### When Proration Applies

* Plan changes within a billing cycle
* Early cancellations
* Mid-cycle sign-ups

### How Proration Is Calculated

UniBee uses a time-based proration model:

```
proratedAmount = (planAmount / totalPeriodDurationInSeconds) × actualUsageDurationInSeconds
```

* `planAmount`: the full amount of the plan
* `totalPeriodDurationInSeconds`: full length of the billing cycle in seconds
* `actualUsageDurationInSeconds`: the portion of time the plan was used

### Example

If a €30/month plan is canceled halfway through the month (15/30 days), the prorated charge would be:

```
€30 × (15 / 30) = €15
```

This prorated amount may also be subject to discounts and tax, following the standard formula logic.

> 💡 Prorated discounts (if any) are calculated externally and applied to the `discountAmount` field at the invoice or item level.

## Line Item Display Format in Invoice PDF

Each invoice line item is rendered in the PDF with the following format:

```
Description                                      Unit Price     Quantity     VAT     Total
1 × Starter Monthly (2024-11-06 to 2024-12-06)   €29.00         1            €0.72   €29.72
```

This format is derived from the following data structure:

```json theme={null}
{
  "description": "1 × Starter Monthly (2024-11-06 - 2024-12-06)",
  "unitAmountExcludingTax": 2900,
  "quantity": 1,
  "taxPercentage": 500,
  "tax": 72,
  "originAmount": 2972
}
```

Where:

* **Description** comes from `pdfDescription`
* **Unit Price** is `unitAmountExcludingTax` (converted from cents)
* **Quantity** is `quantity`
* **VAT** is `tax`
* **Total** is `originAmount` (before discounts)

> 💡 Note: The discounted amount is shown in the invoice summary, not in this table.

## Invoice Summary Format in PDF

The bottom section of the invoice PDF summarizes the overall charges:

```
SUBTOTAL                         € 29.00  
TOTAL DISCOUNTED (code: Ex006)  € -14.50  
VAT (5.0%)                       € 0.72 | AED 2.88  
TOTAL                            € 15.22  
```

This section is computed using the invoice-level fields:

* `subscriptionAmountExcludingTax`
* `discountAmount`
* `taxAmount`
* `totalAmount`