Invoice *

Invoicing

The Invoicing module allows your system to generate, manage, and track invoices for user purchases and subscription renewals. It integrates with payment gateways to automatically update invoice statuses and complete transactions.

---

How Invoices Work

Invoices in the system follow two main workflows: user-initiated purchases and scheduled renewal invoices.

1. User-Initiated Purchase

1. Select Package

   • The user selects a package and clicks Upgrade Now on the website.

2. Invoice Generation

   • The system generates a new invoice with status Unpaid.

   • This invoice represents the order the user is about to pay and includes package details, line items, and billing information.

3. Payment Gateway

   • The user completes payment through the integrated payment gateway.

   • The invoice remains Unpaid until the payment is confirmed.

4. Webhook & Payment Confirmation

   • The payment gateway sends a webhook notification after a successful payment.

   • The server updates the invoice:

     • Status = Paid

     • AmountPaid = TotalAmount

     • AmountDue = 0

5. Transaction Completed

   • Access to the purchased package is granted.

   • Confirmation emails or receipts may be sent.

---

2. Scheduled Renewal / Expired Package

1. Package Expiry Detection

   • The system checks subscriptions daily for expired packages.

2. Invoice Generation

   • For packages expired 1 day ago, a new invoice is automatically created.

   • Default status is Unpaid.

   • Includes relevant line items for the renewed subscription.

   • A Due Date of 7 days from the invoice creation date is automatically assigned.

3. Waiting for Payment

   • The invoice remains Unpaid until the user completes payment.

   • Payment confirmation via webhook updates the invoice to Paid and completes the transaction.

---

Workflow Diagram

User-Initiated Purchase:
User selects package
         |
         v
   Generate Invoice (Unpaid)
         |
         v
  Redirect to Payment Gateway
         |
         v
Payment Success? --> No --> Invoice stays Unpaid
         |
        Yes
         v
Receive Webhook from Payment Gateway
         |
         v
Update Invoice: Status = Paid, AmountPaid = TotalAmount
         |
         v
Complete Transaction (Grant access / Send receipt)

Scheduled Renewal:
Package Expired (1 day ago)
         |
         v
   Generate Invoice (Unpaid)
         |
         v
Waiting for User Payment
         |
         v
Receive Webhook from Payment Gateway
         |
         v
Update Invoice: Status = Paid, AmountPaid = TotalAmount
         |
         v
Complete Transaction (Renew subscription / Grant access)

---

Invoice Object

The Invoice entity stores all billing information and tracks payments.

Properties

Property	Type	Description
Type	short?	Invoice type (e.g., Standard, Credit Note). Optional.
Code	string	Unique invoice code or reference.
Name	string	Name or title of the invoice.
SubtotalAmount	decimal	Amount before discounts and taxes.
DiscountRate	decimal?	Optional discount percentage.
DiscountAmount	decimal?	Optional fixed discount amount.
TaxRate	decimal?	Optional tax percentage.
TaxAmount	decimal?	Calculated tax amount. Optional.
TotalAmount	decimal	Total amount after discount and tax.
AmountPaid	decimal	Amount already paid.
AmountDue	decimal	Remaining amount to be paid.
CurrencyCode	string	ISO currency code (e.g., USD, EUR).
Description	string	Optional detailed description.
Notes	string	Internal notes or additional info.
Tags	string	Comma-separated tags. Optional.
ReminderedCount	int?	Number of payment reminders sent. Optional.
DeliveryInstructions	string	Optional delivery instructions.
ConfirmedDeliveryDate	DateTime?	Optional date when delivery confirmed.
InvoiceDate	DateTime?	Invoice issue date. Optional.
DueDate	DateTime?	Payment due date. Optional.
OverdueDate	DateTime?	Date when invoice is overdue. Optional.
BillingPeriodStartDate	DateTime?	Start of billing period. Optional.
BillingPeriodEndDate	DateTime?	End of billing period. Optional.
TestMode	bool?	Indicates sandbox/test invoice. Optional.
Status	short?	Invoice status (Unpaid, Paid, Partial, Overdue, Canceled). See below.

Invoice Item Object

The Invoice Item entity represents individual line items in an invoice.

Properties

Property	Type	Description
Name	string	Name or description of the line item.
Quantity	int	Quantity of the item.
Amount	decimal	Total amount for this line item.
CurrencyCode	string	ISO currency code (should match parent invoice).

Relationships

• Invoice → InvoiceItem: One-to-Many

• Subtotal, total, and due amounts are calculated based on invoice items, discounts, and taxes.

SubtotalAmount = SUM(InvoiceItem.Amount)
TotalAmount = SubtotalAmount - DiscountAmount + TaxAmount
AmountDue = TotalAmount - AmountPaid