Tax Rates

Tax Rates

Access tax rate information in Teamleader Focus.

Overview

The Tax Rates resource provides read-only access to tax rates configured in your Teamleader account. Tax rates are used when creating invoices, quotations, and other financial documents to calculate taxes on line items.

Important: This resource is read-only. Tax rates are configured in Teamleader Focus settings and cannot be created or modified through the API.

Navigation

• Endpoint
• Capabilities
• Available Methods
• Helper Methods
• Response Structure
• Usage Examples
• Best Practices
• Related Resources

Endpoint

taxRates

Capabilities

• Pagination: ✅ Supported
• Filtering: ✅ Supported (department_id)
• Sorting: ✅ Supported (department_id, rate, description)
• Sideloading: ❌ Not Supported
• Creation: ❌ Not Supported
• Update: ❌ Not Supported
• Deletion: ❌ Not Supported

Available Methods

list()

Get all available tax rates, optionally filtered, sorted, and paginated.

Parameters:

• filters (array, optional): Filter options
  • department_id (string): Filter by department UUID
• options (array, optional): Pagination and sorting options
  • page_size (int): Results per page (default: 20)
  • page_number (int): Page number (default: 1)
  • sort (array): Sort configuration — [['field' => 'rate', 'order' => 'asc']]
    • Valid fields: department_id, rate, description

Example:

use McoreServices\TeamleaderSDK\Facades\Teamleader;

// Get all tax rates
$taxRates = Teamleader::taxRates()->list();

// Get tax rates for specific department
$taxRates = Teamleader::taxRates()->list([
    'department_id' => 'dept-uuid'
]);

// Sorted by rate ascending, with pagination
$taxRates = Teamleader::taxRates()->list([], [
    'sort' => [['field' => 'rate', 'order' => 'asc']],
    'page_size' => 50,
    'page_number' => 1
]);

Helper Methods

forDepartment()

Get tax rates for a specific department.

$taxRates = Teamleader::taxRates()->forDepartment('dept-uuid');

findByRate()

Find a tax rate by its exact rate value.

// Find 21% tax rate
$taxRate = Teamleader::taxRates()->findByRate(0.21);

findByDescription()

Find a tax rate by its description.

$taxRate = Teamleader::taxRates()->findByDescription('21%');

all()

Fetch all tax rates across all pages in a single call. Useful when you need the complete list regardless of pagination limits.

$all = Teamleader::taxRates()->all();
// Returns: ['data' => [...all tax rates...]]

// With a department filter
$all = Teamleader::taxRates()->all(['department_id' => 'dept-uuid']);

sortedByRate()

Get tax rates sorted by rate value ascending.

$taxRates = Teamleader::taxRates()->sortedByRate();

// With department filter
$taxRates = Teamleader::taxRates()->sortedByRate(['department_id' => 'dept-uuid']);

sortedByDescription()

Get tax rates sorted by description.

$taxRates = Teamleader::taxRates()->sortedByDescription();

// Descending order
$taxRates = Teamleader::taxRates()->sortedByDescription([], 'desc');

groupedByDepartment()

Get all tax rates grouped by their department UUID.

$grouped = Teamleader::taxRates()->groupedByDepartment();
// Returns: ['dept-uuid' => ['department' => [...], 'tax_rates' => [...]]]

asOptions()

Get tax rates formatted as key-value pairs for dropdowns.

$options = Teamleader::taxRates()->asOptions();
// Returns: ['uuid-1' => '21%', 'uuid-2' => '6%', ...]

// For specific department
$options = Teamleader::taxRates()->asOptions('dept-uuid');

Response Structure

List Response

{
  "data": [
    {
      "id": "uuid",
      "department": {
        "type": "department",
        "id": "uuid"
      },
      "description": "21%",
      "rate": 0.21
    },
    {
      "id": "uuid",
      "department": {
        "type": "department",
        "id": "uuid"
      },
      "description": "6%",
      "rate": 0.06
    },
    {
      "id": "uuid",
      "department": {
        "type": "department",
        "id": "uuid"
      },
      "description": "0%",
      "rate": 0.00
    }
  ]
}

Usage Examples

Get Available Tax Rates

$taxRates = Teamleader::taxRates()->list();

echo "Available tax rates:\n";
foreach ($taxRates['data'] as $rate) {
    echo "- {$rate['description']} ({$rate['rate']})\n";
}

Use in Invoice Line Items

// Get standard VAT rate
$standardVat = Teamleader::taxRates()->findByRate(0.21);

$invoice = Teamleader::invoices()->create([
    'invoice_date' => '2024-02-01',
    'invoicee' => [...],
    'grouped_lines' => [
        [
            'line_items' => [
                [
                    'quantity' => 2,
                    'description' => 'Product A',
                    'unit_price' => [
                        'amount' => 100.00,
                        'tax' => 'excluding'
                    ],
                    'tax_rate_id' => $standardVat['id']
                ]
            ]
        ]
    ]
]);

Create Dropdown for Tax Rates

$options = Teamleader::taxRates()->asOptions();

echo '<select name="tax_rate_id">';
foreach ($options as $id => $description) {
    echo "<option value='{$id}'>{$description}</option>";
}
echo '</select>';

Calculate Tax Amount

$amount = 100.00;
$taxRate = Teamleader::taxRates()->findByRate(0.21);

$taxAmount = $amount * $taxRate['rate'];
$totalWithTax = $amount + $taxAmount;

echo "Amount: €{$amount}\n";
echo "Tax ({$taxRate['description']}): €{$taxAmount}\n";
echo "Total: €{$totalWithTax}\n";

Best Practices

1. Cache Tax Rates

Tax rates rarely change, so cache them to reduce API calls:

use Illuminate\Support\Facades\Cache;

$taxRates = Cache::remember('tax_rates', 86400, function () {
    return Teamleader::taxRates()->list();
});

2. Department-Specific Rates

If you work with multiple departments, cache per department:

$departmentId = 'dept-uuid';
$cacheKey = "tax_rates_{$departmentId}";

$taxRates = Cache::remember($cacheKey, 86400, function () use ($departmentId) {
    return Teamleader::taxRates()->forDepartment($departmentId);
});

3. Validate Tax Rate Exists

$taxRateId = $request->input('tax_rate_id');
$taxRate = Teamleader::taxRates()->findByRate($expectedRate);

if (!$taxRate || $taxRate['id'] !== $taxRateId) {
    throw new ValidationException('Invalid tax rate');
}

4. Use Helper Methods

// Good: Clear and concise
$vatRate = Teamleader::taxRates()->findByRate(0.21);

// Less ideal: Manual searching
$rates = Teamleader::taxRates()->list();
$vatRate = null;
foreach ($rates['data'] as $rate) {
    if ($rate['rate'] === 0.21) {
        $vatRate = $rate;
        break;
    }
}

Related Resources

• Invoices - Invoice management
• Withholding-Tax-Rates - Withholding tax information
• Quotations - Quotation management