Sales Invoice Complete Walkthrough - Example-Based Documentation

Overview

This document demonstrates the complete lifecycle of a sales invoice using a real payload example, showing exactly which tables and columns are affected during both Add (Draft) and Post phases.

Example Payload

json


{

  "invoiceDate": "2026-01-28T16:14:36",

  "invoiceDueDate": "2026-01-28T14:14:36.711Z",

  "description": "",

  "warehouseId": 48,

  "warehouseName": "Default Warehouse 1",

  "customerId": 433,

  "customerName": "dubai ",

  "customerCreditLimit": 0,

  "pricePolicyId": 42,

  "currencyId": 4,

  "currencyName": "Saudi Riyal",

  "currencyNameAr": "ريال سعودي",

  "currencyRate": 1,

  "paymentTermId": 38,

  "isLinkedToAdvancedPayment": false,

  "sourceType": "Direct",

  "salesInvoiceDetails": [

    {

      "itemId": 422,

      "itemCode": "IDEF_00004",

      "itemName": "وشاح",

      "itemVariantId": 543,

      "categoryId": 109,

      "categoryType": "Storable",

      "isServiceItem": false,

      "uomId": "79415be3-345f-4d51-87ac-84ec87e7a0b0",

      "uomCode": "G8roW",

      "quantity": "1",

      "price": 1000,

      "cost": 99.63636609,

      "costCenterId": 87,

      "costCenterName": "مركز تكلفة 3",

      "discountPercentage": 0,

      "discountAmount": 0,

      "isVatIncluded": false,

      "vatPercentage": 15,

      "taxId": 460,

      "grandTotal": 1150,

      "trackingType": "NoTracking",

      "hasExpiryDate": false,

      "invoiceEntryMode": "Manual"

    }

  ],

  "salesInvoiceBalances": [

    {

      "dueAmount": 1150,

      "dueDate": "2026-01-28",

      "dueBalance": 1150

    }

  ]

}

Phase 1: Add Sales Invoice (Draft)

Handler: AddSalesInvoiceCommandHandler

Action: Creates draft invoice, no inventory or GL impact

Calculations (Before Saving)


Line Item Calculations:

  Quantity × Price = Net Amount

  1 × 1000 = 1000 SAR

  

  VAT Amount (if not included):

  1000 × 15% = 150 SAR

  

  Grand Total:

  1000 + 150 = 1150 SAR

  

Header Totals:

  TotalNetAmount = 1000 SAR

  TotalDiscount = 0 SAR

  TotalAfterDiscount = 1000 SAR

  GrandTotal = 1150 SAR

  LocalGrandTotal = 1150 SAR (currencyRate = 1)

Table 1: SalesInvoiceHeader (INSERT)

Operation: INSERT new record

|------------|-------|--------|-------|

Table 2: SalesInvoiceDetail (INSERT)

Operation: INSERT new record (one per line item)

|------------|-------|--------|-------|

| VatPercentage | 15.0 | Payload | 15% VAT |

| VatAmount | 150.00 | CalculateAllFields() | 1000 × 15% |

Table 3: SalesInvoiceTracking (INSERT)

Operation: INSERT new record

|------------|-------|--------|-------|

Tracking Record Behavior:

NoTracking: Tracking record created with NULL TrackingNo, stores quantity
NoTracking + Expiry: Tracking record with system-generated batch and expiry date
Serial: One record per serial number, Quantity = 1 each
Batch: One or more records per batch number with quantities

Table 4: SalesInvoiceBalance (INSERT)

Operation: INSERT new record (one per payment term installment)

Note: Payment Term ID 38 is used. Assuming it has one installment (Net 0 - immediate payment).

|------------|-------|--------|-------|

Payment Term Logic:

If payment term has multiple installments (e.g., 30% in 10 days, 70% in 30 days), multiple balance records are created:


Balance 1: DueAmount = 345 (30%), DueDate = 2026-02-07

Balance 2: DueAmount = 805 (70%), DueDate = 2026-02-27

