Tax Transactions

Overview

The Tax Transactions API provides endpoints for querying posted tax transactions generated from general ledger journals. These transactions represent the calculated taxes based on the intersection of Tax Groups and Tax Item Groups assigned to journal lines.

Base URL

/api/v1/general-ledger/general-journals

Authentication

All endpoints require authentication. Include the JWT token in the Authorization header:

Authorization: Bearer <jwt-token>

Endpoints

Get Tax Transactions for Journal

Retrieves all tax transactions associated with a posted journal. Tax transactions are created during the posting process and represent the calculated tax amounts based on the intersection logic between Tax Groups and Tax Item Groups.

Endpoint: GET /general-journals/{journalId}/tax-transactions

Parameters:

journalId (UUID, required): The unique identifier of the posted journal

Request Example:

GET /api/v1/general-ledger/general-journals/a1b2c3d4-e5f6-7a8b-9c0d-e1f2a3b4c5d6/tax-transactions
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
Accept: application/json

Success Response:

Code: 200 OK
Content-Type: application/json

[
  {
    "id": "f1e2d3c4-b5a6-7f8e-9d0c-1b2a3f4e5d6c",
    "generalJournalEntryId": "a1b2c3d4-e5f6-7a8b-9c0d-e1f2a3b4c5d6",
    "voucher": "TAX-V-001",
    "transactionDate": "2025-10-01T10:00:00.000Z",
    "currencyCode": "AED",
    "taxAmount": 50.00,
    "sourceAmount": 1000.00,
    "taxValue": 5.00,
    "taxDirection": "Input",
    "source": "GeneralJournal",
    "taxCodeId": "a6b7c8d9-e0f1-8901-23ab-cdef45678901",
    "taxCodeCode": "STD_5",
    "taxCodeName": "Standard Tax 5%",
    "taxGroupId": "e6f7a8b9-c0d1-8901-23ef-abcd45678901",
    "taxGroupCode": "RETAIL_STD",
    "taxItemGroupId": "d1e2f3a4-b5c6-3456-78de-fabc90123456",
    "taxItemGroupCode": "SCENT_OILS_STANDARD"
  }
]

Response Fields:

Field	Type	Description
`id`	UUID	Unique identifier of the tax transaction
`generalJournalEntryId`	UUID	Reference to the parent general journal entry
`voucher`	string	Voucher number from the original journal line
`transactionDate`	datetime	Transaction date from the original journal line
`currencyCode`	string	Currency code for all monetary amounts
`taxAmount`	decimal	Calculated tax amount for this tax code
`sourceAmount`	decimal	Original transaction amount before tax
`taxValue`	decimal	Tax percentage rate applied (e.g., 5.00 for 5%)
`taxDirection`	string	Direction of tax flow: "Input" (receivable) or "Output" (payable)
`source`	string	Source type of the transaction (e.g., "GeneralJournal", "SalesInvoice")
`taxCodeId`	UUID	Identifier of the applied tax code
`taxCodeCode`	string	Code of the applied tax code
`taxCodeName`	string	Name of the applied tax code
`taxGroupId`	UUID	Identifier of the tax group from the transaction
`taxGroupCode`	string	Code of the tax group
`taxItemGroupId`	UUID	Identifier of the tax item group from the transaction
`taxItemGroupCode`	string	Code of the tax item group

Error Responses:

Code: 404 Not Found

{
  "error": "Journal with ID a1b2c3d4-e5f6-7a8b-9c0d-e1f2a3b4c5d6 not found"
}

Code: 400 Bad Request

{
  "error": "Invalid journal ID format"
}

Tax Calculation Logic

Intersection-Based Tax Determination

The system uses an intersection model (Venn diagram logic) to determine which tax codes apply to a transaction:

Tax Group contains tax codes applicable to the entity (Customer, Vendor, etc.)
Tax Item Group contains tax codes applicable to the item/service
Effective Tax Codes are the intersection of codes from both groups
Each effective tax code generates a separate TaxTransaction record

Example Scenario

Tax Group: RETAIL_STD

Contains: STD_5 (5%), STD_10 (10%), CITY_TAX (2%)

Tax Item Group: SCENT_OILS_STANDARD

Contains: STD_5 (5%), IMPORT_DUTY (3%)

Intersection (Applied Taxes):

STD_5 (5%) - Present in both groups

Result:

Only one TaxTransaction is created for STD_5 at 5%
Transaction amount: 1000 AED
Tax amount: 50 AED (1000 × 5%)

Tax Direction

Tax direction is determined by the account type and transaction type:

Input Tax (Receivable): Tax paid on purchases, recorded as an asset
- Example: VAT paid when purchasing goods
- GL Account: Tax Receivable (Asset)
Output Tax (Payable): Tax collected on sales, recorded as a liability
- Example: VAT collected when selling goods
- GL Account: Tax Payable (Liability)

Usage Examples

Successful Query - Single Tax Transaction

curl -X GET \
  "https://api.example.com/api/v1/general-ledger/general-journals/a1b2c3d4-e5f6-7a8b-9c0d-e1f2a3b4c5d6/tax-transactions" \
  -H "Authorization: Bearer <token>" \
  -H "Accept: application/json"

Response:

