​

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

​

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