4. Sales Module

The Sales Module manages the complete revenue cycle in NkapBooks — from generating a quote for a prospect to collecting payment and tracking customer loyalty. It is accessible from the Sales section in the sidebar and contains the following sub-modules:

4.1 Sales Quotes

Sales Quotes (also called Quotations) allow you to prepare a formal pricing proposal for a customer or lead before creating an invoice. They follow the same structure as invoices but do not generate accounting ledger entries.

Schema Overview

Quote Lifecycle

Draft  →  Submitted  →  Converted to Invoice
                    →  Cancelled

1. Draft — The quote is created and can be freely edited. Items, rates, taxes, and discounts can be modified.
2. Submitted — The quote is finalized. No further edits are allowed. The quote can now be converted to a Sales Invoice.
3. Converted — When the "Sales Invoice" action is triggered, a new Sales Invoice is created with all items, rates, and terms copied from the quote. The invoice's quote field links back to the original quote.
4. Cancelled — A submitted quote can be cancelled if it is no longer needed.

Key Features

• One-Click Conversion — Use the Create → Sales Invoice action to convert a submitted quote into a Sales Invoice. All line items, quantities, rates, taxes, and terms are carried over.
• Multi-Currency — If the customer has a different default currency, the exchange rate is automatically fetched and applied to all amounts.
• Tax Templates — Taxes are calculated automatically based on the tax template assigned to each item.
• Print / PDF Export — Generate professional PDF quotes using your configured print templates.
• Custom Number Series — Configure the prefix and starting number for quotes (e.g., SQUOT-, QT-, EST-).

Actions

4.2 Sales Invoices

Sales Invoices are the core revenue document in NkapBooks. They record the sale of goods or services to a customer and automatically generate double-entry accounting ledger entries upon submission.

Schema Overview

Invoice-Level Settings (Settings Tab)

Invoice Lifecycle

Draft  →  Submitted  →  Paid
                    →  Partly Paid
                    →  Cancelled
                    →  Return / Return Issued

Status Definitions:

What Happens on Submit

When you submit a Sales Invoice, the following accounting ledger entries are automatically generated:

1. Debit the Receivable Account (e.g., Debtors) with the Grand Total
2. Credit each item's Income Account (e.g., Sales, Service) with the item amount
3. Credit each Tax Account with the respective tax amount
4. Debit the Discount Account (if a discount is applied and a discount account is configured)
5. A round-off entry is made if the total doesn't balance exactly due to rounding

For multi-currency invoices, all amounts are converted to the base currency using the exchange rate before posting.

If Loyalty Program is active and points are being redeemed:

• Debit the Loyalty Program Expense Account
• Credit the Receivable Account with the loyalty amount

Key Features

• Automatic Tax Calculation — Taxes are computed per item based on assigned tax templates. The tax summary table shows a breakdown by tax account with rates and amounts.
• Discount Support — Both item-level and invoice-level discounts are supported. You can set discounts as a percentage or fixed amount. The discountAfterTax setting controls whether discounts apply before or after tax.
• Multi-Currency — When a customer's default currency differs from your company currency, the invoice automatically applies the exchange rate. The baseGrandTotal shows the converted amount.
• Linked Payments — Payments made against an invoice are tracked. The outstanding amount is automatically recalculated when payments are created, submitted, or cancelled.
• Auto-Payment — Enable "Make Payment On Submit" to automatically create and submit a payment entry when the invoice is submitted. The payment account is taken from Settings → Defaults → Sales Payment Account.
• Auto-Shipment — Enable "Make Shipment On Submit" to automatically create and submit a Shipment document for all tracked items. The location is taken from Settings → Defaults → Shipment Location.
• Pricing Rules — Automatic discounts are applied based on configured pricing rules. The isPricingRuleApplied flag and pricingRuleDetail table track which rules were applied.
• Coupon Codes — Apply coupon codes to trigger coupon-based pricing rules. Coupons are validated for date range, amount range, and maximum usage.
• Price Lists — Select a price list to automatically look up per-item rates. The price list must be marked as "For Sales" and "Enabled".
• Returns / Credit Notes — Create a return against any submitted invoice using the Create → Return action. The return invoice reverses the ledger entries and updates the original invoice's isReturned status. Partial returns are supported based on remaining quantity.
• POS Integration — Invoices created through the Point of Sale module are automatically linked to the active POS session via the isPOS and posSession fields.
• License Check — For non-return invoices, NkapBooks validates against your license tier's invoice limits before allowing creation. If the limit is reached, you'll be prompted to upgrade.
• Custom Print Templates — Use the Template Builder to design custom invoice layouts with your logo, terms, and styling.

Actions

Line Item Fields (SalesInvoiceItem)

Each line item in a Sales Invoice supports the following fields:

4.3 Sales Payments

Sales Payments record money received from customers. In NkapBooks, payments are managed through the unified Payment document with paymentType: "Receive".

Schema Overview

Payment Lifecycle

Draft  →  Submitted  →  (auto-updates invoice outstanding)
                    →  Cancelled  →  (reverts invoice outstanding)

