TaxJar Sales Tax API for PHP

Official PHP client for Sales Tax API v2. For the REST documentation, please visit http://developers.taxjar.com/api.

Requirements

PHP 5.5.0 and later.
Guzzle (included via Composer).

Installation

Use Composer and add taxjar-php as a dependency:

composer require taxjar/taxjar-php

{
  "require": {
    "taxjar/taxjar-php": "^1.5"
  }
}

If you get an error with composer require, update your composer.json directly and run composer update.

Authentication

require __DIR__ . '/vendor/autoload.php';
$client = TaxJar\Client::withApiKey($_ENV['TAXJAR_API_KEY']);

Usage

List all tax categories

$categories = $client->categories();

List tax rates for a location (by zip/postal code)

$rates = $client->ratesForLocation(90002, [
  'city' => 'LOS ANGELES',
  'country' => 'US'
]);

echo $rates->combined_rate;
// 0.09

Calculate sales tax for an order

$order_taxes = $client->taxForOrder([
  'from_country' => 'US',
  'from_zip' => '07001',
  'from_state' => 'NJ',
  'to_country' => 'US',
  'to_zip' => '07446',
  'to_state' => 'NJ',
  'amount' => 16.50,
  'shipping' => 1.5,
  'line_items' => [
    [
      'quantity' => 1,
      'unit_price' => 15.0,
      'product_tax_code' => 31000
    ]
  ]
]);

echo $order_taxes->amount_to_collect;
// 1.26

List order transactions

$orders = $client->listOrders([
  'from_transaction_date' => '2014/01/01',
  'to_transaction_date' => '2015/05/30'
]);

Show order transaction

$order = $client->showOrder('123');

Create order transaction

$order = $client->createOrder([
  'transaction_id' => '123',
  'transaction_date' => '2015/05/14',
  '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' => [
    [
      'quantity' => 1,
      'product_identifier' => '12-34243-9',
      'description' => 'Fuzzy Widget',
      'unit_price' => 15.0,
      'sales_tax' => 0.95
    ]
  ]
]);

Update order transaction

$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
    ]
  ]
]);

Delete order transaction

$client->deleteOrder('123');

List refund transactions

$refunds = $client->listRefunds([
  'from_transaction_date' => '2014/01/01',
  'to_transaction_date' => '2015/05/30'
]);

Show refund transaction

$refund = $client->showRefund('321');

Create refund transaction

$refund = $client->createRefund([
  'transaction_id' => '321',
  'transaction_date' => '2015/05/14',
  'transaction_reference_id' => '123',
  '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' => [
    [
      'quantity' => 1,
      'product_identifier' => '12-34243-9',
      'description' => 'Fuzzy Widget',
      'unit_price' => 15.0,
      'sales_tax' => 0.95
    ]
  ]
]);

Update refund transaction

$refund = $client->updateRefund([
  'transaction_id' => '321',
  'amount' => 17.95,
  'shipping' => 2.0,
  'line_items' => [
    [
      'quantity' => 1,
      'product_identifier' => '12-34243-0',
      'description' => 'Heavy Widget',
      'unit_price' => 15.0,
      'sales_tax' => 0.95
    ]
  ]
]);

Delete refund transaction

$client->deleteRefund('321');

List nexus regions

$nexus_regions = $client->nexusRegions();

Validate a VAT number

$validation = $client->validate([
  'vat' => 'FR40303265045'
]);

Summarize tax rates for all regions

$summarized_rates = $client->summaryRates();

Error Handling

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',
    'to_country' => 'US',
    'to_zip' => '90002',
    'to_state' => 'CA',
    'amount' => 16.5,
    'shipping' => 1.5,
    '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.

Testing

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);

srdjanmarjanovic / taxjar-php