Sales Tax API Client for PHP 5.5+
Official PHP client for Sales Tax API v2. For the REST documentation, please visit https://developers.taxjar.com/api.
Requirements
Installation
Authentication
Usage
Custom Options
Sandbox Environment
Error Handling
Testing
Use Composer and add taxjar-php
as a dependency:
composer require taxjar/taxjar-php
{
"require": {
"taxjar/taxjar-php": "^2.0"
}
}
If you get an error with composer require
, update your composer.json
directly and run composer update
.
require __DIR__ . '/vendor/autoload.php';
$client = TaxJar\Client::withApiKey($_ENV['TAXJAR_API_KEY']);
You're now ready to use TaxJar! Check out our quickstart guide to get up and running quickly.
categories
- List all tax categories
taxForOrder
- Calculate sales tax for an order
listOrders
- List order transactions
showOrder
- Show order transaction
createOrder
- Create order transaction
updateOrder
- Update order transaction
deleteOrder
- Delete order transaction
listRefunds
- List refund transactions
showRefund
- Show refund transaction
createRefund
- Create refund transaction
updateRefund
- Update refund transaction
deleteRefund
- Delete refund transaction
listCustomers
- List customers
showCustomer
- Show customer
createCustomer
- Create customer
updateCustomer
- Update customer
deleteCustomer
- Delete customer
ratesForLocation
- List tax rates for a location (by zip/postal code)
nexusRegions
- List nexus regions
validateAddress
- Validate an address
validate
- Validate a VAT number
summaryRates
- Summarize tax rates for all regions
The TaxJar API provides product-level tax rules for a subset of product categories. These categories are to be used for products that are either exempt from sales tax in some jurisdictions or are taxed at reduced rates. You need not pass in a product tax code for sales tax calculations on product that is fully taxable. Simply leave that parameter out.
$categories = $client->categories();
Shows the sales tax that should be collected for a given order.
$order_taxes = $client->taxForOrder([
'from_country' => 'US',
'from_zip' => '07001',
'from_state' => 'NJ',
'from_city' => 'Avenel',
'from_street' => '305 W Village Dr',
'to_country' => 'US',
'to_zip' => '07446',
'to_state' => 'NJ',
'to_city' => 'Ramsey',
'to_street' => '63 W Main St',
'amount' => 16.50,
'shipping' => 1.5,
'line_items' => [
[
'id' => '1',
'quantity' => 1,
'product_tax_code' => '31000',
'unit_price' => 15.0,
'discount' => 0
]
]
]);
echo $order_taxes->amount_to_collect;
// 1.26
Lists existing order transactions created through the API.
$orders = $client->listOrders([
'from_transaction_date' => '2015/05/01',
'to_transaction_date' => '2015/05/31'
]);
Shows an existing order transaction created through the API.
$order = $client->showOrder('123');
Creates a new order transaction.
$order = $client->createOrder([
'transaction_id' => '123',
'transaction_date' => '2015/05/14',
'from_country' => 'US',
'from_zip' => '92093',
'from_state' => 'CA',
'from_city' => 'La Jolla',
'from_street' => '9500 Gilman Drive',
'to_country' => 'US',
'to_zip' => '90002',
'to_state' => 'CA',
'to_city' => 'Los Angeles',
'to_street' => '123 Palm Grove Ln',
'amount' => 17.45,
'shipping' => 1.5,
'sales_tax' => 0.95,
'line_items' => [
[
'id' => '1',
'quantity' => 1,
'product_identifier' => '12-34243-9',
'description' => 'Fuzzy Widget',
'unit_price' => 15.0,
'discount': 0,
'sales_tax' => 0.95
]
]
]);
Updates an existing order transaction created through the API.
$order = $client->updateOrder([
'transaction_id' => '123',
'amount' => 17.95,
'shipping' => 2.0,
'line_items' => [
[
'quantity' => 1,
'product_identifier' => '12-34243-0',
'description' => 'Heavy Widget',
'unit_price' => 15.0,
'discount' => 0.0,
'sales_tax' => 0.95
]
]
]);
Deletes an existing order transaction created through the API.
$client->deleteOrder('123');
Lists existing refund transactions created through the API.
$refunds = $client->listRefunds([
'from_transaction_date' => '2015/05/01',
'to_transaction_date' => '2015/05/31'
]);
Shows an existing refund transaction created through the API.
$refund = $client->showRefund('123-refund');
Creates a new refund transaction.
$refund = $client->createRefund([
'transaction_id' => '123-refund',
'transaction_reference_id' => '123',
'transaction_date' => '2015/05/14',
'from_country' => 'US',
'from_zip' => '92093',
'from_state' => 'CA',
'from_city' => 'La Jolla',
'from_street' => '9500 Gilman Drive',
'to_country' => 'US',
'to_zip' => '90002',
'to_state' => 'CA',
'to_city' => 'Los Angeles',
'to_street' => '123 Palm Grove Ln',
'amount' => -17.45,
'shipping' => -1.5,
'sales_tax' => -0.95,
'line_items' => [
[
'id' => '1',
'quantity' => 1,
'product_identifier' => '12-34243-9',
'description' => 'Fuzzy Widget',
'unit_price' => -15.0,
'discount' => -0,
'sales_tax' => -0.95
]
]
]);
Updates an existing refund transaction created through the API.
$refund = $client->updateRefund([
'transaction_id' => '123-refund',
'transaction_reference_id' => '123',
'amount' => -17.95,
'shipping' => -2.0,
'line_items' => [
[
'id' => '1',
'quantity' => 1,
'product_identifier' => '12-34243-0',
'description' => 'Heavy Widget',
'unit_price' => -15.0,
'discount' => -0,
'sales_tax' => -0.95
]
]
]);
Deletes an existing refund transaction created through the API.
$client->deleteRefund('123-refund');
Lists existing customers created through the API.
$customers = $client->listCustomers();
Shows an existing customer created through the API.
$customer = $client->showCustomer('123');
Creates a new customer.
$customer = $client->createCustomer([
'customer_id' => '123',
'exemption_type' => 'wholesale',
'name' => 'Dunder Mifflin Paper Company',
'exempt_regions' => [
[
'country' => 'US',
'state' => 'FL'
],
[
'country' => 'US',
'state' => 'PA'
]
],
'country' => 'US',
'state' => 'PA',
'zip' => '18504',
'city' => 'Scranton',
'street' => '1725 Slough Avenue'
]);
Updates an existing customer created through the API.
$customer = $client->updateCustomer([
'customer_id' => '123',
'exemption_type' => 'wholesale',
'name' => 'Sterling Cooper',
'exempt_regions' => [
[
'country' => 'US',
'state' => 'NY'
]
],
'country' => 'US',
'state' => 'NY',
'zip' => '10010',
'city' => 'New York',
'street' => '405 Madison Ave'
]);
Deletes an existing customer created through the API.
$client->deleteCustomer('123');
Shows the sales tax rates for a given location.
Please note this method only returns the full combined rate for a given location. It does not support nexus determination, sourcing based on a ship from and ship to address, shipping taxability, product exemptions, customer exemptions, or sales tax holidays. We recommend using
taxForOrder
to accurately calculate sales tax for an order.
$rates = $client->ratesForLocation(90002, [
'city' => 'LOS ANGELES',
'country' => 'US'
]);
echo $rates->combined_rate;
// 0.09
Lists existing nexus locations for a TaxJar account.
$nexus_regions = $client->nexusRegions();
Validates a customer address and returns back a collection of address matches. Address validation requires a TaxJar Plus subscription.
$addresses = $client->validateAddress([
'country' => 'US',
'state' => 'AZ',
'zip' => '85297',
'city' => 'Gilbert',
'street' => '3301 South Greenfield Rd'
]);
Validates an existing VAT identification number against VIES.
$validation = $client->validate([
'vat' => 'FR40303265045'
]);
Retrieve minimum and average sales tax rates by region as a backup.
This method is useful for periodically pulling down rates to use if the TaxJar API is unavailable. However, it does not support nexus determination, sourcing based on a ship from and ship to address, shipping taxability, product exemptions, customer exemptions, or sales tax holidays. We recommend using
taxForOrder
to accurately calculate sales tax for an order.
$summarized_rates = $client->summaryRates();
You can easily configure the client to use the TaxJar Sandbox:
require __DIR__ . '/vendor/autoload.php';
$client = TaxJar\Client::withApiKey($_ENV['TAXJAR_SANDBOX_API_KEY']);
$client->setApiConfig('api_url', TaxJar\Client::SANDBOX_API_URL);
For testing specific error response codes, pass the custom X-TJ-Expected-Response
header:
$client->setApiConfig('headers', [
'X-TJ-Expected-Response' => 422
]);
This package utilizes Guzzle which defaults to a request timeout value of 0s, allowing requests to remain pending for an indefinite period of time.
You can modify this behavior by configuring the client with a
timeout
value in seconds.
$client->setApiConfig('timeout', 30);
By default, TaxJar's API will respond to requests with the latest API version when a version header is not present on the request.
To request a specific API version, include the
x-api-version
header with the desired version string.
$client->setApiConfig('headers', [
'x-api-version' => '2020-08-07'
]);
When invalid data is sent to TaxJar or we encounter an error, we’ll throw a TaxJar\Exception
with the HTTP status code and error message. To catch these exceptions, refer to the example below:
require __DIR__ . '/vendor/autoload.php';
$client = TaxJar\Client::withApiKey($_ENV['TAXJAR_API_KEY']);
try {
// Invalid request
$order = $client->createOrder([
'transaction_date' => '2015/05/14',
'from_country' => 'US',
'from_zip' => '07001',
'from_state' => 'NJ',
'from_city' => 'Avenel',
'from_street' => '305 W Village Dr',
'to_country' => 'US',
'to_zip' => '90002',
'to_state' => 'CA',
'to_city' => 'Ramsey',
'to_street' => '63 W Main St',
'amount' => 16.5,
'shipping' => 1.5,
'sales_tax' => 0.95,
'line_items' => [
[
'id' => '1',
'quantity' => 1,
'product_tax_code' => '31000',
'unit_price' => 15,
'discount' => 0,
'sales_tax' => 0.95
]
]
]);
} catch (TaxJar\Exception $e) {
// 406 Not Acceptable – transaction_id is missing
echo $e->getMessage();
// 406
echo $e->getStatusCode();
}
For a full list of error codes, click here.
Make sure PHPUnit is installed via composer install
and run the following:
php vendor/bin/phpunit test/specs/.
To enable debug mode, set the following config parameter after authenticating:
$client->setApiConfig('debug', true);