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

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:

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

Start Here

Core Concepts

Guides

Reference

Migration and Deployment

Invoice computation

Subscription Invoice Computation

Invoice Overview

Sample Summary

Data Structure

Formula Reference

Item-Level Calculations

Invoice-Level Aggregations

Fields Summary

Notes

Proration Explanation

When Proration Applies

How Proration Is Calculated

Example

Line Item Display Format in Invoice PDF

Invoice Summary Format in PDF

​Subscription Invoice Computation

​Invoice Overview

​Sample Summary

​Data Structure

​Formula Reference

​Item-Level Calculations

​Invoice-Level Aggregations

​Fields Summary

​Notes

​Proration Explanation

​When Proration Applies

​How Proration Is Calculated

​Example

​Line Item Display Format in Invoice PDF

​Invoice Summary Format in PDF

Subscription Invoice Computation

Invoice Overview

Sample Summary

Data Structure

Formula Reference

Item-Level Calculations

Invoice-Level Aggregations

Fields Summary

Notes

Proration Explanation

When Proration Applies

How Proration Is Calculated

Example

Line Item Display Format in Invoice PDF

Invoice Summary Format in PDF