Accounting Entries

When a sales payment is submitted, the following ledger entries are created:

If a Write Off amount is specified:

• An additional entry debits the Write Off Account and credits the Receivable Account for the write-off amount.

Key Features

• Multi-Invoice Payments — A single payment can be applied against multiple invoices using the Payment Reference table. Each reference row specifies the invoice and amount.
• Partial Payments — Pay any amount less than the outstanding balance. The invoice's outstanding amount is automatically recalculated.
• Write-Off — Write off small remaining balances (e.g., rounding differences). Requires a configured Write Off Account.
• Payment Methods — Create custom payment methods (Cash, Bank Transfer, Cheque, Mobile Money, etc.) from Settings → Payment Methods. Each method can have a default account.
• Auto-Update Outstanding — When a payment is submitted, the linked invoice's outstandingAmount is recalculated based on all linked payments. When cancelled, the outstanding is reverted.
• Party Outstanding — After each payment, the customer's overall outstanding amount is recalculated across all their invoices.
• Quick Payment — From any submitted Sales Invoice, use the Create → Payment action to open a pre-filled payment quick-edit form. The payment is automatically linked to the invoice.
• Validation — The system validates that:
  • The payment amount doesn't exceed the invoice's outstanding amount
  • The from/to accounts are appropriate for the payment type
  • Reference invoices are submitted and not cancelled
  • Total reference amounts match the payment amount (plus any write-off)

4.4 Customer Management

In NkapBooks, customers are managed as Party records with role: "Customer" (or role: "Both" for parties that are both customers and suppliers).

Schema Overview

Default Account Logic

The default account is automatically determined based on:

1. SYSCOHADA Countries (Benin, Burkina Faso, Cameroon, etc.) — Uses French accounting terminology:
   • Customers: 411-Clients, 4111-Clients, or 41-Clients et comptes rattachés
   • Suppliers: 401-Fournisseurs, Dettes en Compte, 4011-Fournisseurs, or 40-Fournisseurs et comptes rattachés
2. Other Countries — Uses English account names:
   • Customers: Debtors
   • Suppliers: Creditors

Outstanding Amount Calculation

The outstanding amount is calculated by summing the outstandingAmount field across all submitted, non-cancelled invoices for the customer:

• Customer role: Sum of outstanding Sales Invoices
• Both role: Outstanding Sales Invoices minus outstanding Purchase Invoices (net receivable)

The calculation uses a retry mechanism with up to 3 attempts to handle concurrent updates (ConflictError).

Customer Actions

When viewing a customer record, the following contextual actions are available:

Duplicate Behavior

When duplicating a customer, the outstandingAmount is reset to zero and loyaltyPoints is reset to 0, ensuring the new record starts fresh.

Filtering in Sidebar

The sidebar entry "Customers" applies a route filter of role: ["in", ["Customer", "Both"]] to show only parties that can receive Sales Invoices.

4.5 Sales Items

Items in NkapBooks represent products or services that can be sold, purchased, or both. Items visible under Sales → Sales Items are filtered to show only those with for: "Sales" or for: "Both".

Schema Overview

Income Account Logic

The income account is automatically determined:

• SYSCOHADA Countries: Products → 701-Ventes de Marchandises; Services → 706-Services Vendus
• Other Countries: Products → Sales; Services → Service

Stock Quantity in List View

When viewing the items list, a Stock Qty column shows the current stock balance for tracked items. This is computed by summing stock ledger entries across all locations. Non-tracked items show a dash (-).

Item Actions

Read-Only After Save

The following fields become read-only after the item is first saved to maintain data integrity:

• Unit, Item Type, Track Item, Has Batch, Has Serial Number

4.6 Loyalty Program

The Loyalty Program allows you to reward customers with points based on their purchase amounts. Points can be accumulated over time and redeemed as discounts on future purchases.

Schema Overview

Collection Rules

Each collection rule defines a tier with conditions for earning points:

How Points Are Earned

When a Sales Invoice is submitted:

1. The system checks if the customer has an assigned Loyalty Program.
2. It determines the customer's tier based on their total spending history.
3. Points are calculated: purchase amount / collection factor.
4. A Loyalty Point Entry is created with:
   • The program name, tier, customer, invoice reference
   • Posting date and expiry date (posting date + expiry duration)
   • The number of points earned

How Points Are Redeemed

On a Sales Invoice:

1. Enable Redeem Loyalty Points (checkbox on the invoice).
2. Enter the number of Loyalty Points to redeem.
3. The monetary value is calculated: points × conversion factor.
4. Validations ensure:
   • Points must be greater than 0
   • Points cannot exceed the customer's available balance
   • The redemption value cannot exceed the invoice grand total
5. On submit, the ledger entries include an additional debit to the Loyalty Expense Account.

Loyalty Point Entry

Each point transaction (earned or redeemed) is tracked as a LoyaltyPointEntry:

Customer Loyalty Balance

Each customer's loyalty point balance is automatically calculated by summing all non-expired LoyaltyPointEntry records. The balance is visible on the customer's Party record under the Loyalty Program section.

