​
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: 
{
  "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

FieldDescription
subscriptionAmountOriginal total including VAT
discountAmountCalculated based on discount code
taxAmountTotal VAT applied
totalAmountFinal amount user needs to pay
lines[n].amountFinal amount of each item after discounts
lines[n].originAmountAmount before discount
lines[n].taxPercentageRepresented 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: 
{
  "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