Table 5: SalesInvoiceSource (NO INSERT)

Operation: NONE - Direct sale (not from Sales Order)

Reason: SourceType = "Direct", no Sales Order references

When created:

SourceType = "SalesOrder"
Links invoice to originating sales order(s)

Summary of Add Phase (Draft)

Tables Affected:

✅ SalesInvoiceHeader - 1 INSERT
✅ SalesInvoiceDetail - 1 INSERT
✅ SalesInvoiceTracking - 1 INSERT (even for NoTracking, stores quantity)
✅ SalesInvoiceBalance - 1 INSERT
❌ SalesInvoiceSource - 0 records (Direct sale)

Inventory Impact:

NONE - No stock movement in draft phase

GL Impact:

NONE - No journal entries in draft phase

Validations Performed:

✅ Invoice date in open financial period (FinancialYearPeriodId = 25)

✅ Customer credit limit check (0 limit, passed)

✅ No overdue unpaid invoices for customer (if enabled)

✅ Cost center provided (87) as required by accounting settings

✅ Price matches price policy (PricePolicyDetailId = 498)

Phase 2: Post Sales Invoice

Handler: PostSalesInvoiceCommandHandler

Action: Finalizes invoice, creates inventory and GL transactions

Prerequisites Check

Before posting, system validates:

✅ Invoice Status = Draft
✅ Period allows posted journals (Jan 2026 period open)
✅ Customer has receivable account configured
✅ Item 422 has revenue account configured
✅ Tax 460 has GL account configured
✅ COGS account exists in inventory settings
✅ Warehouse 48 has available stock (Quantity ≥ 1 for Item 422/Variant 543)

Table 1: SalesInvoiceHeader (UPDATE)

Operation: UPDATE existing record

|------------|----------------|----------------|-------------------|

All other columns remain unchanged

Table 2: StockOutHeader (INSERT - Inventory Module)

Operation: INSERT new record

Created By: IInventoryPublicApi.AddPostedStockOut()

|------------|-------|--------|-------|

Table 3: StockOutDetail (INSERT - Inventory Module)

Operation: INSERT new record (one per inventory line)

Created By: IInventoryPublicApi.AddPostedStockOut()

|------------|-------|--------|-------|

COGS Calculation:

System uses Weighted Average Cost from ItemStockBatchHeader
For Item 422, Variant 543, Warehouse 48
Current available stock: Quantity = 10, Total Cost = 996.36, WAC = 99.64

Table 4: StockOutTracking (INSERT)

Operation: INSERT new record

Created By: IInventoryPublicApi.AddPostedStockOut()

Note: Even for NoTracking items, a tracking record is created to store the quantity

|------------|-------|--------|-------|

Tracking Record Behavior:

NoTracking: Tracking record created with NULL TrackingNo, stores quantity and cost
Serial: One record per serial number issued, Quantity = 1 each
Batch: One or more records per batch number with quantities
Expiry: One record per expiry batch issued with expiry date

Table 5: ItemStockDetail (UPDATE - Inventory Module)

Operation: UPDATE existing record

Mechanism: Reduces AvailableQuantity

Before Post:

sql


ItemId: 422

ItemVariantId: 543

WarehouseId: 48

TrackingNo: NULL (NoTracking)

TrackingType: NoTracking

HasExpiryDate: false

Quantity: 10.0

AvailableQuantity: 10.0

TotalCost: 996.36

UnitCost: 99.64 (Weighted Average)

After Post:

sql


ItemId: 422

ItemVariantId: 543

WarehouseId: 48

TrackingNo: NULL (NoTracking)

TrackingType: NoTracking

HasExpiryDate: false

Quantity: 10.0              -- Unchanged (historical record)

AvailableQuantity: 9.0      -- Reduced by 1

TotalCost: 996.36           -- Unchanged

UnitCost: 99.64             -- Unchanged

Update Logic:

sql


UPDATE ItemStockDetail

SET AvailableQuantity = AvailableQuantity - 1.0

