List Taxes

The List Taxes endpoint retrieves all tax configurations associated with your authenticated application. This endpoint provides access to both active and inactive taxes that can be used for invoices, payment links, and other tax-related operations.

Endpoint DetailsCopied!

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

Query ParametersCopied!

Optional Parameters

Parameter	Type	Description	Default	Validation
`skip`	`string`	Number of records to skip for pagination	`"0"`	Optional numeric string
`take`	`string`	Number of records to return	`"10"`	Optional numeric string

Note: While these parameters are defined in the controller, the current implementation returns all taxes associated with the application regardless of pagination parameters.

Request ExamplesCopied!

Basic Request

curl -X GET https://api.devdraft.com/api/v0/taxes \
  -H "x-client-key: your-client-key" \
  -H "x-client-secret: your-client-secret"

With Query Parameters

curl -X GET "https://api.devdraft.com/api/v0/taxes?skip=0&take=20" \
  -H "x-client-key: your-client-key" \
  -H "x-client-secret: your-client-secret"

ResponseCopied!

Success Response (200 OK)

[
  {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "name": "VAT",
    "description": "Value Added Tax",
    "business_id": "456e7890-e89b-12d3-a456-426614174001",
    "percentage": 20.0,
    "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"
      }
    ]
  },
  {
    "id": "234e5678-e89b-12d3-a456-426614174001",
    "name": "Sales Tax",
    "description": "California State Sales Tax",
    "business_id": "456e7890-e89b-12d3-a456-426614174001",
    "percentage": 8.25,
    "active": true,
    "created_at": "2024-01-12T14:20:00.000Z",
    "updated_at": "2024-01-12T14: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"
      },
      {
        "id": "890e1234-e89b-12d3-a456-426614174003",
        "business_id": "456e7890-e89b-12d3-a456-426614174001",
        "app_name": "west-coast-store",
        "display_name": "West Coast Store",
        "environment": "PRODUCTION",
        "stage": "PRODUCTION",
        "timezone": "America/Los_Angeles",
        "created_at": "2024-01-05T12:00:00.000Z",
        "updated_at": "2024-01-05T12:00:00.000Z"
      }
    ]
  },
  {
    "id": "345e6789-e89b-12d3-a456-426614174002",
    "name": "Future Tax Rate",
    "description": "Tax rate for next fiscal year",
    "business_id": "456e7890-e89b-12d3-a456-426614174001",
    "percentage": 12.0,
    "active": false,
    "created_at": "2024-01-20T09:15:00.000Z",
    "updated_at": "2024-01-20T09:15: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"
      }
    ]
  }
]

Empty Response (200 OK)

[]

Error Responses

401 Unauthorized

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

403 Forbidden

{
  "statusCode": 403,
  "message": "Invalid API credentials",
  "error": "Forbidden"
}

Response FieldsCopied!

Tax Object Fields

