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 Details

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

Query Parameters

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

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

Response

Success Response (200 OK)

[
  {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "name": "Sales Tax",
    "description": "Standard sales tax for retail transactions",
    "business_id": "456e7890-e89b-12d3-a456-426614174001",
    "percentage": 8.25,
    "active": true,
    "created_at": "2024-01-10T08:00: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": "234f5678-f90c-23e4-b567-537725285111",
    "name": "VAT",
    "description": "Value Added Tax for European customers",
    "business_id": "456e7890-e89b-12d3-a456-426614174001",
    "percentage": 20.0,
    "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": "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"
      }
    ]
  },
  {
    "id": "345g6789-g01e-45f6-d789-759947407333",
    "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-18T16:45:00.000Z",
    "updated_at": "2024-01-18T16:45:00.000Z",
    "apps": []
  }
]

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

App 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" \
  -H "x-client-key: your-client-key" \
  -H "x-client-secret: your-client-secret"

Error Responses

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

Business Logic

Application Scoping

Automatic Filtering

Only taxes associated with your authenticated application are returned
Taxes are automatically filtered based on the application context
No manual filtering required - the API handles application scoping

Business Isolation

Taxes are scoped to your business - other businesses’ taxes are not visible
All returned taxes belong to the same business as your authenticated application
Ensures data privacy and prevents unauthorized access

Data Relationships

Application Association

Each tax includes an apps array showing associated applications
Applications in the array can use this tax for calculations
Empty apps array indicates tax is not assigned to any applications

Multi-Application Support

Taxes can be shared across multiple applications within the same business
Applications inherit access to taxes they’re associated with
Changes to tax rates affect all associated applications

Filtering and Sorting

Client-Side Filtering

Filter taxes by active/inactive status:

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

Use Cases

Tax Configuration Dashboard

Display all available taxes with status and rates for management

Invoice Tax Selection

Populate tax dropdown lists for invoice creation forms

Compliance Reporting

Generate reports showing all configured tax rates for audit purposes

Application Setup

Configure tax settings when setting up new applications

Detailed Examples

const TaxDashboard = async () => {
  const taxes = await getTaxes();
  
  return {
    overview: {
      total: taxes.length,
      active: taxes.filter(t => t.active).length,
      inactive: taxes.filter(t => !t.active).length
    },
    rateDistribution: taxes.reduce((acc, tax) => {
      const rate = `${tax.percentage}%`;
      acc[rate] = (acc[rate] || 0) + 1;
      return acc;
    }, {}),
    recentlyCreated: taxes
      .sort((a, b) => new Date(b.created_at) - new Date(a.created_at))
      .slice(0, 5),
    multiAppTaxes: taxes.filter(t => t.apps.length > 1)
  };
};

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

Caching

Cache tax data locally to reduce API calls:

// Cache taxes for 1 hour
const CACHE_DURATION = 60 * 60 * 1000;
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;
}

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 [];
  }
}

Status Indication

Clearly indicate tax status in your UI:

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

Application Context

Show which applications use each tax:

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

Security Notes

Tax configurations are scoped to your authenticated application and contain sensitive business information. Ensure secure transmission and storage.

Data Scoping

Tax configurations are automatically scoped to your authenticated application
Only taxes explicitly associated with your application are returned
Business-level isolation prevents cross-business data access

Access Control

Requires valid API authentication
Consider implementing additional access controls in your application layer
Monitor access patterns for unusual activity

Data Protection

Sensitive business information - ensure secure transmission
Consider encryption for stored tax configuration data
Implement audit logging for tax data access

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

Query Parameters

Optional Parameters

Response

Success Response (200 OK)

Response Fields

Tax Object

App Object

Example Requests

Error Responses

Business Logic

Application Scoping

Data Relationships

Filtering and Sorting

Client-Side Filtering

Use Cases

Tax Configuration Dashboard

Invoice Tax Selection

Compliance Reporting

Application Setup

Detailed Examples

Rate Limiting

Best Practices

Security Notes

Home

Customers

Payment Links

Payment Intents

Products

Invoices

Taxes

Webhooks

Wallets

Transfers

​Endpoint Details

​Authentication

​Query Parameters

​Optional Parameters

​Response

​Success Response (200 OK)

​Response Fields

​Tax Object

​App Object

​Example Requests

​Error Responses

​Business Logic

​Application Scoping

​Data Relationships

​Filtering and Sorting

​Client-Side Filtering

​Use Cases

Tax Configuration Dashboard

Invoice Tax Selection

Compliance Reporting

Application Setup

​Detailed Examples

​Rate Limiting

​Best Practices

​Security Notes

​Related Endpoints

Endpoint Details

Authentication

Query Parameters

Optional Parameters

Response

Success Response (200 OK)

Response Fields

Tax Object

App Object

Example Requests

Error Responses

Business Logic

Application Scoping

Data Relationships

Filtering and Sorting

Client-Side Filtering

Use Cases

Detailed Examples

Rate Limiting

Best Practices

Security Notes

Related Endpoints