[
  {
    "id": "f1e2d3c4-b5a6-7f8e-9d0c-1b2a3f4e5d6c",
    "generalJournalEntryId": "a1b2c3d4-e5f6-7a8b-9c0d-e1f2a3b4c5d6",
    "voucher": "TAX-V-001",
    "transactionDate": "2025-10-01T10:00:00.000Z",
    "currencyCode": "AED",
    "taxAmount": 50.00,
    "sourceAmount": 1000.00,
    "taxValue": 5.00,
    "taxDirection": "Input",
    "source": "GeneralJournal",
    "taxCodeId": "a6b7c8d9-e0f1-8901-23ab-cdef45678901",
    "taxCodeCode": "STD_5",
    "taxCodeName": "Standard Tax 5%",
    "taxGroupId": "e6f7a8b9-c0d1-8901-23ef-abcd45678901",
    "taxGroupCode": "RETAIL_STD",
    "taxItemGroupId": "d1e2f3a4-b5c6-3456-78de-fabc90123456",
    "taxItemGroupCode": "SCENT_OILS_STANDARD"
  }
]

Successful Query - Multiple Tax Transactions

When a journal has multiple lines with different tax configurations:

[
  {
    "id": "f1e2d3c4-b5a6-7f8e-9d0c-1b2a3f4e5d6c",
    "voucher": "TAX-V-002",
    "taxAmount": 25.00,
    "sourceAmount": 500.00,
    "taxValue": 5.00,
    "taxCodeCode": "STD_5"
  },
  {
    "id": "a2b3c4d5-e6f7-8a9b-0c1d-2e3f4a5b6c7d",
    "voucher": "TAX-V-002",
    "taxAmount": 37.50,
    "sourceAmount": 750.00,
    "taxValue": 5.00,
    "taxCodeCode": "STD_5"
  }
]

Query with No Tax Transactions

If the journal has no taxable lines (no tax groups specified):

Response:

[]

Integration with Journal Posting

Pre-Posting

During journal line creation:

Client specifies optional tax_group_id and tax_item_group_id
System validates that both IDs exist
System calculates and stores tax amount and rate on the journal line
No TaxTransaction records are created yet

During Posting

When the journal is posted:

System reads the stored tax information from each journal line
For each line with tax data:
- Creates a GeneralJournalEntry record
- Creates corresponding TaxTransaction records
- Links tax transactions to the journal entry
Tax transactions become immutable after posting

Post-Posting

After posting:

Tax transactions can be queried via this endpoint
Tax transactions are included in tax reports and settlements
Tax transactions cannot be modified or deleted
Tax transactions are included in audit trails

Business Rules

Journal Must Be Posted: Tax transactions are only created during posting
Tax Group Intersection: Only tax codes in both groups are applied
One Transaction Per Tax Code: Each effective tax code creates one transaction per journal line
Immutability: Tax transactions cannot be modified after creation
Currency Consistency: All amounts use the transaction's currency
Audit Trail: All tax transactions are fully auditable with source references

POST /general-journals/{journalId}/transactions - Add journal line with tax
PUT /general-journals/{journalId}/post - Post journal and create tax transactions
GET /tax/tax-groups/{taxGroupId} - Get tax group details
GET /tax/tax-item-groups/{taxItemGroupId} - Get tax item group details
POST /general-journals/preview-sales-tax - Preview tax before posting

Testing Considerations

Test Scenarios

Single Taxable Line
- Create journal with one line
- Assign both tax groups
- Verify single tax transaction created
Multiple Taxable Lines
- Create journal with multiple lines
- Use different tax group combinations
- Verify correct number of transactions
Mixed Taxable and Non-Taxable
- Some lines with tax groups
- Some lines without tax groups
- Verify only taxable lines create transactions
Zero Intersection
- Tax groups with no common tax codes
- Verify no tax transactions created
Multiple Tax Codes
- Tax groups with multiple common codes
- Verify multiple transactions per line

Verification Checklist

Tax amounts calculated correctly (source × rate)
Tax direction set appropriately
All reference IDs populated correctly
Voucher numbers match journal lines
Transaction dates match journal lines
Currency codes consistent
No tax transactions for non-taxable lines
Tax transactions immutable after posting

Performance Considerations

Query is optimized for posted journals
Indexes on general_journal_entry_id and voucher
Consider pagination for journals with many lines
Tax calculations performed during posting, not during query
Response time typically < 100ms for standard journals

Security Considerations

Requires authentication for all requests
Only authorized users can query tax transactions
Tax transactions are read-only via this endpoint
Audit logging for all tax transaction queries
No sensitive tax calculation logic exposed in responses

Overview​

Base URL​

Authentication​

Endpoints​

Get Tax Transactions for Journal​

Tax Calculation Logic​

Intersection-Based Tax Determination​

Example Scenario​

Tax Direction​

Usage Examples​

Successful Query - Single Tax Transaction​

Successful Query - Multiple Tax Transactions​

Query with No Tax Transactions​

Integration with Journal Posting​

Pre-Posting​

During Posting​

Post-Posting​

Business Rules​

Related Endpoints​

Testing Considerations​

Test Scenarios​

Verification Checklist​

Performance Considerations​

Security Considerations​