Fetch Tax

The Fetch Tax endpoint allows you to retrieve detailed information about a specific tax configuration, including its rate, status, associated applications, and usage statistics. This endpoint is useful for displaying tax details, validating tax configurations, and debugging tax-related issues.

Endpoint Details

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

Parameter	Type	Description	Required
tax_id	string	Unique identifier for the tax	Yes

Response

Success Response (200 OK)

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "name": "VAT Standard Rate",
  "description": "Standard VAT rate for goods and services",
  "business_id": "456e7890-e89b-12d3-a456-426614174001",
  "percentage": 20.0,
  "active": true,
  "created_at": "2024-01-15T10:30:00.000Z",
  "updated_at": "2024-01-20T14:45: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"
    },
    {
      "id": "890f1234-f01d-34f5-c678-648836396222",
      "business_id": "456e7890-e89b-12d3-a456-426614174001",
      "app_name": "eu-store",
      "display_name": "EU Store",
      "environment": "PRODUCTION",
      "stage": "PRODUCTION",
      "timezone": "Europe/London",
      "created_at": "2024-01-05T12:00:00.000Z",
      "updated_at": "2024-01-05T12:00:00.000Z"
    }
  ]
}

Response Fields

Tax Object

Field	Type	Description
id	string	Unique identifier for the tax
name	string	Tax name for identification
description	string	Detailed description of the tax (optional)
business_id	string	ID of the business this tax belongs to
percentage	number	Tax percentage rate
active	boolean	Whether the tax is currently active
created_at	string	ISO 8601 timestamp when tax was created
updated_at	string	ISO 8601 timestamp when tax was last updated
apps	array	Applications associated with this tax

Application Object

Field	Type	Description
id	string	Unique identifier for the application
business_id	string	ID of the business this application belongs to
app_name	string	Internal application name
display_name	string	Human-readable application name
environment	string	Application environment (PRODUCTION, STAGING)
stage	string	Application stage
timezone	string	Application timezone
created_at	string	ISO 8601 timestamp when app was created
updated_at	string	ISO 8601 timestamp when app was last updated

Example Requests

curl -X GET "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"
}

Tax Analysis

Rate Categorization

Zero Rate (0%)

Use Cases: Exempt items, non-taxable services
Examples: Basic food items, medical services, educational materials
Compliance: Often used for essential goods and services

Low Rate (0.1% - 4.9%)

Use Cases: Reduced rate items, special categories
Examples: Books, newspapers, children’s items
Considerations: May require special documentation or approval

Standard Rate (5% - 14.9%)

Use Cases: Most common tax rates for general goods and services
Examples: General sales tax, standard VAT rates
Implementation: Straightforward application to most transactions

High Rate (15% - 24.9%)

Use Cases: Luxury items, higher tax jurisdictions
Examples: Premium goods, certain services
Considerations: May affect customer behavior and pricing strategies

Premium Rate (25%+)

Use Cases: Luxury taxes, sin taxes, special levies
Examples: Tobacco, alcohol, luxury vehicles
Compliance: Often requires additional regulatory compliance

Configuration Health

Active Status

Healthy: Active taxes with associated applications
Warning: Inactive taxes still associated with applications
Issue: Active taxes with no associated applications

Application Association

Single App: Tax used by one application only
Multi App: Tax shared across multiple applications
Unassigned: Tax not associated with any applications

Maintenance

Recently Created: Created within last 7 days
Recently Updated: Modified within last 7 days
Needs Review: Not updated in over 365 days

Use Cases

Tax Detail Display

Show complete tax information in admin interfaces

Configuration Validation

Verify tax settings before applying to transactions

Audit and Compliance

Review tax configurations for regulatory compliance

Integration Setup

Retrieve tax details for third-party system integration

Rate Comparison

Compare tax rates across different jurisdictions

Application Management

Review which applications use specific tax rates

Implementation Examples

