The Delete Tax endpoint allows you to permanently remove tax configurations from your business. This operation is irreversible and should be used carefully, as it will affect any applications or transactions that reference the deleted tax.

​
Endpoint Details

  • URL: /api/v0/taxes/{tax_id}
  • Method: DELETE
  • Authentication: Required (API Key Authentication)
  • Content-Type: application/json

​
Authentication

This endpoint requires API key authentication using:
  • x-client-key: Your API client key
  • x-client-secret: Your API client secret

​
Path Parameters

ParameterTypeDescriptionRequired
tax_idstringUnique identifier for the taxYes

​
Response

​
Success Response (204 No Content)

When a tax is successfully deleted, the API returns a 204 No Content status with an empty response body. This indicates that the tax has been permanently removed.

​
Confirmation Response (200 OK)

Some implementations may return a confirmation response: 
{
  "message": "Tax successfully deleted",
  "tax_id": "123e4567-e89b-12d3-a456-426614174000",
  "deleted_at": "2024-01-25T16:30:00.000Z"
}

​
Example Requests

curl -X DELETE "https://api.devdraft.ai/api/v0/taxes/123e4567-e89b-12d3-a456-426614174000" \
  -H "x-client-key: your-client-key" \
  -H "x-client-secret: your-client-secret"

​
Error Responses

{
  "statusCode": 404,
  "message": "Tax not found",
  "error": "Not Found"
}

​
Safety Considerations

Irreversible Action: Once a tax is deleted, it cannot be recovered. All configuration data will be permanently lost.
Application Impact: Deleting a tax may affect applications that reference it. Ensure proper cleanup before deletion.

​
Pre-Deletion Checklist

1

Verify Tax Status

Ensure the tax is inactive and not currently being used in transactions.
2

Check Application Associations

Verify that no applications are associated with this tax.
3

Review Transaction History

Check if the tax has been used in historical transactions that may need references.
4

Backup Configuration

Export tax configuration details in case you need to recreate it later.
5

Notify Stakeholders

Inform relevant team members about the tax deletion, especially if it affects shared resources.

​
Alternative Actions

Before deleting a tax, consider these alternatives:
Safer Option: Deactivate the tax by setting active: false instead of deleting it.
// Deactivate tax instead of deleting
await updateTax(taxId, { active: false });
Benefits:
  • Preserves historical configuration
  • Can be reactivated if needed later
  • Maintains referential integrity
  • Safer than permanent deletion
Gradual Cleanup: Remove application associations first, then delete after validation.
// Remove all application associations
await updateTax(taxId, { appIds: [] });

// Wait and verify no active usage
// Then delete if confirmed safe
Use Cases:
  • Gradual migration to new tax configurations
  • Testing impact before full deletion
  • Staged cleanup process
Export Before Delete: Save tax configuration for future reference.
// Export tax configuration
const tax = await getTax(taxId);
const archiveData = {
  original_id: tax.id,
  name: tax.name,
  percentage: tax.percentage,
  description: tax.description,
  archived_at: new Date().toISOString(),
  archived_reason: 'Business restructuring'
};

// Save to your archive system
await saveToArchive(archiveData);

// Then delete original
await deleteTax(taxId);

​
Validation Before Deletion

​
Safety Checks

  • Safe: Tax is inactive (active: false)
  • Unsafe: Tax is still active and may be used in new transactions
  • Recommendation: Deactivate tax first, wait for confirmation, then delete
  • Safe: Tax has no associated applications (apps: [])
  • Unsafe: Tax is associated with one or more applications
  • Recommendation: Remove all application associations before deletion
  • Safe: Tax hasn’t been used recently or was created long ago
  • Warning: Recently created or recently used taxes
  • Recommendation: Review usage patterns before deletion
  • Consider: Whether historical transactions reference this tax
  • Impact: Deletion won’t affect historical data but may impact reporting
  • Recommendation: Verify reporting systems can handle missing tax references

​
Batch Operations

​
Cleanup Scenarios

const cleanupDevelopmentTaxes = async () => {
  const taxes = await listTaxes();
  
  // Find development/test taxes
  const devTaxes = taxes.filter(tax => 
    tax.name.toLowerCase().includes('test') ||
    tax.name.toLowerCase().includes('dev') ||
    tax.name.toLowerCase().includes('staging') ||
    !tax.active && tax.apps.length === 0
  );
  
  console.log(`Found ${devTaxes.length} development taxes`);
  
  // Delete development taxes
  for (const tax of devTaxes) {
    try {
      await deleteTax(tax.id);
      console.log(`Deleted development tax: ${tax.name}`);
    } catch (error) {
      console.error(`Failed to delete ${tax.name}: ${error.message}`);
    }
  }
};

​
Best Practices

  • Always validate tax status and associations before deletion
  • Implement confirmation steps for deletion operations
  • Use batch operations carefully with proper error handling
  • Consider deactivation as an alternative to deletion
  • Log all tax deletions with user information and timestamps
  • Maintain records of deleted taxes for audit purposes
  • Document reasons for deletion in audit logs
  • Implement approval workflows for production deletions
  • Review applications that may be affected by tax deletion
  • Check for any hardcoded references to specific tax IDs
  • Verify that reporting systems can handle missing tax references
  • Test deletion operations in staging environments first
  • Export tax configurations before deletion for potential recovery
  • Maintain backups of critical tax data
  • Document tax configurations in external systems
  • Consider soft deletion for critical tax configurations

​
Use Cases

​
Business Scenarios

Business Restructuring

Remove obsolete tax configurations during company reorganization

Regulatory Changes

Delete tax rates that are no longer legally valid

System Migration

Clean up old tax configurations after migrating to new systems

Development Cleanup

Remove test and development tax configurations from production

Compliance Requirements

Remove tax configurations that don’t meet current compliance standards

Data Governance

Maintain clean tax data by removing unused configurations

​
Security Considerations

Tax deletions affect financial calculations and should be carefully controlled with proper authentication, authorization, and audit logging.
  • Only authenticated applications can delete taxes they have access to
  • Tax deletions are scoped to the business of the authenticated application
  • Consider implementing role-based permissions for tax deletion operations
  • Log all tax deletions with detailed information
  • Track who deleted taxes, when, and why
  • Maintain historical records for compliance and investigation purposes
  • Ensure tax deletions don’t break critical business processes
  • Validate that applications can handle missing tax references gracefully
  • Implement proper error handling for deleted tax scenarios

​
Rate Limiting

This endpoint is subject to the standard API rate limits:
  • Production: 1000 requests per hour per API key
  • Development: 100 requests per hour per API key
  • POST /api/v0/taxes - Create a new tax
  • GET /api/v0/taxes - List all taxes
  • GET /api/v0/taxes/{id} - Fetch specific tax details
  • PATCH /api/v0/taxes/{id} - Update tax configuration