Tax Periods

Overview

The Tax Periods API provides comprehensive functionality for managing tax reporting periods and their associated headers. This API enables the creation, configuration, and management of tax period templates and individual reporting periods required for tax compliance across different jurisdictions.

Base URL

/tax/tax-periods

Key Concepts

• Tax Period Header: Template defining how tax periods are calculated (duration, frequency)
• Tax Period: Individual reporting period with specific start/end dates and status
• Tax Authority: Governmental entity that governs the tax periods
• Duration Units: Days, Months, or Years used for period calculations

---

Endpoints Summary

Method	Endpoint	Purpose
GET	/tax/tax-periods	Retrieve all tax period headers
GET	/tax/tax-periods/{id}	Retrieve specific tax period header
POST	/tax/tax-periods	Create new tax period header
PUT	/tax/tax-periods/{id}	Update existing tax period header
POST	/tax/tax-periods/{headerid}/periods	Create individual tax period
DELETE	/tax/tax-periods/{headerid}/periods	Remove tax period
POST	/tax/tax-periods/generate-next-period/{headerid}	Generate next sequential period
GET	/tax/tax-periods/duration-units	Get available duration units
GET	/tax/tax-periods/periods/{periodid}/transactions	Get tax transactions for period

---

Commands

1. Create Tax Period Header

Creates a new tax period header that serves as a template for generating tax periods.

Request

POST /tax/tax-periods
Content-Type: application/json

Request Body

{
  "name": "Monthly VAT Returns",
  "durationUnitId": 2,
  "duration": 1,
  "taxAuthorityId": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}

Request Schema

Field	Type	Required	Description
name	string	Yes	Unique name for the tax period header
durationUnitId	integer	Yes	Duration unit (1=Days, 2=Months, 3=Years)
duration	integer	Yes	Number of duration units per period
taxAuthorityId	guid	Yes	ID of the governing tax authority

Response

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "name": "Monthly VAT Returns",
  "durationUnitName": "Months",
  "durationUnitId": 2,
  "duration": 1,
  "taxAuthorityId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "taxAuthorityName": "HM Revenue and Customs",
  "periods": [],
  "createdAt": "2023-11-15T10:30:00Z",
  "modifiedAt": "2023-11-15T10:30:00Z"
}

Status Codes

• 201 Created: Header successfully created
• 400 Bad Request: Invalid request data or validation failure
• 404 Not Found: Tax authority not found
• 409 Conflict: Header name already exists

Business Rules

• Header name must be unique across the system
• Tax authority must exist and be valid
• Duration must be greater than 0
• Duration unit must be valid enumeration value

---

2. Update Tax Period Header

Updates an existing tax period header configuration.

Request

PUT /tax/tax-periods/{id}
Content-Type: application/json

Request Body

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "name": "Quarterly VAT Returns",
  "durationUnitId": 2,
  "duration": 3,
  "taxAuthorityId": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}

Response

Same as Create Tax Period Header response with updated values.

Status Codes

• 200 OK: Header successfully updated
• 400 Bad Request: Invalid request data or ID mismatch
• 404 Not Found: Header or tax authority not found
• 409 Conflict: Name conflicts with existing header

Business Rules

• ID in URL must match ID in request body
• Name uniqueness validated (excluding current header)
• Cannot modify header if it has closed periods (business rule enforcement)

---

3. Create Tax Period

Creates an individual tax period within an existing header.

Request

POST /tax/tax-periods/{taxPeriodHeaderId}/periods
Content-Type: application/json

Request Body

{
  "fromDate": "2023-11-01T00:00:00Z",
  "toDate": "2023-11-30T23:59:59Z"
}

Request Schema

Field	Type	Required	Description
fromDate	datetime	Yes	Start date and time of the period
toDate	datetime	Yes	End date and time of the period

Response