4.7 Pricing Rules

Pricing Rules allow you to automate discounts and free item offers based on configurable conditions. They can be applied to individual items, item groups, or all items.

Schema Overview

Discount Type: Price Discount

When Discount Type = "Price Discount", you choose one of three sub-types:

Optionally link to a Price List for rate-based discounts using the forPriceList field.

Discount Type: Product Discount

When Discount Type = "Product Discount", a free item is automatically added to the invoice:

Conditions

Pricing rules can be limited by quantity and amount ranges, and by date validity:

Priority & Conflict Resolution

When multiple pricing rules match for the same item:

1. Rules are sorted by priority (highest first).
2. If two rules have the same priority, the system detects a conflict and prompts the user to resolve it.
3. Only one pricing rule can be applied per item per invoice.

How Pricing Rules Are Applied

When an item is added to a Sales Invoice:

1. The system queries all enabled pricing rules where the item (or its group) is in the appliedItems table.
2. Non-coupon-based rules are filtered by quantity, amount, and date conditions.
3. Coupon-based rules are only considered if a matching coupon code has been applied to the invoice.
4. The highest-priority matching rule is applied:
   • Price Discount: The item's discount amount or percentage is automatically set.
   • Product Discount: A free item row is added to the invoice with isFreeItem: true and pricingRule set.
5. The pricingRuleDetail table on the invoice records which rules were applied to which items.

4.9 Coupon Codes

Coupon Codes are alphanumeric codes that customers can use to activate coupon-based Pricing Rules. They add a layer of control over when and how discounts are applied.

Schema Overview

Code Generation

The coupon code is automatically generated from the coupon name:

• Spaces are removed
• Text is converted to uppercase
• Truncated to 8 characters

For example: "Summer Sale" → SUMMERSA

Validation Rules

Coupon codes enforce strict validation:

How Coupons Work in an Invoice

1. Add items to a Sales Invoice as usual.
2. In the Coupons section, add one or more coupon codes.
3. The system validates each coupon against the current invoice:
   • Is the coupon enabled?
   • Is the current date within the Valid From/To range?
   • Is the invoice amount within the Min/Max amount range?
   • Has the coupon not exceeded its Maximum Use limit?
4. If valid, the linked Pricing Rule is activated and the discount is applied.
5. When the invoice is submitted, the coupon's used counter is incremented.
6. If the invoice is cancelled, the used counter is decremented.

4.10 Price Lists

Price Lists allow you to maintain multiple sets of item prices for different customer segments, channels, or promotions (e.g., Retail, Wholesale, VIP, Staff).

Schema Overview

Price List Items

Each row in the Item Prices table defines a rate for a specific item:

How Price Lists Work

1. Create a Price List — Give it a name, enable it for Sales and/or Purchase, and add item rows with custom rates.
2. Apply to an Invoice — Select the Price List in the invoice's priceList field.
3. Automatic Rate Lookup — When an item is added to the invoice, the system looks up the item's rate from the selected price list. If found, it overrides the item's default rate.
4. Fallback Behavior — If an item is not in the price list, the item's default saleRate (or purchaseRate) is used.
5. Priority — Price list rates take precedence over the item's default rate but may be further modified by Pricing Rules.

Filtering

When selecting a price list on a Sales Invoice:

• Only price lists with isEnabled: true AND isSales: true are shown.

When selecting on a Purchase Invoice:

• Only price lists with isEnabled: true AND isPurchase: true are shown.

List View

The Price List list view shows:

• Name — The price list identifier
• Enabled Status — Badge showing whether the list is active
• Sales/Purchase — Badge indicating whether it's for Sales, Purchase, or both

4.11 Sales Module Tips & Best Practices

Recommended Workflow

1. Create a Lead (optional) — Track prospects before they become customers.
2. Send a Sales Quote — Prepare a formal quotation with pricing and terms.
3. Convert to Invoice — One-click conversion preserves all details.
4. Receive Payment — Record partial or full payment against the invoice.
5. Ship Goods — Create a Shipment for tracked inventory items.
6. Track Loyalty — Customers automatically earn loyalty points on purchases.

Discount Strategy

• Use Pricing Rules for automated, condition-based discounts (quantity breaks, seasonal promotions).
• Use Coupon Codes for customer-initiated discounts (marketing campaigns, referral codes).
• Use Price Lists for segment-based pricing (wholesale vs. retail).
• Use Invoice-Level Discounts for one-off manual adjustments.
• Use Item-Level Discounts for per-line adjustments.

Multi-Currency Tips

• Set the customer's default currency on their Party record to auto-apply it on invoices.
• Exchange rates are fetched automatically but can be manually overridden.
• The baseGrandTotal always shows the amount in your company currency for consistent reporting.

Returns & Credit Notes

• Always use the Create → Return action instead of manually creating negative invoices.
• Returns automatically reverse the original ledger entries.
• Partial returns are supported — specify the quantity to return for each item.
• The original invoice's status updates to "Return Issued" after a return is created.