Create Tax

Endpoint DetailsCopied!

• URL: /api/v0/taxes

• Method: POST

• Authentication: Required (API Key Authentication)

• Content-Type: application/json

AuthenticationCopied!

This endpoint requires API key authentication using:

• x-client-key: Your API client key

• x-client-secret: Your API client secret

Request BodyCopied!

Required Fields

Optional Fields

Request Schema

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

ResponseCopied!

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

400 Bad Request

{
  "statusCode": 400,
  "message": [
    "name should not be empty",
    "percentage must be a number"
  ],
  "error": "Bad Request"
}

401 Unauthorized

{
  "statusCode": 401,
  "message": "Application not authenticated",
  "error": "Unauthorized"
}

Business LogicCopied!

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

• 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

Example RequestsCopied!

Basic Tax Creation

curl -X POST https://api.devdraft.com/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"
  }'

Tax with Multiple Applications

curl -X POST https://api.devdraft.com/api/v0/taxes \
  -H "Content-Type: application/json" \
  -H "x-client-key: your-client-key" \
  -H "x-client-secret: your-client-secret" \
  -d '{
    "name": "EU VAT",
    "percentage": 20.0,
    "description": "European Union Value Added Tax",
    "active": true,
    "appIds": [
      "app-eu-store-1",
      "app-eu-store-2"
    ]
  }'

Inactive Tax Creation

curl -X POST https://api.devdraft.com/api/v0/taxes \
  -H "Content-Type: application/json" \
  -H "x-client-key: your-client-key" \
  -H "x-client-secret: your-client-secret" \
  -d '{
    "name": "Future Tax Rate",
    "percentage": 12.0,
    "description": "Tax rate for next fiscal year",
    "active": false
  }'

Use CasesCopied!

1. Single Application Tax

Create a tax for your current application only:

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

2. Multi-Region Tax Setup

Create taxes for different regions with specific applications:

{
  "name": "VAT",
  "percentage": 19.0,
  "appIds": ["eu-app-1", "eu-app-2"]
}

3. Seasonal Tax Preparation

Create inactive taxes for future use:

{
  "name": "Holiday Tax Rate",
  "percentage": 5.0,
  "active": false
}

Response Fields ExplanationCopied!

Validation RulesCopied!

Name Validation

• Must be a non-empty string

• No specific length restrictions

• Should be descriptive (e.g., "VAT", "Sales Tax", "GST")

Percentage Validation

• Must be a valid number

• Can include decimal places for precise rates

• No explicit range restrictions (allows 0% or high rates)

AppIds Validation

• Must be valid UUID v4 format

• Each ID must correspond to an existing application

• Applications must belong to the same business

Rate LimitingCopied!

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

Best PracticesCopied!

1. 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"
}

2. Precise Percentages

Include decimal places for accurate tax calculations:

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

3. 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"
}

4. 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"
}

Integration NotesCopied!

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

With Payment Links

• Taxes can be applied to payment links for automatic tax calculation

• Tax calculations are performed server-side to ensure accuracy

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

Security ConsiderationsCopied!

• Tax rates are sensitive business data and require proper authentication

• Only applications within the same business can access shared taxes

• Tax modifications should be tracked for audit purposes

• Consider implementing approval workflows for tax rate changes in production