{
  "id": "4fa85f64-5717-4562-b3fc-2c963f66afa6",
  "fromDate": "2023-11-01T00:00:00Z",
  "toDate": "2023-11-30T23:59:59Z",
  "statusName": "Open",
  "status": 0,
  "taxPeriodHeaderId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "taxAuthorityId": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}

Status Codes

• 201 Created: Period successfully created
• 400 Bad Request: Invalid dates or overlapping period
• 404 Not Found: Tax period header not found

Business Rules

• Period dates cannot overlap with existing periods in the same header
• FromDate must be before ToDate
• Header must exist and be valid

---

4. Generate Next Tax Period

Automatically generates the next sequential tax period based on the header's configuration.

Request

POST /tax/tax-periods/generate-next-period/{taxPeriodHeaderId}

Response

Same as Create Tax Period response.

Status Codes

• 200 OK: Next period successfully generated
• 400 Bad Request: Cannot calculate next period (no existing periods)
• 404 Not Found: Tax period header not found

Business Rules

• Requires at least one existing period to calculate the next interval
• Automatically calculates start date as the day after the latest period's end date
• Uses header's duration configuration to calculate end date

---

5. Remove Tax Period

Removes an existing tax period from a header.

Request

DELETE /tax/tax-periods/{taxPeriodHeaderId}/periods
Content-Type: application/json

Request Body

{
  "taxPeriodHeaderId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "taxPeriodId": "4fa85f64-5717-4562-b3fc-2c963f66afa6"
}

Response

200 OK

Status Codes

• 200 OK: Period successfully removed
• 400 Bad Request: Period cannot be removed (closed status) or doesn't exist
• 404 Not Found: Tax period header not found

Business Rules

• Only open (non-closed) periods can be removed
• Period must exist within the specified header
• Closed periods cannot be removed to maintain audit integrity

---

6. Settle and Post Sales Tax

Initiates the settlement process for a tax period, creating a journal to post the tax amounts.

Request

PUT /tax/tax-periods/{taxPeriodId}/settle-and-post-sales-tax
Content-Type: application/json

Request Body

{
  "tax_period_header_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "from_date": "2023-11-01T00:00:00Z",
  "transaction_date": "2023-12-15T00:00:00Z"
}

Request Schema

Field	Type	Required	Description
tax_period_header_id	guid	Yes	ID of the parent tax period header
from_date	datetime	Yes	Start date of the tax period to settle
transaction_date	datetime	Yes	The date to use for the settlement journal

Response

{
  "journal_id": "c4d5e6f7-a8b9-c0d1-e2f3-a4b5c6d7e8f9"
}

Status Codes

• 200 OK: Settlement process initiated successfully, returns the new journal ID.
• 400 Bad Request: Invalid request data.
• 404 Not Found: Tax period header not found.

---

Queries

1. Get Tax Period Headers

Retrieves all tax period headers, optionally filtered by tax authority.

Request

GET /tax/tax-periods?taxAuthorityId={guid}

Query Parameters

Parameter	Type	Required	Description
taxAuthorityId	guid	No	Filter by specific tax authority

Response

[
  {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "name": "Monthly VAT Returns",
    "durationUnitName": "Months",
    "durationUnitId": 2,
    "duration": 1,
    "taxAuthorityId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "taxAuthorityName": "HM Revenue and Customs",
    "periods": [
      {
        "id": "4fa85f64-5717-4562-b3fc-2c963f66afa6",
        "fromDate": "2023-11-01T00:00:00Z",
        "toDate": "2023-11-30T23:59:59Z",
        "statusName": "Open",
        "status": 0,
        "taxPeriodHeaderId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "taxAuthorityId": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
      }
    ],
    "createdAt": "2023-11-15T10:30:00Z",
    "modifiedAt": "2023-11-15T10:30:00Z"
  }
]

Status Codes

• 200 OK: Headers successfully retrieved

---

2. Get Tax Period Header

Retrieves a specific tax period header by ID, including all its periods.

Request

GET /tax/tax-periods/{id}

Response

Same structure as single item from Get Tax Period Headers.

Status Codes

• 200 OK: Header successfully retrieved
• 404 Not Found: Header with specified ID not found

---

3. Get Duration Units

Retrieves all available duration units for tax period configuration.

Request

GET /tax/tax-periods/duration-units

Response

[
  {
    "id": 1,
    "name": "Days"
  },
  {
    "id": 2,
    "name": "Months"
  },
  {
    "id": 3,
    "name": "Years"
  }
]

Status Codes

• 200 OK: Duration units successfully retrieved

---

4. Get Tax Transactions for Settlement Period

Retrieves tax transactions that occurred within a specific tax period for settlement purposes.

Request

GET /tax/tax-periods/periods/{taxPeriodId}/transactions?includeDetails=true&limit=100

Query Parameters

Parameter	Type	Required	Default	Description
includeDetails	boolean	No	true	Include detailed transaction information
limit	integer	No	null	Maximum number of transactions to return

Response

[
  {
    "id": "5fa85f64-5717-4562-b3fc-2c963f66afa6",
    "currencyCode": "GBP",
    "invoiceId": "INV-2023-001",
    "journalNumber": "GJ-2023-001",
    "voucher": "V-2023-001",
    "taxCodeId": "6fa85f64-5717-4562-b3fc-2c963f66afa6",
    "taxCodeName": "VAT-STANDARD",
    "taxGroupId": "7fa85f64-5717-4562-b3fc-2c963f66afa6",
    "taxGroupName": "UK-VAT",
    "taxItemGroupId": "8fa85f64-5717-4562-b3fc-2c963f66afa6",
    "taxItemGroupName": "STANDARD-ITEMS",
    "taxAmount": 200.00,
    "sourceAmount": 1000.00,
    "sourceDocumentLineId": "9fa85f64-5717-4562-b3fc-2c963f66afa6",
    "sourceRecordId": "afa85f64-5717-4562-b3fc-2c963f66afa6",
    "sourceName": "Sales Invoice",
    "transactionDate": "2023-11-15T14:30:00Z",
    "taxDirection": "Output Tax",
    "taxValue": 20.0,
    "generalJournalEntryId": "bfa85f64-5717-4562-b3fc-2c963f66afa6",
    "documentNumber": "DOC-2023-001"
  }
]

Status Codes

• 200 OK: Transactions successfully retrieved
• 404 Not Found: Tax period not found

---

Common Error Responses

Validation Error (400 Bad Request)

{
  "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1",
  "title": "One or more validation errors occurred.",
  "status": 400,
  "errors": {
    "Name": ["The Name field is required."],
    "Duration": ["Duration must be greater than 0."]
  }
}

Not Found Error (404 Not Found)

{
  "type": "https://tools.ietf.org/html/rfc7231#section-6.5.4",
  "title": "Resource not found.",
  "status": 404,
  "detail": "Tax Period Header with ID '3fa85f64-5717-4562-b3fc-2c963f66afa6' was not found."
}

Conflict Error (409 Conflict)

{
  "type": "https://tools.ietf.org/html/rfc7231#section-6.5.8",
  "title": "Resource conflict.",
  "status": 409,
  "detail": "A Tax Period Header with name 'Monthly VAT Returns' already exists."
}

---

Usage Examples

Complete Tax Period Setup Workflow

1. Create Tax Period Header

curl -X POST /tax/tax-periods \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Monthly VAT Returns",
    "durationUnitId": 2,
    "duration": 1,
    "taxAuthorityId": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
  }'

