The Update Tax endpoint allows you to modify existing tax configurations, including changing tax rates, updating descriptions, toggling active status, and managing application associations. This endpoint is essential for maintaining accurate tax configurations as business requirements change.

​
Endpoint Details

  • URL: /api/v0/taxes/{tax_id}
  • Method: PATCH
  • 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

​
Request Body

All fields are optional - only provide the fields you want to update.

​
Optional Fields

FieldTypeDescriptionValidation
namestringTax name (e.g., “VAT”, “Sales Tax”, “GST”)1-100 characters
descriptionstringDetailed description of the taxMax 255 characters
percentagenumberTax percentage rate (e.g., 15.5 for 15.5%)0-100, numeric
activebooleanWhether the tax is currently activeBoolean
appIdsstring[]Array of application IDs to associate with this taxArray of valid UUIDs

​
Request Schema

{
  "name": "string",
  "description": "string", 
  "percentage": "number",
  "active": "boolean",
  "appIds": ["string"]
}

​
Response

​
Success Response (200 OK)

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "name": "Updated VAT Standard Rate",
  "description": "Updated standard VAT rate for goods and services",
  "business_id": "456e7890-e89b-12d3-a456-426614174001",
  "percentage": 21.0,
  "active": true,
  "created_at": "2024-01-15T10:30:00.000Z",
  "updated_at": "2024-01-25T16:20:00.000Z",
  "apps": [
    {
      "id": "789e0123-e89b-12d3-a456-426614174002",
      "business_id": "456e7890-e89b-12d3-a456-426614174001",
      "app_name": "my-store",
      "display_name": "My Store",
      "environment": "PRODUCTION",
      "stage": "PRODUCTION",
      "timezone": "UTC",
      "created_at": "2024-01-10T08:00:00.000Z",
      "updated_at": "2024-01-10T08:00:00.000Z"
    }
  ]
}

​
Error Responses

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

​
Example Requests

curl -X PATCH "https://api.devdraft.ai/api/v0/taxes/123e4567-e89b-12d3-a456-426614174000" \
  -H "Content-Type: application/json" \
  -H "x-client-key: your-client-key" \
  -H "x-client-secret: your-client-secret" \
  -d '{
    "percentage": 21.0,
    "description": "Updated VAT rate effective 2024"
  }'

​
Update Types

​
Rate Changes

  • Use Case: Regulatory changes, government rate adjustments
  • Impact: Affects all future transactions using this tax
  • Consideration: May require notification to affected applications
  • Use Case: Immediate regulatory changes, temporary rate adjustments
  • Best Practice: Update description to document reason and effective date
  • Monitoring: Track applications using this tax for impact assessment

​
Status Management

  • Use Case: Discontinuing tax rates, temporary suspension
  • Impact: Prevents tax from being used in new transactions
  • Cleanup: Consider removing application associations when deactivating
  • Use Case: Restoring previously used tax rates
  • Verification: Ensure tax rate is still current and compliant
  • Testing: Validate in staging environment before production activation

​
Application Management

  • Preserves Existing: Maintains current application associations
  • Validation: Ensures applications belong to the same business
  • Impact: New applications can immediately use this tax rate
  • Selective Removal: Remove specific applications while preserving others
  • Impact: Affected applications lose access to this tax rate
  • Validation: Ensure removed applications have alternative tax configurations
  • Complete Replacement: Replace all current associations with new list
  • Use Case: Major application restructuring, business reorganization
  • Caution: Verify all current applications have alternative tax configurations

​
Validation Rules

  • Length: 1-100 characters when provided
  • Uniqueness: Should be unique within business context
  • Clarity: Use descriptive names that indicate purpose and jurisdiction
  • Range: 0-100% (inclusive)
  • Precision: Supports decimal places for precise rates
  • Validation: Must be a valid number when provided
  • Length: Maximum 255 characters when provided
  • Content: Should explain tax purpose, jurisdiction, or recent changes
  • Optional: Can be null or empty string
  • Format: Must be valid UUID v4 format
  • Ownership: Applications must belong to the same business
  • Existence: Applications must exist and be accessible

​
Business Logic

​
Update Behavior

Partial Updates: Only fields provided in the request body are updated. Omitted fields remain unchanged.
Application Association: When updating appIds, the entire application list is replaced. To add/remove specific applications, first retrieve current associations.

​
Impact Assessment

  • Future Transactions: All future transactions using this tax will use the new rate
  • Active Invoices: Existing draft invoices may be affected depending on implementation
  • Payment Links: Active payment links using this tax will calculate with new rate
  • Deactivation: Prevents tax from being used in new transactions
  • Application Behavior: Applications should handle inactive tax gracefully
  • Existing Data: Historical transactions remain unchanged
  • Access Control: Applications gain or lose access to tax immediately
  • Validation: Existing transactions using removed applications remain valid
  • Migration: Consider data migration when removing applications

​
Use Cases

Regulatory Compliance

Update tax rates to comply with new government regulations

Business Restructuring

Modify application associations during business reorganization

Seasonal Adjustments

Activate or deactivate seasonal tax rates

Rate Corrections

Fix incorrect tax rates or update descriptions

Application Migration

Move tax configurations between applications during system updates

Compliance Updates

Update tax descriptions to include compliance notes or regulatory references

​
Best Practices

1

Backup Before Changes

Always retrieve and backup current tax configuration before making changes:
const backupTax = await getTax(taxId);
console.log('Backup created:', JSON.stringify(backupTax, null, 2));
2

Validate Changes

Validate update data before sending to API:
const validateTaxUpdate = (updates) => {
  if (updates.percentage !== undefined) {
    if (updates.percentage < 0 || updates.percentage > 100) {
      throw new Error('Tax percentage must be between 0 and 100');
    }
  }
  
  if (updates.name !== undefined) {
    if (!updates.name || updates.name.length > 100) {
      throw new Error('Tax name must be 1-100 characters');
    }
  }
  
  return true;
};
3

Document Changes

Always update description when making significant changes:
const updateTaxWithReason = async (taxId, updates, reason) => {
  const currentTax = await getTax(taxId);
  const timestamp = new Date().toISOString().split('T')[0];
  
  const enhancedUpdates = {
    ...updates,
    description: `${currentTax.description || ''}. Updated ${timestamp}: ${reason}`.trim()
  };
  
  return await updateTax(taxId, enhancedUpdates);
};
4

Test in Staging

Test tax updates in staging environment before production:
const testTaxUpdate = async (taxId, updates) => {
  if (process.env.NODE_ENV === 'production') {
    throw new Error('Direct production updates not allowed');
  }
  
  return await updateTax(taxId, updates);
};
5

Monitor Impact

Monitor applications after tax updates to ensure proper functionality:
const monitorTaxUpdate = async (taxId, updates) => {
  const result = await updateTax(taxId, updates);
  
  // Log for monitoring
  console.log(`Tax ${taxId} updated:`, {
    changes: updates,
    affectedApps: result.apps.length,
    timestamp: new Date().toISOString()
  });
  
  return result;
};

​
Security Considerations

Tax updates affect financial calculations and should be carefully controlled with proper authentication and audit logging.
  • Only authenticated applications can update taxes they have access to
  • Tax updates are scoped to the business of the authenticated application
  • Consider implementing role-based permissions for tax modifications
  • Log all tax updates with user information and timestamps
  • Track what changed, when, and why for compliance purposes
  • Maintain historical records of tax rate changes
  • Implement approval workflows for production tax changes
  • Test tax updates in staging environments
  • Monitor application behavior after tax updates

​
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
  • DELETE /api/v0/taxes/{id} - Delete tax