Tax Settlements

Overview

The Tax Settlements API provides functionality for querying tax settlement records (also known as sales tax payment vouchers. Tax settlements are created when the "Settle and Post Sales Tax" process is executed, providing an official audit trail of tax reporting and payment obligations.

Base URL

/tax/tax-settlements

Key Concepts

Tax Settlement: Official record of a tax settlement run
Settlement Counter: Tracks corrections and adjustments (1 = original, 2 = first correction, etc.)
Settlement Journal: The ledger journal created during the settlement process
Unsettled Transactions: Tax transactions that haven't yet been included in a settlement
Corrections Workflow: Ability to re-run settlement for the same period to include new or corrected transactions

Endpoints Summary

Method	Endpoint	Purpose
GET	`/tax/tax-settlements`	Retrieve all tax settlements with filtering
GET	`/tax/tax-settlements/by-period/{taxPeriodId}`	Retrieve settlements for specific period

Queries

1. Get Tax Settlements

Retrieves all tax settlements with optional filtering by tax period header or transaction date range.

Request

GET /tax/tax-settlements?taxPeriodHeaderId={guid}&startDate={date}&endDate={date}

Query Parameters

Parameter	Type	Required	Description
`taxPeriodHeaderId`	guid	No	Filter by specific tax period header (e.g., all settlements for "UAE VAT Quarterly")
`startDate`	datetime	No	Filter by settlement transaction date (start of range)
`endDate`	datetime	No	Filter by settlement transaction date (end of range)

Response

[
  {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "taxPeriodId": "1a2b3c4d-5e6f-7890-abcd-ef1234567890",
    "fromDate": "2025-01-01T00:00:00Z",
    "toDate": "2025-03-31T23:59:59Z",
    "transactionDate": "2025-04-15T10:30:00Z",
    "voucherNumber": "VAT-2025-Q1-001",
    "settlementJournalId": "2b3c4d5e-6f78-9012-3456-789012345678",
    "settlementCounter": 1,
    "periodDisplayValue": "2025-Q1",
    "taxPeriodHeaderName": "UAE VAT Quarterly"
  },
  {
    "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
    "taxPeriodId": "1a2b3c4d-5e6f-7890-abcd-ef1234567890",
    "fromDate": "2025-01-01T00:00:00Z",
    "toDate": "2025-03-31T23:59:59Z",
    "transactionDate": "2025-04-20T14:15:00Z",
    "voucherNumber": "VAT-2025-Q1-002",
    "settlementJournalId": "3c4d5e6f-7890-1234-5678-901234567890",
    "settlementCounter": 2,
    "periodDisplayValue": "2025-Q1",
    "taxPeriodHeaderName": "UAE VAT Quarterly"
  }
]

Response Schema

Property	Type	Description
`id`	guid	Unique identifier of the tax settlement
`taxPeriodId`	guid	ID of the tax period this settlement applies to
`fromDate`	datetime	Start date of the settlement period
`toDate`	datetime	End date of the settlement period
`transactionDate`	datetime	Date when the settlement was posted
`voucherNumber`	string	Voucher number of the settlement journal
`settlementJournalId`	guid	ID of the ledger journal created for this settlement
`settlementCounter`	integer	Settlement run number for this period (1, 2, 3...)
`periodDisplayValue`	string	Display name of the tax period (e.g., "2025-Q1", "2025-01")
`taxPeriodHeaderName`	string	Name of the parent tax period header (e.g., "UAE VAT Quarterly")

Status Codes

200 OK: Settlements successfully retrieved (returns empty array if none found)

Usage Examples

Get all settlements:

curl -X GET /tax/tax-settlements

Get settlements for specific tax period header:

curl -X GET /tax/tax-settlements?taxPeriodHeaderId=1a2b3c4d-5e6f-7890-abcd-ef1234567890

Get settlements for Q1 2025:

curl -X GET /tax/tax-settlements?startDate=2025-01-01&endDate=2025-03-31

Get settlements for UAE VAT in Q1 2025:

curl -X GET /tax/tax-settlements?taxPeriodHeaderId=1a2b3c4d-5e6f-7890-abcd-ef1234567890&startDate=2025-01-01&endDate=2025-03-31

2. Get Tax Settlements By Period

Retrieves all tax settlements for a specific tax period, including the original settlement and any corrections.

Request

GET /tax/tax-settlements/by-period/{taxPeriodId}

Path Parameters

Parameter	Type	Required	Description
`taxPeriodId`	guid	Yes	ID of the tax period to retrieve settlements for

Response

[
  {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "taxPeriodId": "1a2b3c4d-5e6f-7890-abcd-ef1234567890",
    "fromDate": "2025-01-01T00:00:00Z",
    "toDate": "2025-03-31T23:59:59Z",
    "transactionDate": "2025-04-15T10:30:00Z",
    "voucherNumber": "VAT-2025-Q1-001",
    "settlementJournalId": "2b3c4d5e-6f78-9012-3456-789012345678",
    "settlementCounter": 1,
    "periodDisplayValue": "2025-Q1",
    "taxPeriodHeaderName": "UAE VAT Quarterly"
  },
  {
    "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
    "taxPeriodId": "1a2b3c4d-5e6f-7890-abcd-ef1234567890",
    "fromDate": "2025-01-01T00:00:00Z",
    "toDate": "2025-03-31T23:59:59Z",
    "transactionDate": "2025-04-20T14:15:00Z",
    "voucherNumber": "VAT-2025-Q1-002",
    "settlementJournalId": "3c4d5e6f-7890-1234-5678-901234567890",
    "settlementCounter": 2,
    "periodDisplayValue": "2025-Q1",
    "taxPeriodHeaderName": "UAE VAT Quarterly"
  }
]

Response Schema

Same as Get Tax Settlements response.

Status Codes

200 OK: Settlements successfully retrieved (returns empty array if none found)

Usage Examples

Get all settlements for a period (original + corrections):

curl -X GET /tax/tax-settlements/by-period/1a2b3c4d-5e6f-7890-abcd-ef1234567890

Business Workflows

Understanding Settlement Counter

The settlementCounter field tracks multiple settlement runs for the same tax period:

Initial Settlement (Counter = 1)
- First settlement run for a period
- Includes all unsettled tax transactions for the period
- Creates settlement journal and stamps all included transactions
First Correction (Counter = 2)
- Additional transactions posted to the same period after initial settlement
- Re-running settlement only processes transactions where TaxSettlementId is null
- Creates new settlement journal with only the new transactions
- Settlement counter increments to 2
Subsequent Corrections (Counter = 3, 4, ...)
- Each re-run creates a new settlement with incremented counter
- System maintains complete audit trail of all settlements

Corrections Workflow Example

Scenario: Company settles Q1 2025 VAT, then discovers a missed invoice

April 15: Run "Settle and Post Sales Tax" for Q1 2025
- Settlement Counter = 1
- All Q1 transactions stamped with Settlement ID
- Settlement journal created with voucher VAT-2025-Q1-001
April 18: Discover missing invoice from March 15
- Post corrected invoice (backdated to March 15)
- Tax transaction created but TaxSettlementId = null (unsettled)
April 20: Re-run "Settle and Post Sales Tax" for Q1 2025
- Settlement Counter = 2
- System only processes transactions where TaxSettlementId is null
- New settlement journal created with voucher VAT-2025-Q1-002
- Only the corrected transaction is included
Query settlements for Q1 2025:
```
GET /tax/tax-settlements/by-period/{q1-2025-period-id}
```
Returns both settlements (counter 1 and counter 2)

Integration with Other APIs

Tax Transactions API

Use TaxSettlementId field to identify which settlement includes a transaction
Transactions with null TaxSettlementId are unsettled

Tax Periods API

Use /tax/tax-periods/{taxPeriodId}/settle-and-post-sales-tax to create settlements
Get settlements for a period using this API

Ledger Journals API

Settlement journals can be queried using settlementJournalId
View detailed accounting entries for each settlement

Usage Scenarios

1. VAT Return Preparation

Query all settlements for a reporting period to prepare VAT return:

# Get all settlements for UAE VAT in 2025
curl -X GET /tax/tax-settlements?taxPeriodHeaderId={uae-vat-header-id}&startDate=2025-01-01&endDate=2025-12-31

Use the results to:

Identify all settlement vouchers for the year
Verify settlement dates and amounts
Cross-reference with filed VAT returns

2. Audit Trail Review

Review complete settlement history for a specific period:

# Get all settlements for Q1 2025 (including corrections)
curl -X GET /tax/tax-settlements/by-period/{q1-2025-period-id}

The response shows:

Original settlement (counter 1)
All corrections (counter 2, 3, etc.)
Transaction dates showing when each settlement was posted
Voucher numbers for tracing in GL

3. Reconciliation

Verify that all tax transactions for a period have been settled:

Query settlements for period:

GET /tax/tax-settlements/by-period/{period-id}

Query tax transactions for period:

GET /tax/tax-periods/periods/{period-id}/transactions

Verify: All transactions should have TaxSettlementId matching one of the settlements

4. Corrections Monitoring

Monitor which periods have had corrections:

# Get all settlements
curl -X GET /tax/tax-settlements?taxPeriodHeaderId={header-id}

Filter results where settlementCounter > 1 to identify periods with corrections.

Data Model

TaxSettlementViewModel

Property	Type	Nullable	Description
`id`	guid	No	Unique identifier of the settlement
`taxPeriodId`	guid	No	ID of the tax period
`fromDate`	datetime	No	Start date of the settlement period
`toDate`	datetime	No	End date of the settlement period
`transactionDate`	datetime	No	Date when settlement was posted
`voucherNumber`	string	No	Settlement journal voucher number
`settlementJournalId`	guid	No	ID of the settlement journal
`settlementCounter`	integer	No	Settlement run number (1, 2, 3...)
`periodDisplayValue`	string	No	Display name of the period
`taxPeriodHeaderName`	string	No	Name of the tax period header

Tax Periods API: /tax/tax-periods - Create and manage tax periods
Tax Codes API: /tax/tax-codes - Configure tax codes and rates
Tax Transactions API: /tax/tax-transactions - Query detailed tax transaction data
General Journals API: /general-journals - View settlement journal details

Integration Notes

Prerequisites

Tax periods must be configured before settlements can be created
Tax codes and posting groups must be properly set up
Settlement process is initiated via Tax Periods API

Best Practices

Query by Period: Use /by-period/{taxPeriodId} for period-specific queries
Date Range Filtering: Use date parameters for reporting period queries
Settlement Counter: Monitor counter > 1 to identify corrections
Cross-Reference: Use settlementJournalId to link to GL postings

Performance Considerations

Results are ordered by transaction date (descending) and settlement counter
Navigation properties (TaxPeriod, TaxPeriodHeader) are pre-loaded for efficiency
No pagination required - settlements are typically low-volume data

Compliance and Audit

Audit Trail Components

Each settlement provides:

Unique Identifier: Permanent record ID
Timestamp: Exact date/time of settlement posting
Voucher Reference: Links to GL accounting entries
Period Reference: Links to tax reporting period
Counter: Tracks corrections and adjustments

Regulatory Requirements

This API supports:

VAT Return Filing: Query settlements to prepare returns
Tax Authority Audits: Complete settlement history available
Period Corrections: Transparent tracking of adjustments
Reconciliation: Verify all transactions are settled

D365 F&O Migration

When migrating from D365 F&O:

Map TaxReportVoucher table to Tax Settlements
Preserve settlement counter values
Maintain voucher number references
Verify tax transaction stamps (TaxSettlementId)

Overview​

Base URL​

Key Concepts​

Endpoints Summary​

Queries​

1. Get Tax Settlements​

Request​

Query Parameters​

Response​

Response Schema​

Status Codes​

Usage Examples​

2. Get Tax Settlements By Period​

Request​

Path Parameters​

Response​

Response Schema​

Status Codes​

Usage Examples​

Business Workflows​

Understanding Settlement Counter​

Corrections Workflow Example​

Integration with Other APIs​

Usage Scenarios​

1. VAT Return Preparation​

2. Audit Trail Review​

3. Reconciliation​

4. Corrections Monitoring​

Data Model​

TaxSettlementViewModel​

Related APIs​

Integration Notes​

Prerequisites​

Best Practices​

Performance Considerations​

Compliance and Audit​

Audit Trail Components​

Regulatory Requirements​

D365 F&O Migration​

Overview

Base URL

Key Concepts

Endpoints Summary

Queries

1. Get Tax Settlements

Request

Query Parameters

Response

Response Schema

Status Codes

Usage Examples

2. Get Tax Settlements By Period

Request

Path Parameters

Response

Response Schema

Status Codes

Usage Examples

Business Workflows

Understanding Settlement Counter

Corrections Workflow Example

Integration with Other APIs

Usage Scenarios

1. VAT Return Preparation

2. Audit Trail Review

3. Reconciliation

4. Corrections Monitoring

Data Model

TaxSettlementViewModel

Related APIs

Integration Notes

Prerequisites

Best Practices

Performance Considerations

Compliance and Audit

Audit Trail Components

Regulatory Requirements

D365 F&O Migration