2. Create First Period

curl -X POST /tax/tax-periods/3fa85f64-5717-4562-b3fc-2c963f66afa6/periods \
  -H "Content-Type: application/json" \
  -d '{
    "fromDate": "2023-11-01T00:00:00Z",
    "toDate": "2023-11-30T23:59:59Z"
  }'

3. Generate Next Period

curl -X POST /tax/tax-periods/generate-next-period/3fa85f64-5717-4562-b3fc-2c963f66afa6

4. Get Tax Transactions for Period

curl -X GET /tax/tax-periods/periods/4fa85f64-5717-4562-b3fc-2c963f66afa6/transactions?includeDetails=true

---

Integration Notes

Prerequisites

• Tax Authority must be created before creating tax period headers
• Appropriate permissions for tax management operations
• Valid authentication and authorization headers

Related APIs

• Tax Authorities API: /tax/tax-authorities
• Tax Codes API: /tax/tax-codes
• Tax Groups API: /tax/tax-groups

Workflow Considerations

• Create tax period headers during initial system setup
• Generate periods as needed for upcoming reporting cycles
• Close periods after tax filing to prevent modifications
• Use transaction queries for tax return preparation and audit purposes

---

Data Models

TaxPeriodHeaderViewModel

Property	Type	Description
id	guid	Unique identifier
name	string	Header name
durationUnitName	string	Human-readable duration unit
durationUnitId	integer	Duration unit enumeration
duration	integer	Number of units per period
taxAuthorityId	guid	Associated tax authority
taxAuthorityName	string	Tax authority name
periods	array	Collection of tax periods
createdAt	datetime	Creation timestamp
modifiedAt	datetime	Last modification timestamp

TaxPeriodViewModel

Property	Type	Description
id	guid	Unique identifier
fromDate	datetime	Period start date
toDate	datetime	Period end date
statusName	string	Human-readable status
status	integer	Status enumeration (0=Open, 1=Closed)
taxPeriodHeaderId	guid	Parent header ID
taxAuthorityId	guid	Associated tax authority

TaxTransactionViewModel

Property	Type	Description
id	guid	Unique identifier
currencyCode	string	Transaction currency
invoiceId	string	Related invoice identifier
journalNumber	string	Journal entry number
voucher	string	Voucher number
taxCodeId	guid	Applied tax code
taxCodeName	string	Tax code name
taxGroupId	guid	Applied tax group
taxGroupName	string	Tax group name
taxItemGroupId	guid	Applied tax item group
taxItemGroupName	string	Tax item group name
taxAmount	decimal	Calculated tax amount
sourceAmount	decimal	Original transaction amount
transactionDate	datetime	Transaction date
taxDirection	string	Tax direction (Input/Output)
taxValue	decimal	Tax percentage rate
documentNumber	string	Source document number