Sales Tax API Client for .NET / C#
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
build Version 2.2.0 Sep 18, 2018
src Version 2.2.0 Sep 18, 2018
.gitignore Update gitignore Apr 5, 2018
LICENSE.txt Update README, add LICENSE Sep 20, 2016
README.md Version 2.2.0 Sep 18, 2018

README.md

TaxJar Sales Tax API for .NET / C#

Official .NET / C# client for SmartCalcs by TaxJar. For the API documentation, please visit http://developers.taxjar.com/api.

Getting Started

We recommend installing TaxJar.net via NuGet. Before authenticating, get your API key from TaxJar.

Use the NuGet package manager inside Visual Studio, Xamarin Studio, or run the following command in the Package Manager Console:

PM> Install-Package TaxJar

Package Dependencies

TaxJar.net comes with assemblies for .NET 4.5.2 and .NET Standard 2.0. It requires the following dependencies:

These packages are automatically included when installing via NuGet.

Authentication

To authenticate with our API, add a new AppSetting with your TaxJar API key to your project's Web.config / App.config file or directly supply the API key when instantiating the client:

Method A

<!-- Web.config / App.config -->
<appSettings>
...
  <add key="TaxjarApiKey" value="[Your TaxJar API Key]" />
...
</appSettings>
var client = new TaxjarApi();

Method B

var client = new TaxjarApi("[Your TaxJar API Key]");

Usage

List all tax categories

var categories = client.Categories();

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

var rates = client.RatesForLocation("90002", new {
  city = "LOS ANGELES",
  country = "US"
});

Calculate sales tax for an order

var rates = client.TaxForOrder(new {
  from_country = "US",
  from_zip = "07001",
  from_state = "NJ",
  to_country = "US",
  to_zip = "07446",
  to_state = "NJ",
  amount = 16.50,
  shipping = 1.50
});

List order transactions

var orders = client.ListOrders(new {
	from_transaction_date = "2015/05/01",
	to_transaction_date = "2015/05/31"
});

Show order transaction

var order = client.ShowOrder("123");

Create order transaction

var order = client.CreateOrder(new {
  transaction_id = "123",
  transaction_date = "2015/05/04",
  to_country = "US",
  to_zip = "90002",
  to_city = "Los Angeles",
  to_street = "123 Palm Grove Ln",
  amount = 17,
  shipping = 2,
  sales_tax = 0.95,
  line_items = new[] {
    new {
      quantity = 1,
      product_identifier = "12-34243-0",
      description = "Heavy Widget",
      unit_price = 15,
      sales_tax = 0.95
    }
  }
});

Update order transaction

var order = client.UpdateOrder(new
{
  transaction_id = "123",
  amount = 17,
  shipping = 2,
  line_items = new[] {
    new {
      quantity = 1,
      product_identifier = "12-34243-0",
      description = "Heavy Widget",
      unit_price = 15,
      discount = 0,
      sales_tax = 0.95
    }
  }
});

Delete order transaction

var order = client.DeleteOrder("123");

List refund transactions

var refunds = client.ListRefunds(new
{
  from_transaction_date = "2015/05/01",
  to_transaction_date = "2015/05/31"
});

Show refund transaction

var refund = client.ShowRefund("321");

Create refund transaction

var refund = client.CreateRefund(new
{
  transaction_id = "321",
  transaction_date = "2015/05/04",
  transaction_reference_id = "123",
  to_country = "US",
  to_zip = "90002",
  to_city = "Los Angeles",
  to_street = "123 Palm Grove Ln",
  amount = 17,
  shipping = 2,
  sales_tax = 0.95,
  line_items = new[] {
    new {
      quantity = 1,
      product_identifier = "12-34243-0",
      description = "Heavy Widget",
      unit_price = 15,
      sales_tax = 0.95
    }
  }
});

Update refund transaction

var refund = client.UpdateRefund(new
{
  transaction_id = "321",
  amount = 17,
  shipping = 2,
  line_items = new[] {
    new {
      quantity = 1,
      product_identifier = "12-34243-0",
      description = "Heavy Widget",
      unit_price = 15,
      discount = 0,
      sales_tax = 0.95
    }
  }
});

Delete refund transaction

var refund = client.DeleteRefund("321");

List customers

var customers = client.ListCustomers();

Show customer

var customer = client.ShowCustomer("123");

Create customer

var customer = client.CreateCustomer(new {
  customer_id = "123",
  exemption_type = "wholesale",
  name = "Dunder Mifflin Paper Company",
  exempt_regions = new[] {
    new {
      country = "US",
      state = "FL"
    },
    new {
      country = "US",
      state = "PA"
    }
  },
  country = "US",
  state = "PA",
  zip = "18504",
  city = "Scranton",
  street = "1725 Slough Avenue"
});

Update customer

var customer = client.UpdateCustomer(new {
  customer_id = "123",
  exemption_type = "wholesale",
  name = "Sterling Cooper",
  exempt_regions = new[] {
    new {
      country = "US",
      state = "NY"
    }
  },
  country = "US",
  state = "NY",
  zip = "10010",
  city = "New York",
  street = "405 Madison Ave"
});

Delete customer

var customer = client.DeleteCustomer("123");

List nexus regions

var nexusRegions = client.NexusRegions();

Validate a VAT number

var validation = client.Validate(new {
  vat = "FR40303265045"
});

Summarize tax rates for all regions

var summaryRates = client.SummaryRates();

Custom Options

You can pass additional options using SetApiConfig or when instantiating the client for the following:

Timeouts

// Custom timeout when instantiating the client
var client = new TaxjarApi("[Your TaxJar API Key]", new { apiUrl = "https://api.taxjar.com", timeout = 30 });

// Custom timeout via `SetApiConfig`
client.SetApiConfig("timeout", 30);

Sandbox Environment

You can easily configure the client to use the TaxJar Sandbox:

var client = new TaxjarApi("[Your TaxJar Sandbox API Key]", new { apiUrl = "https://api.sandbox.taxjar.com" });

For testing specific error response codes, pass the custom X-TJ-Expected-Response header:

client.SetApiConfig("headers", new Dictionary<string, string>
{
  { "X-TJ-Expected-Response", "422" }
});

Error Handling

When invalid data is sent to TaxJar or we encounter an error, we’ll throw a TaxjarException with the HTTP status code and error message. To catch these exceptions, refer to the example below. Click here for a list of common error response classes.

using Taxjar;
var client = new TaxjarApi();

try
{
  // Invalid request
  var order = client.CreateOrder(new {
    transaction_date = "2015/05/04",
    to_country = "US",
    to_state = "CA",
    to_zip = "90002",
    amount = 17.45,
    shipping = 1.5,
    sales_tax = 0.95
  });
}
catch(TaxjarException e)
{
  // 406 Not Acceptable – transaction_id is missing
  e.TaxjarError.Error;
  e.TaxjarError.Detail;
  e.TaxjarError.StatusCode;
}

Tests

We use NUnit and WireMock.Net for testing. Before running the specs, create a .env file inside the Taxjar.Tests directory with your sandbox API key:

TAXJAR_API_KEY=YOUR_TAXJAR_SANDBOX_API_KEY

More Information

More information can be found at TaxJar Developers.

License

TaxJar.net is released under the MIT License.

Support

Bug reports and feature requests should be filed on the GitHub issue tracking page.

Contributing

  1. Fork it
  2. Create your feature branch (git checkout -b my-new-feature)
  3. Commit your changes (git commit -am 'Add some feature')
  4. Push to the branch (git push origin my-new-feature)
  5. Create new pull request