Tax Deletion

Overview

The Tax Deletion API provides endpoints for safely deleting tax-related entities in the General Ledger module. Each endpoint implements comprehensive validation to ensure referential integrity and audit trail preservation.

Base URL

/api/v1/general-ledger

Authentication

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

Authorization: Bearer <jwt-token>

Endpoints

Delete Tax Posting Group

Deletes a tax posting group if it is not assigned to any tax codes.

Endpoint: DELETE /tax-posting-groups/{taxPostingGroupId}

Parameters:

• taxPostingGroupId (UUID, required): The ID of the tax posting group to delete

Request Example:

DELETE /api/v1/general-ledger/tax-posting-groups/550e8400-e29b-41d4-a716-446655440000
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Success Response:

• Code: 204 No Content
• Description: Tax posting group successfully deleted

Error Responses:

• Code: 404 Not Found

  {
    "error": "Tax posting group with ID 550e8400-e29b-41d4-a716-446655440000 not found"
  }

• Code: 409 Conflict (Business Rule Violation)

  {
    "error": "Cannot delete tax posting group 'VAT-STANDARD' because it is currently being used. Usage found: Assigned to 3 tax code(s): TC001, TC002, TC003",
    "usageViolations": [
      "Assigned to 3 tax code(s): TC001, TC002, TC003"
    ],
    "entityId": "550e8400-e29b-41d4-a716-446655440000",
    "entityName": "VAT-STANDARD"
  }

Delete Tax Code

Deletes a tax code if it is not a member of any tax groups or tax item groups and has not been used in any transactions.

Endpoint: DELETE /tax-codes/{taxCodeId}

Parameters:

• taxCodeId (UUID, required): The ID of the tax code to delete

Request Example:

DELETE /api/v1/general-ledger/tax-codes/650e8400-e29b-41d4-a716-446655440000
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Success Response:

• Code: 204 No Content
• Description: Tax code successfully deleted

Error Responses:

• Code: 409 Conflict (Multiple Usage Types)

  {
    "error": "Cannot delete tax code 'VAT-20' because it is currently being used. Usage found: Member of 2 tax group(s): TG001, TG002; Member of 1 tax item group(s): TIG001; Referenced in 15 ledger journal line(s)",
    "usageViolations": [
      "Member of 2 tax group(s): TG001, TG002",
      "Member of 1 tax item group(s): TIG001", 
      "Referenced in 15 ledger journal line(s)"
    ],
    "entityId": "650e8400-e29b-41d4-a716-446655440000",
    "entityName": "VAT-20"
  }

Delete Tax Group

Deletes a tax group if it is not assigned to any customers or vendors and has not been used in any transactions.

Endpoint: DELETE /tax-groups/{taxGroupId}

Parameters:

• taxGroupId (UUID, required): The ID of the tax group to delete

Request Example:

DELETE /api/v1/general-ledger/tax-groups/750e8400-e29b-41d4-a716-446655440000
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Success Response:

• Code: 204 No Content
• Description: Tax group successfully deleted

Error Responses:

• Code: 409 Conflict (Cross-Module Usage)

  {
    "error": "Cannot delete tax group 'VAT-DOMESTIC' because it is currently being used. Usage found: AccountsReceivable: Assigned to 5 customer(s): C001, C002 and 3 others; AccountsPayable: Used in 8 purchase invoice(s); GeneralLedger: Referenced in 12 ledger journal line(s)",
    "usageViolations": [
      "AccountsReceivable: Assigned to 5 customer(s): C001, C002 and 3 others",
      "AccountsPayable: Used in 8 purchase invoice(s)",
      "GeneralLedger: Referenced in 12 ledger journal line(s)"
    ],
    "entityId": "750e8400-e29b-41d4-a716-446655440000", 
    "entityName": "VAT-DOMESTIC"
  }

Delete Tax Item Group

