Create Tax

The Create Tax endpoint enables you to create and configure tax rates for your business applications. This endpoint supports multi-application tax management, allowing you to assign tax rates to specific applications within your business.

Endpoint Details

URL: /api/v0/taxes
Method: POST
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

Request Body

Required Fields

Field	Type	Description	Validation
name	string	Tax name (e.g., “VAT”, “Sales Tax”, “GST”)	Required, non-empty
percentage	number	Tax percentage rate (e.g., 15.5 for 15.5%)	Required, numeric

Optional Fields

Field	Type	Description	Default	Validation
description	string	Detailed description of the tax	null	Optional string
active	boolean	Whether the tax is currently active	true	Optional boolean
appIds	string[]	Array of application IDs to associate with this tax	[]	Optional array of valid UUIDs

Request Schema

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

Response

Success Response (201 Created)

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "name": "VAT",
  "description": "Value Added Tax",
  "business_id": "456e7890-e89b-12d3-a456-426614174001",
  "percentage": 15.5,
  "active": true,
  "created_at": "2024-01-15T10:30:00.000Z",
  "updated_at": "2024-01-15T10:30: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": 400,
  "message": [
    "name should not be empty",
    "percentage must be a number"
  ],
  "error": "Bad Request"
}

Business Logic

Automatic App Association

The current authenticated application is automatically associated with the created tax. Even if appIds is provided, the current app ID will be added if not already included. This ensures the creating application always has access to the tax.

Multi-Application Support

Application Scoping

Taxes can be shared across multiple applications within the same business
Use the appIds array to specify which applications should have access to this tax
Applications not in the array won’t be able to access or use this tax

Business Isolation

Taxes are scoped to your business - other businesses cannot access your tax configurations
All applications in the appIds array must belong to the same business
Tax calculations are performed consistently across all associated applications

Example Requests

curl -X POST https://api.devdraft.ai/api/v0/taxes \
  -H "Content-Type: application/json" \
  -H "x-client-key: your-client-key" \
  -H "x-client-secret: your-client-secret" \
  -d '{
    "name": "Sales Tax",
    "percentage": 8.25,
    "description": "California State Sales Tax"
  }'

Use Cases

Single Application Tax

Create a tax for your current application only

Multi-Region Tax Setup

Create taxes for different regions with specific applications

Seasonal Tax Preparation

Create inactive taxes for future use

Compliance Management

Set up tax rates for regulatory compliance

Detailed Use Cases

Create a tax for your current application only:

{
  "name": "Local Sales Tax",
  "percentage": 7.5
}

Perfect for businesses operating in a single jurisdiction with one application.

Validation Rules

Name Validation

Required: Yes
Type: String
Length: 1-100 characters
Description: Must be descriptive (e.g., “VAT”, “Sales Tax”, “GST”)
Examples: “California Sales Tax”, “UK VAT Standard Rate”, “EU VAT”

Percentage Validation

Required: Yes
Type: Number
Range: 0-100%
Decimal: Supports decimal places for precise rates
Examples: 8.25, 20.0, 15.5

Description Validation

Required: No
Type: String
Length: Maximum 255 characters
Purpose: Explain what this tax covers
Examples: “Standard VAT rate for goods and services”

AppIds Validation

Required: No
Type: Array of strings
Format: Valid UUID v4 format
Constraint: Applications must belong to the same business
Auto-inclusion: Current application automatically included

Response Fields Explanation

Field	Description
id	Unique identifier for the tax
name	Tax name as provided
description	Tax description (if provided)
business_id	ID of the business this tax belongs to
percentage	Tax percentage rate
active	Whether the tax is currently active
created_at	Timestamp when the tax was created
updated_at	Timestamp when the tax was last updated
apps	Array of applications associated with this tax

Integration Notes

With Invoices

Created taxes can be associated with invoices using the taxId field in invoice creation
Only taxes associated with the invoice’s application can be used
Tax calculations are performed server-side for accuracy

With Payment Links

Taxes can be applied to payment links for automatic tax calculation
Tax amounts are calculated and displayed to customers
Supports multiple tax rates per payment link

With Products

While products don’t directly reference taxes, taxes are applied at the invoice/payment level
Consider your tax strategy when organizing products and pricing
Tax-inclusive vs tax-exclusive pricing strategies

Best Practices

Descriptive Naming

Use clear, descriptive names that indicate the tax type and jurisdiction:

{
  "name": "California State Sales Tax",
  "description": "8.25% state sales tax for California transactions"
}

Precise Percentages

Include decimal places for accurate tax calculations:

{
  "percentage": 8.375  // Instead of rounding to 8.4
}

Regional Organization

Group taxes by region or jurisdiction for easier management:

{
  "name": "UK VAT Standard Rate",
  "percentage": 20.0,
  "description": "United Kingdom VAT standard rate"
}

Future Planning

Create inactive taxes for upcoming rate changes:

{
  "name": "2025 Updated Sales Tax",
  "percentage": 9.0,
  "active": false,
  "description": "New rate effective January 1, 2025"
}

Security Considerations

Tax rates are sensitive business data and require proper authentication. Only applications within the same business can access shared taxes.

Access Control

Tax configurations are scoped to your business
Only authenticated applications can create taxes
Application isolation prevents unauthorized access

Audit Requirements

Tax modifications should be tracked for audit purposes
Consider implementing approval workflows for tax rate changes in production
Maintain records of tax rate changes for compliance

Data Integrity

Tax calculations are performed server-side to ensure accuracy
Percentage values are validated to prevent invalid rates
Business association ensures proper data isolation

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

GET /api/v0/taxes - List all taxes
GET /api/v0/taxes/{id} - Fetch specific tax details
PATCH /api/v0/taxes/{id} - Update tax configuration
DELETE /api/v0/taxes/{id} - Delete tax

Home

Customers

Payment Links

Payment Intents

Products

Invoices

Taxes

Webhooks

Wallets

Transfers

Endpoint Details

Authentication

Request Body

Required Fields

Optional Fields

Request Schema

Response

Success Response (201 Created)

Error Responses

Business Logic

Automatic App Association

Multi-Application Support

Example Requests

Use Cases

Single Application Tax

Multi-Region Tax Setup

Seasonal Tax Preparation

Compliance Management

Detailed Use Cases

Validation Rules

Response Fields Explanation

Integration Notes

Best Practices

Security Considerations

Rate Limiting

Home

Customers

Payment Links

Payment Intents

Products

Invoices

Taxes

Webhooks

Wallets

Transfers

​Endpoint Details

​Authentication

​Request Body

​Required Fields

​Optional Fields

​Request Schema

​Response

​Success Response (201 Created)

​Error Responses

​Business Logic

​Automatic App Association

​Multi-Application Support

​Example Requests

​Use Cases

Single Application Tax

Multi-Region Tax Setup

Seasonal Tax Preparation

Compliance Management

​Detailed Use Cases

​Validation Rules

​Response Fields Explanation

​Integration Notes

​Best Practices

​Security Considerations

​Rate Limiting

​Related Endpoints

Endpoint Details

Authentication

Request Body

Required Fields

Optional Fields

Request Schema

Response

Success Response (201 Created)

Error Responses

Business Logic

Automatic App Association

Multi-Application Support

Example Requests

Use Cases

Detailed Use Cases

Validation Rules

Response Fields Explanation

Integration Notes

Best Practices

Security Considerations

Rate Limiting

Related Endpoints