const TaxDetailView = async (taxId) => {
  const tax = await getTax(taxId);
  
  return {
    basicInfo: {
      name: tax.name,
      rate: `${tax.percentage}%`,
      status: tax.active ? 'Active' : 'Inactive',
      description: tax.description || 'No description provided'
    },
    applications: tax.apps.map(app => ({
      name: app.display_name,
      environment: app.environment,
      id: app.id
    })),
    metadata: {
      created: new Date(tax.created_at).toLocaleDateString(),
      lastUpdated: new Date(tax.updated_at).toLocaleDateString(),
      businessId: tax.business_id
    },
    actions: [
      { label: 'Edit Tax', action: 'edit', enabled: true },
      { label: 'Deactivate', action: 'deactivate', enabled: tax.active },
      { label: 'Delete', action: 'delete', enabled: !tax.active && tax.apps.length === 0 }
    ]
  };
};

Security Considerations

Tax details contain sensitive business configuration data. Ensure proper access controls and audit logging.

Access Control

Only authenticated applications can access tax details
Tax data is scoped to the business of the authenticated application
Applications can only access taxes they’re associated with

Data Integrity

Tax rates are critical for financial calculations
Verify tax data integrity before using in transactions
Implement checksums or validation for critical tax data

Audit Requirements

Log all tax data access for audit purposes
Track who accessed tax configuration data and when
Maintain records for regulatory compliance requirements

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

Best Practices

Error Handling

Implement comprehensive error handling for missing or inaccessible taxes:

const getTaxSafely = async (taxId) => {
  try {
    return await getTax(taxId);
  } catch (error) {
    if (error.message.includes('404')) {
      console.warn(`Tax ${taxId} not found`);
      return null;
    }
    throw error;
  }
};

Caching Strategy

Cache frequently accessed tax details:

const taxCache = new Map();
const CACHE_TTL = 30 * 60 * 1000; // 30 minutes

const getCachedTax = async (taxId) => {
  const cached = taxCache.get(taxId);
  if (cached && (Date.now() - cached.timestamp) < CACHE_TTL) {
    return cached.data;
  }
  
  const tax = await getTax(taxId);
  taxCache.set(taxId, { data: tax, timestamp: Date.now() });
  return tax;
};

Validation

Always validate tax data before using in calculations:

const validateTaxData = (tax) => {
  if (!tax || typeof tax.percentage !== 'number') {
    throw new Error('Invalid tax data');
  }
  
  if (tax.percentage < 0 || tax.percentage > 100) {
    throw new Error('Invalid tax percentage');
  }
  
  if (!tax.active) {
    console.warn('Using inactive tax rate');
  }
  
  return true;
};

Monitor Usage

Track tax usage patterns for optimization:

const trackTaxUsage = (taxId, context) => {
  // Log tax access for analytics
  analytics.track('tax_accessed', {
    taxId,
    context,
    timestamp: new Date().toISOString()
  });
};

POST /api/v0/taxes - Create a new tax
GET /api/v0/taxes - List all taxes
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

Path Parameters

Response

Success Response (200 OK)

Response Fields

Tax Object

Application Object

Example Requests

Error Responses

Tax Analysis

Rate Categorization

Configuration Health

Use Cases

Tax Detail Display

Configuration Validation

Audit and Compliance

Integration Setup

Rate Comparison

Application Management

Implementation Examples

Security Considerations

Rate Limiting

Best Practices

Home

Customers

Payment Links

Payment Intents

Products

Invoices

Taxes

Webhooks

Wallets

Transfers

​Endpoint Details

​Authentication

​Path Parameters

​Response

​Success Response (200 OK)

​Response Fields

​Tax Object

​Application Object

​Example Requests

​Error Responses

​Tax Analysis

​Rate Categorization

​Configuration Health

​Use Cases

Tax Detail Display

Configuration Validation

Audit and Compliance

Integration Setup

Rate Comparison

Application Management

​Implementation Examples

​Security Considerations

​Rate Limiting

​Best Practices

​Related Endpoints

Endpoint Details

Authentication

Path Parameters

Response

Success Response (200 OK)

Response Fields

Tax Object

Application Object

Example Requests

Error Responses

Tax Analysis

Rate Categorization

Configuration Health

Use Cases

Implementation Examples

Security Considerations

Rate Limiting

Best Practices

Related Endpoints