Field	Type	Description
`id`	`string`	Unique identifier for the tax (UUID)
`name`	`string`	Tax name (e.g., "VAT", "Sales Tax")
`description`	`string \| null`	Detailed description of the tax
`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 timestamp when the tax was created
`updated_at`	`string`	ISO timestamp when the tax was last updated
`apps`	`App[]`	Array of applications associated with this tax

App Object Fields

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

Business LogicCopied!

Application-Scoped Results

Only returns taxes that are associated with the authenticated application
Taxes shared across multiple applications will show all associated apps in the apps array
The current application will always be included in the apps array for returned taxes

Active and Inactive Taxes

Both active (active: true) and inactive (active: false) taxes are returned
Use the active field to filter client-side if needed
Inactive taxes can still be used but may require special handling

Filtering and SortingCopied!

Client-Side Filtering Examples

Filter Active Taxes Only

const activeTaxes = taxes.filter(tax => tax.active === true);

Filter by Tax Rate Range

const lowRateTaxes = taxes.filter(tax => tax.percentage <= 10);
const highRateTaxes = taxes.filter(tax => tax.percentage > 10);

Sort by Tax Rate

const sortedByRate = taxes.sort((a, b) => a.percentage - b.percentage);

Sort by Name

const sortedByName = taxes.sort((a, b) => a.name.localeCompare(b.name));

Use CasesCopied!

1. Tax Selection for Invoices

Retrieve available taxes for invoice creation:

// Get all active taxes for invoice dropdown
const activeTaxes = taxes.filter(tax => tax.active);
const taxOptions = activeTaxes.map(tax => ({
  value: tax.id,
  label: `${tax.name} (${tax.percentage}%)`,
  description: tax.description
}));

2. Tax Rate Display

Show tax information in your application:

// Display tax rates in settings
taxes.forEach(tax => {
  console.log(`${tax.name}: ${tax.percentage}% ${tax.active ? '(Active)' : '(Inactive)'}`);
});

3. Multi-Application Tax Management

Identify taxes shared across applications:

// Find taxes used by multiple applications
const sharedTaxes = taxes.filter(tax => tax.apps.length > 1);

4. Tax Audit and Reporting

Generate tax configuration reports:

// Create tax summary report
const taxSummary = taxes.map(tax => ({
  name: tax.name,
  rate: tax.percentage,
  status: tax.active ? 'Active' : 'Inactive',
  applicationCount: tax.apps.length,
  lastUpdated: tax.updated_at
}));

Integration ExamplesCopied!

JavaScript/TypeScript

interface Tax {
  id: string;
  name: string;
  description: string | null;
  business_id: string;
  percentage: number;
  active: boolean;
  created_at: string;
  updated_at: string;
  apps: App[];
}

async function fetchTaxes(): Promise<Tax[]> {
  const response = await fetch('/api/v0/taxes', {
    headers: {
      'x-client-key': 'your-client-key',
      'x-client-secret': 'your-client-secret'
    }
  });
  
  if (!response.ok) {
    throw new Error('Failed to fetch taxes');
  }
  
  return response.json();
}

Python

import requests

def get_taxes():
    headers = {
        'x-client-key': 'your-client-key',
        'x-client-secret': 'your-client-secret'
    }
    
    response = requests.get(
        'https://api.devdraft.com/api/v0/taxes',
        headers=headers
    )
    
    response.raise_for_status()
    return response.json()

# Get only active taxes
taxes = get_taxes()
active_taxes = [tax for tax in taxes if tax['active']]

PHP

<?php
function getTaxes($clientKey, $clientSecret) {
    $ch = curl_init();
    
    curl_setopt_array($ch, [
        CURLOPT_URL => 'https://api.devdraft.com/api/v0/taxes',
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_HTTPHEADER => [
            'x-client-key: ' . $clientKey,
            'x-client-secret: ' . $clientSecret
        ]
    ]);
    
    $response = curl_exec($ch);
    $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    
    curl_close($ch);
    
    if ($httpCode === 200) {
        return json_decode($response, true);
    }
    
    throw new Exception('Failed to fetch taxes');
}

// Usage
$taxes = getTaxes('your-client-key', 'your-client-secret');
$activeTaxes = array_filter($taxes, function($tax) {
    return $tax['active'] === true;
});
?>

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. Caching

Cache tax data locally to reduce API calls:

// Cache taxes for 1 hour
const CACHE_DURATION = 60 * 60 * 1000; // 1 hour in milliseconds
let cachedTaxes = null;
let cacheTimestamp = null;

async function getTaxes() {
  const now = Date.now();
  
  if (cachedTaxes && cacheTimestamp && (now - cacheTimestamp) < CACHE_DURATION) {
    return cachedTaxes;
  }
  
  cachedTaxes = await fetchTaxes();
  cacheTimestamp = now;
  
  return cachedTaxes;
}

2. Error Handling

Implement robust error handling:

async function getTaxesWithFallback() {
  try {
    return await fetchTaxes();
  } catch (error) {
    console.error('Failed to fetch taxes:', error);
    // Return empty array or cached data as fallback
    return [];
  }
}

3. Status Indication

Clearly indicate tax status in your UI:

function formatTaxDisplay(tax) {
  const status = tax.active ? '✓ Active' : '✗ Inactive';
  return `${tax.name} (${tax.percentage}%) - ${status}`;
}

4. Application Context

Show which applications use each tax:

function getTaxApplications(tax) {
  return tax.apps.map(app => app.display_name).join(', ');
}

Security NotesCopied!

Tax configurations are scoped to your authenticated application
Only taxes explicitly associated with your application are returned
Sensitive business information - ensure secure transmission and storage
Consider implementing additional access controls in your application layer