Deletes a tax item group if it is not assigned to any items/products and has not been used in any transactions.

Endpoint: DELETE /tax-item-groups/{taxItemGroupId}

Parameters:

• taxItemGroupId (UUID, required): The ID of the tax item group to delete

Request Example:

DELETE /api/v1/general-ledger/tax-item-groups/850e8400-e29b-41d4-a716-446655440000
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Success Response:

• Code: 204 No Content
• Description: Tax item group successfully deleted

Error Responses:

• Code: 409 Conflict (Inventory Assignment)

  {
    "error": "Cannot delete tax item group 'STANDARD-ITEMS' because it is currently being used. Usage found: Inventory: Assigned to 25 item(s): ITEM001, ITEM002, ITEM003 and 22 others; AccountsReceivable: Used in 45 sales invoice line(s)",
    "usageViolations": [
      "Inventory: Assigned to 25 item(s): ITEM001, ITEM002, ITEM003 and 22 others",
      "AccountsReceivable: Used in 45 sales invoice line(s)"
    ],
    "entityId": "850e8400-e29b-41d4-a716-446655440000",
    "entityName": "STANDARD-ITEMS"
  }

Common Error Responses

Validation Errors

• Code: 400 Bad Request

  {
    "error": "Validation failed",
    "details": [
      {
        "field": "taxGroupId",
        "message": "Tax Group ID is required"
      }
    ]
  }

Authentication Errors

• Code: 401 Unauthorized

  {
    "error": "Authentication required"
  }

Authorization Errors

• Code: 403 Forbidden

  {
    "error": "Insufficient permissions to delete tax entities"
  }

Server Errors

• Code: 500 Internal Server Error

  {
    "error": "An unexpected error occurred while processing the deletion",
    "requestId": "req_123456789"
  }

Validation Flow

Usage Examples

Successful Deletion

curl -X DELETE \
  https://api.example.com/api/v1/general-ledger/tax-groups/750e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json"

Response:

HTTP/1.1 204 No Content

Blocked Deletion

curl -X DELETE \
  https://api.example.com/api/v1/general-ledger/tax-groups/750e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json"

Response:

HTTP/1.1 409 Conflict
Content-Type: application/json

{
  "error": "Cannot delete tax group 'VAT-DOMESTIC' because it is currently being used. Usage found: AccountsReceivable: Assigned to 3 customer(s): C001, C002, C003",
  "usageViolations": [
    "AccountsReceivable: Assigned to 3 customer(s): C001, C002, C003"
  ],
  "entityId": "750e8400-e29b-41d4-a716-446655440000",
  "entityName": "VAT-DOMESTIC"
}

Rate Limiting

All deletion endpoints are subject to rate limiting:

• Rate Limit: 100 requests per hour per authenticated user
• Headers: Response includes rate limit information

  X-RateLimit-Limit: 100
  X-RateLimit-Remaining: 95
  X-RateLimit-Reset: 1640995200

Audit Logging

All deletion attempts are logged for audit purposes:

• Successful Deletions: Logged with user, timestamp, and entity details
• Blocked Deletions: Logged with user, timestamp, entity details, and blocking reasons
• Error Conditions: Logged with error details and context

Best Practices

Before Deletion

1. Check Dependencies: Use the corresponding GET endpoints to understand entity relationships
2. Remove Usage First: Update master data and complete transactions before attempting deletion
3. Backup Considerations: Consider creating backups of critical tax configurations

Error Handling

1. Parse Usage Violations: Use the usageViolations array for detailed user feedback
2. Implement Retry Logic: For server errors, implement exponential backoff
3. User Experience: Present blocking reasons clearly to help users resolve issues

Integration Patterns

1. Bulk Operations: For multiple deletions, implement client-side batching with appropriate delays
2. Dependency Resolution: Delete entities in correct order (TaxCode before TaxPostingGroup)
3. Validation Caching: Cache validation results for improved performance in bulk scenarios