tax

Collection: taxes

Tax rates are determined by the customer's shipping location. If you are within the United States, you can set is_live to true to automatically calculate live tax rates based on the customer's postal code. Otherwise, you can set up global taxes which don't change based on location, country taxes which change based on the country, regional taxes which change based on the customer's state/province, and local taxes which change based on the customer's city. If the location matches, the tax rate is applied. You can also specify whether or not this tax rate should also be applied to the shipping costs.

Once a tax rate is configured, it must be applied to an item category for it to be used by creating a tax_item_category resource.

Notes

If you want to add a Custom Tax Endpoint, you can set just name and type, and other fields will be set automatically.

Required Scopes

Full store_full_access
Read tax_settings_read
Write tax_settings_write

Actions

GET View a tax
PATCH Update a tax (send only the properties you want to modify)
PUT Replace a tax (send the entire representation)
DELETE Delete a tax
HEAD Get just the header response
OPTIONS Get a response explaining which HTTP methods are supported

Properties (13)

name String · Required · max 30

The name of this tax which will be displayed to the customer.

type String · Required

The type of tax rate which determines when this tax will be applied.

globalunioncountryregionlocalcustom_tax_endpoint
country String

The country which will be matched against the customer shipping country to determine if a country tax will be applied.

Two character ISO 3166-1-alpha-2 code.

region String · max 20

The region (also known as a state or province) which will be matched against the customer shipping region to determine if a regional tax will be applied.

2 characters if code exists, otherwise.

city String · Required · max 50

The city which will be matched against the customer shipping city to determine if a local tax will be applied.

Required when type is local.

is_live Boolean

Set to true if the tax rate will be determined automatically by the postal code.

service_provider String

If using a live tax rate service provider, this value can be set to determine which provider you would like to use.

""avalaracustom_taxtaxjaronesource
apply_to_shipping Boolean

Set to true if the tax rate will also be applied to the shipping costs.

use_origin_rates Boolean

For a Union tax type, set to true to use the origin country tax rates.

exempt_all_customer_tax_ids Boolean

Set to true to exempt all customers with a tax id.

rate Number · Required

The tax rate to be applied for this tax. For 10%, use 10.

Greater than 0.

date_created String (nullable) · Read-only

The date this resource was created.

date_modified String (nullable) · Read-only

The date this resource was last modified.

Link Relations (5)

self This Tax
fx:store GET PATCH PUT DELETE This Store
fx:tax_item_categories GET POST Tax Item Category relationships
fx:native_integrations GET POST Native Integrations for this service provider

Only present when the tax has a service provider configured.

https://api.foxycart.com/taxes/{id}
Available via fx:tax on applied_tax·fx:tax on item_taxes·fx:tax on tax_item_category

Example Representation

{
  "_links": {
    "curies": [
      {
        "name": "fx",
        "href": "https://api.foxycart.com/rels/{rel}",
        "templated": true
      }
    ],
    "self": {
      "href": "https://api.foxycart.com/taxes/123",
      "title": "This Tax"
    },
    "fx:store": {
      "href": "https://api.foxycart.com/stores/456",
      "title": "This Store"
    },
    "fx:tax_item_categories": {
      "href": "https://api.foxycart.com/taxes/123/tax_item_categories",
      "title": "Tax Item Category relationships"
    },
    "fx:native_integrations": {
      "href": "https://api.foxycart.com/native_integrations",
      "title": "Native Integrations for this service provider"
    }
  },
  "name": "TN",
  "type": "region",
  "country": "US",
  "region": "TN",
  "city": "",
  "is_live": false,
  "service_provider": "avalara",
  "apply_to_shipping": true,
  "use_origin_rates": false,
  "exempt_all_customer_tax_ids": false,
  "rate": 1,
  "date_created": null,
  "date_modified": null
}