Billing Overview
The billing module provides a comprehensive system for managing sales, payments, products, and taxes. It serves as the core financial engine for transactions within the platform.
Core Concepts
Sales: The main transactional entity representing a purchase. Sales contain one or more products, applicable taxes, discounts, and pricing information. Sales progress through different statuses from draft to paid or canceled.
Products: Items or services that can be sold. Products can be organized into families and subfamilies for categorization. Each product can have associated taxes and tags.
Payments: Records of money transactions. A single sale can be paid using multiple payment methods (split payments). Payments can be refunded if needed.
Payment Methods: Various ways to receive payment including cash, card, bank transfer, direct debit, online gateways, deposits, and vouchers.
Main Database Tables
Core Sales Flow
Customer
│
▼
┌───────────┐ ┌─────────────┐ ┌─────────────┐
│ Sale │────▶│ Product │────▶│ Subfamily │
└─────┬─────┘ └─────────────┘ └─────────────┘
│ │
│ ▼
│ ┌─────────────┐
│ │ Family │
│ └─────────────┘
│
▼
┌─────────────┐ ┌─────────────┐ ┌─────────────┐
│ SalePayment │◄──▶│ Payment │───▶│PaymentMethod│
└─────────────┘ └─────────────┘ └─────────────┘
Product Organization
┌─────────────┐
│ Family │
└──────┬──────┘
│ 1:n
▼
┌─────────────┐
│ Subfamily │ (optional, nullable)
└──────┬──────┘
│ 1:n
▼
┌─────────────┐ ┌───────────────┐ ┌─────────────┐
│ Product │◄──▶│ ProductToTag │◄──▶│ ProductTag │
└──────┬──────┘ └───────────────┘ └─────────────┘
│
│ n:m
▼
┌───────────────┐ ┌─────────────┐
│ ProductToTax │◄──▶│ Tax │
└───────────────┘ └─────────────┘
Tax Application
┌─────────────┐ ┌───────────────┐ ┌─────────────┐
│ Product │◄──▶│ ProductToTax │◄──▶│ Tax │ (default taxes)
└──────┬──────┘ └───────────────┘ └──────┬──────┘
│ │
│ │ (copied when sale created)
▼ ▼
┌─────────────┐ ┌─────────────┐ ┌─────────────┐
│ Sale │───▶│ SaleTax │◄──▶│ Tax │ (actual applied taxes)
└──────┬──────┘ └─────────────┘ └─────────────┘
│
▼
┌─────────────┐
│ Customer │ (tax exempt?)
└─────────────┘
Core Entities
- sale: Primary transaction record with status, totals, customer, and product information
- payment: Individual payment records
- salePayment: Links sales to payments (many-to-many relationship)
- product: Catalog of sellable items/services
- paymentMethod: Available payment methods configuration
Product Organization
- family: Top-level product categories
- subfamily: Second-level product categories (optional)
- productTag: Product labeling system
- productToTag: Links products to tags
Tax System
- tax: Tax definitions (rates, names, types)
- saleTax: Tax calculations applied to specific sales
- productToTax: Default taxes associated with products
Supporting Tables
- company: Company information for B2B sales and supply sales
- discountReasons: Predefined reasons for applying discounts
Sale Lifecycle
- Draft (0): Sale is being created/edited
- No Cost (1): Sale has no cost (free items)
- Pending (2): Sale awaits payment
- Paid (3): Sale is fully paid
- Canceled (4): Original sale marked as canceled (historical record preserved)
- Cancelation (5): Compensating sale with negative amounts to zero out the original sale
Important: When canceling a sale, the system preserves the original sale (status → Canceled) and creates a new compensating sale (status = Cancelation) with opposite amounts. This maintains accurate historical records while ensuring totals balance to zero.
Cancellation Process
Original Sale (ID: 1001) After Cancellation:
┌─────────────────────┐ ┌─────────────────────┐
│ Status: PAID │ │ Status: CANCELED │
│ Amount: €100 │ ──▶ │ Amount: €100 │ (preserved)
│ Tax: €21 │ │ Tax: €21 │
└─────────────────────┘ └─────────────────────┘
+
┌─────────────────────┐
│ Status: CANCELATION │
│ Amount: -€100 │ (new compensating sale)
│ Tax: -€21 │
│ Parent: 1001 │
└─────────────────────┘
Total Impact: €0
Key Features
Multi-Payment Support: Sales can be paid using multiple payment methods simultaneously.
Tax Management: Flexible tax system supporting multiple taxes per product, tax-exempt customers, and automatic tax calculations.
Split Sales: Large sales can be split into smaller transactions or by payment amounts.
Hierarchical Sales: Support for parent-child sale relationships with cascading operations.
Online Payments: Integration with payment gateways for web-based transactions via payment links.
Refunds: Full support for payment refunds and sale cancellations.
Automation: Automatic sale timeout and cancellation via scheduled jobs.
Business Rules
- Products can optionally belong to a subfamily, which belongs to a family
- Tax calculations are automatic based on product configuration and customer tax exemption status
- Paid sales cannot be modified
- Virtual payment methods (vouchers, deposits) don’t involve actual money transfer
- Supply sales (suplidos) cannot have taxes applied - they represent pass-through expenses to companies
- All monetary calculations include rounding error detection
API Integration
The billing module exposes RESTful APIs for: - Creating and updating sales - Processing payments - Managing refunds and cancellations - Generating payment links for online checkout - Retrieving customer transaction history
This system provides the foundation for any business requiring robust transaction processing with flexible payment options and comprehensive financial reporting capabilities.