WHERE ItemVariantId = 543

  AND WarehouseId = 48

  AND TrackingType = 'NoTracking'

  AND HasExpiryDate = false

Table 6: JournalEntry (INSERT #1 - Sales Journal)

Operation: INSERT new record

Created By: IAccountingPublicApi.AddJournal()

Purpose: Record sales revenue and receivable

|------------|-------|--------|-------|

Table 7: JournalEntryLine (INSERT Multiple - Sales Journal)

Operation: INSERT 3 records

Created By: IAccountingPublicApi.AddJournal()

Line 1: Accounts Receivable (Debit)

|------------|-------|--------|-------|

| CreditAmount | 0.00 | N/A | No credit |

Line 2: VAT Output (Credit)

|------------|-------|--------|-------|

| DebitAmount | 0.00 | N/A | No debit |

Line 3: Sales Revenue (Credit)

|------------|-------|--------|-------|

| DebitAmount | 0.00 | N/A | No debit |

Sales Journal Summary:


JE-2026-0123 - Sales Journal

  DR  1010  Accounts Receivable       1,150.00

      CR  2030  VAT Output                       150.00

      CR  4010  Sales Revenue                  1,000.00

                                     ---------  ---------

      Total                          1,150.00   1,150.00

Table 8: JournalEntry (INSERT #2 - COGS Journal)

Operation: INSERT new record

Created By: IInventoryPublicApi.AddPostedStockOut() (Inventory Module)

Purpose: Record cost of goods sold and inventory reduction

|------------|-------|--------|-------|

Table 9: JournalEntryLine (INSERT Multiple - COGS Journal)

Operation: INSERT 2 records

Created By: Inventory Module

Line 1: Cost of Goods Sold (Debit)

|------------|-------|--------|-------|

| CreditAmount | 0.00 | N/A | No credit |

Line 2: Inventory Asset (Credit)

|------------|-------|--------|-------|

| DebitAmount | 0.00 | N/A | No debit |

COGS Journal Summary:


JE-2026-0124 - COGS Journal

  DR  5010  Cost of Goods Sold           99.64

      CR  1030  Inventory                        99.64

                                        ------  ------

      Total                              99.64   99.64

Table 10: CustomerFinancial (UPDATE)

Operation: UPDATE existing record

Before Post:

sql


CustomerId: 433

CustomerName: "dubai"

TotalSales: 0.00

TotalReturns: 0.00

OutstandingBalance: 0.00

CreditLimit: 0.00

AvailableCredit: 0.00

After Post:

sql


CustomerId: 433

CustomerName: "dubai"

TotalSales: 1150.00              -- += Invoice.LocalGrandTotal

TotalReturns: 0.00               -- Unchanged

OutstandingBalance: 1150.00      -- += Invoice.LocalGrandTotal

CreditLimit: 0.00                -- Unchanged

AvailableCredit: -1150.00        -- CreditLimit - OutstandingBalance

Update SQL:

sql


UPDATE CustomerFinancial

SET TotalSales = TotalSales + 1150.00,

    OutstandingBalance = OutstandingBalance + 1150.00,

    AvailableCredit = CreditLimit - (OutstandingBalance + 1150.00)

WHERE CustomerId = 433

Table 11: SalesMan (NO UPDATE)

Operation: NONE - No salesman assigned

Reason: SalesManId is NULL in the invoice

When updated:

If SalesManId is provided, updates salesman's TotalSales and OutstandingBalance

Summary of Post Phase

Tables Affected:

✅ SalesInvoiceHeader - 1 UPDATE (status, journal IDs)
✅ StockOutHeader - 1 INSERT (inventory transaction)
✅ StockOutDetail - 1 INSERT (line detail)
✅ StockOutTracking - 1 INSERT (even for NoTracking, stores quantity and cost)
✅ ItemStockDetail - 1 UPDATE (reduced AvailableQuantity)
✅ JournalEntry - 2 INSERTS (Sales + COGS journals)
✅ JournalEntryLine - 5 INSERTS (3 sales + 2 COGS)
✅ CustomerFinancial - 1 UPDATE (balances)
❌ SalesMan - 0 updates (no salesman)

Inventory Impact:


Item: IDEF_00004 (وشاح)

Warehouse: Default Warehouse 1 (48)

Before: Available Qty = 10

After:  Available Qty = 9

COGS Recognized: 99.64 SAR

GL Impact (Combined Journals):


Chart of Accounts Impact:

  Account 1010 (Accounts Receivable)   DR  1,150.00

  Account 2030 (VAT Output)                CR    150.00

  Account 4010 (Sales Revenue)             CR  1,000.00

  Account 5010 (COGS)                  DR     99.64

  Account 1030 (Inventory)                 CR     99.64

  

Balance Sheet Impact:

  Assets:

    Accounts Receivable  +1,150.00

    Inventory              -99.64

    Net Assets           +1,050.36

  

  Liabilities:

    VAT Payable          +150.00

  

Income Statement Impact:

  Revenue:

    Sales Revenue        +1,000.00

  

  Expenses:

    Cost of Goods Sold     +99.64

  

  Gross Profit           +900.36

Financial Ratios:


Gross Profit Margin = (Revenue - COGS) / Revenue

                    = (1000 - 99.64) / 1000

                    = 90.04%

  

Markup = (Selling Price - Cost) / Cost

       = (1000 - 99.64) / 99.64

       = 903.6%

Complete Transaction Flow Summary

Step-by-Step Execution


1. User submits Add Sales Invoice request

   ↓

2. AddSalesInvoiceCommandHandler.Handle()

   ↓

3. Validate invoice date → Get FinancialYearPeriodId = 25

   ↓

4. Validate price policy → Match price 1000 to PricePolicyDetailId = 498

   ↓

5. Validate cost center activated → Check costCenterId = 87 provided

   ↓

6. Validate customer credit limit → 0 limit, no overdue invoices

   ↓

7. Generate sequence code → "SI-2026-0001"

   ↓

8. Calculate line totals:

   - NetAmount = 1 × 1000 = 1000

   - VatAmount = 1000 × 15% = 150

   - GrandTotal = 1000 + 150 = 1150

   ↓

9. Calculate header totals:

   - TotalNetAmount = 1000

   - TotalAfterDiscount = 1000

   - GrandTotal = 1150

   ↓

10. Create payment term balances:

    - DueDate = 2026-01-28

    - DueAmount = 1150

    ↓

11. INSERT SalesInvoiceHeader (Status = Draft)

    INSERT SalesInvoiceDetail (1 line)

    INSERT SalesInvoiceBalance (1 installment)

    ↓

12. SaveChanges → Database transaction committed

    ↓

13. Return InvoiceId → Frontend receives draft invoice

  

--- DRAFT PHASE COMPLETE ---

  

14. User clicks "Post" button

    ↓

15. PostSalesInvoiceCommandHandler.Handle()

    ↓

16. Validate preconditions:

    - Invoice is Draft ✓

    - Period allows posting ✓

    - Customer has receivable account ✓

    - Item has revenue account ✓

    - Tax has GL account ✓

    - COGS account exists ✓

    - Warehouse has available stock (Qty ≥ 1) ✓

    ↓

17. Create Sales Journal (JE-2026-0123):

    DR  Accounts Receivable  1,150

        CR  VAT Output                 150

        CR  Sales Revenue            1,000

    ↓

18. Call IInventoryPublicApi.AddPostedStockOut():

    - Create StockOutHeader (SO-2026-0001)

    - Create StockOutDetail (Qty 1, Cost 99.64)

    - Update ItemStockDetail (AvailableQty 10 → 9)

    - Create COGS Journal (JE-2026-0124):

      DR  COGS                    99.64

          CR  Inventory                    99.64

    - Return StockOutId, JournalId

    ↓

19. Update SalesInvoiceHeader:

    - Status = Posted

    - StockOutId = [GUID]

    - StockOutCode = "SO-2026-0001"

    - InvoiceJournalId = [GUID]

    - InvoiceJournalCode = "JE-2026-0123"

    - StockOutJournalId = [GUID]

    - StockOutJournalCode = "JE-2026-0124"

    - PostedDate = 2026-01-28 16:20:00

    ↓

20. Update CustomerFinancial:

    - TotalSales += 1150

    - OutstandingBalance += 1150

    ↓

21. SaveChanges → All transactions committed

    ↓

22. Publish webhook event (if enabled)

    ↓

23. Return InvoiceId → Frontend receives posted invoice

  

--- POST PHASE COMPLETE ---

Database Transaction Isolation

Add Phase (Draft)

sql


BEGIN TRANSACTION

  

INSERT INTO SalesInvoiceHeader VALUES (...)

INSERT INTO SalesInvoiceDetail VALUES (...)

INSERT INTO SalesInvoiceBalance VALUES (...)

  

COMMIT TRANSACTION

Duration: ~50ms (single database transaction)

Post Phase

sql


BEGIN TRANSACTION -- Main Transaction

  

-- Step 1: Create Sales Journal

EXEC Accounting.AddJournal

  INSERT INTO JournalEntry VALUES (...)

  INSERT INTO JournalEntryLine VALUES (...) -- 3 lines

  

-- Step 2: Create Stock Out (nested transaction)

EXEC Inventory.AddPostedStockOut

  INSERT INTO StockOutHeader VALUES (...)

  INSERT INTO StockOutDetail VALUES (...)

  UPDATE ItemStockDetail SET AvailableQuantity -= 1

  

  -- Create COGS Journal

  INSERT INTO JournalEntry VALUES (...)

  INSERT INTO JournalEntryLine VALUES (...) -- 2 lines

  

-- Step 3: Update Invoice

UPDATE SalesInvoiceHeader

  SET Status = 'Posted',

      StockOutId = @StockOutId,

      InvoiceJournalId = @JournalId,

      ...

  

-- Step 4: Update Customer

UPDATE CustomerFinancial

  SET TotalSales += 1150,

      OutstandingBalance += 1150

  

COMMIT TRANSACTION

Duration: ~200-500ms (multiple module integrations)

Error Scenarios

Add Phase Validation Failures

| Error Condition | Error Message | Resolution |

|----------------|---------------|------------|

| Invalid Period | "Invoice date must be in an open financial period" | Change invoice date or open period |

| Customer Credit Exceeded | "Grand total exceeds customer credit limit" | Increase credit limit or reduce amount |

| Cost Center Missing | "Cost center required for all invoice details" | Provide cost center ID |

| Price Policy Mismatch | "Price does not match active price policy" | Use price from policy or override |

| Customer Has Overdue | "Customer has outstanding invoices: SI-2026-0001" | Customer must pay overdue invoices |

Post Phase Validation Failures

| Error Condition | Error Message | Resolution |

|----------------|---------------|------------|

| Invoice Not Draft | "Invoice must be in draft status to post" | Cannot post already-posted invoice |

| Insufficient Stock | "Insufficient stock for item IDEF_00004" | Receive more inventory or reduce qty |

| Missing GL Account | "Customer receivable account not configured" | Configure customer accounting |

| Missing Item Account | "Item revenue account not found for item 422" | Configure item GL accounts |

| Missing Tax Account | "Tax definition account required for tax 460" | Configure tax GL account |

| Period Closed | "Cannot post journals in closed period" | Reopen period or change invoice date |

End of Walkthrough

This example demonstrates a typical sales invoice with:

✅ Single storable item (no tracking)
✅ Direct sale (not from sales order)
✅ No discount
✅ VAT not included in price
✅ Single payment installment
✅ Cost center tracking
✅ Weighted average cost method

Document Version: 1.0

Example Date: 2026-01-28

Currency: Saudi Riyal (SAR)

Total Amount: 1,150.00 SAR (including 15% VAT)

Sales Invoice Complete Walkthrough - Example-Based Documentation ​

Overview ​

Example Payload ​

Phase 1: Add Sales Invoice (Draft) ​

Calculations (Before Saving) ​

Table 1: SalesInvoiceHeader (INSERT) ​

Table 2: SalesInvoiceDetail (INSERT) ​

Table 3: SalesInvoiceTracking (INSERT) ​

Table 4: SalesInvoiceBalance (INSERT) ​

Table 5: SalesInvoiceSource (NO INSERT) ​

Summary of Add Phase (Draft) ​

Tables Affected: ​

Inventory Impact: ​

GL Impact: ​

Validations Performed: ​

Phase 2: Post Sales Invoice ​

Prerequisites Check ​

Table 1: SalesInvoiceHeader (UPDATE) ​

Table 2: StockOutHeader (INSERT - Inventory Module) ​

Table 3: StockOutDetail (INSERT - Inventory Module) ​

Table 4: StockOutTracking (INSERT) ​

Table 5: ItemStockDetail (UPDATE - Inventory Module) ​

Table 6: JournalEntry (INSERT #1 - Sales Journal) ​

Table 7: JournalEntryLine (INSERT Multiple - Sales Journal) ​

Line 1: Accounts Receivable (Debit) ​

Line 2: VAT Output (Credit) ​

Line 3: Sales Revenue (Credit) ​

Table 8: JournalEntry (INSERT #2 - COGS Journal) ​

Table 9: JournalEntryLine (INSERT Multiple - COGS Journal) ​

Line 1: Cost of Goods Sold (Debit) ​

Line 2: Inventory Asset (Credit) ​

Table 10: CustomerFinancial (UPDATE) ​

Table 11: SalesMan (NO UPDATE) ​

Summary of Post Phase ​

Tables Affected: ​

Inventory Impact: ​

GL Impact (Combined Journals): ​

Financial Ratios: ​

Complete Transaction Flow Summary ​

Step-by-Step Execution ​

Database Transaction Isolation ​

Add Phase (Draft) ​

Post Phase ​

Error Scenarios ​

Add Phase Validation Failures ​

Post Phase Validation Failures ​

End of Walkthrough ​

Sales Invoice Complete Walkthrough - Example-Based Documentation

Overview

Example Payload

Phase 1: Add Sales Invoice (Draft)

Calculations (Before Saving)

Table 1: SalesInvoiceHeader (INSERT)

Table 2: SalesInvoiceDetail (INSERT)

Table 3: SalesInvoiceTracking (INSERT)

Table 4: SalesInvoiceBalance (INSERT)

Table 5: SalesInvoiceSource (NO INSERT)

Summary of Add Phase (Draft)

Tables Affected:

Inventory Impact:

GL Impact:

Validations Performed:

Phase 2: Post Sales Invoice

Prerequisites Check

Table 1: SalesInvoiceHeader (UPDATE)

Table 2: StockOutHeader (INSERT - Inventory Module)

Table 3: StockOutDetail (INSERT - Inventory Module)

Table 4: StockOutTracking (INSERT)

Table 5: ItemStockDetail (UPDATE - Inventory Module)

Table 6: JournalEntry (INSERT #1 - Sales Journal)

Table 7: JournalEntryLine (INSERT Multiple - Sales Journal)

Line 1: Accounts Receivable (Debit)

Line 2: VAT Output (Credit)

Line 3: Sales Revenue (Credit)

Table 8: JournalEntry (INSERT #2 - COGS Journal)

Table 9: JournalEntryLine (INSERT Multiple - COGS Journal)

Line 1: Cost of Goods Sold (Debit)

Line 2: Inventory Asset (Credit)

Table 10: CustomerFinancial (UPDATE)

Table 11: SalesMan (NO UPDATE)

Summary of Post Phase

Tables Affected:

Inventory Impact:

GL Impact (Combined Journals):

Financial Ratios:

Complete Transaction Flow Summary

Step-by-Step Execution

Database Transaction Isolation

Add Phase (Draft)

Post Phase

Error Scenarios

Add Phase Validation Failures

Post Phase Validation Failures

End of Walkthrough