Many jurisdictions have a wide variety of taxes for selling goods and services, such as sales and VAT taxes.

The taxRate object helps you define, categorize, and set tax rates for your payment methods based upon geography, type, and exact percentage amount for collection and accounting.

After creating a taxRate, you can apply them by passing them their id into a given payment method.

The tax rate object

Let's take a look at a full taxRate object:

{
  "id": "taxRate_c80791a7ef6e4ff89627b1807aeac1a8",
  "active": false,
  "country": "US",
  "name": "International Tax Rate",
  "description": "This tax rate is scoped to your international customers.",
  "percentageDecimal": 0.03,
  "percentage": "300",
  "inclusive": false,
  "jurisdiction": "01242",
  "state": "San Francisco",
  "type": "salesTax",
  "meta": {
    "uuid": "123e4567-e89b-12d3-a456-426614174000",
  },
  "updated": "2021-01-01T00:00:00.000Z",
  "created": "2021-01-01T00:00:00.000Z"
}

id: string Unique identifier for the object. Auto-generated by Sphere upon creation.

active: boolean Denotes whether the tax rate will successfully apply upon payment.

country: string Identifies the country that this tax rate is for. Uses ISO 3166 alpha-2.

name: string The name of the tax rate for your reference. Hidden from customers. Max length (500).

description: string Describes your tax rate. Hidden from customers. Max length (500).

percentageDecimal: number The percentage, in decimal form, of the tax rate to apply.

percentage: number The percentage, in basis points, of the tax rate to apply.

inclusive: boolean Denotes whether the tax rate will be applied during payment.

true means that the tax rate is inclusive, meaning that your price already includes taxes.
- Hence, the billing engine will not apply the tax rate you've defined on-top.
false means that the tax rate is exclusive, meaning that your price does not include taxes.
- Hence, the billing engine will apply the tax rate you've defined on-top.
Note: price objects have a field for taxBehavior, which identifies whether the set price is inclusive or exclusive of taxes. However, this is for your accounting purposes. The billing engine will assume whatever behavior is defined in the taxRate object, and apply the tax on-top if inclusive is false.

jurisdiction: string Identifies the postal code for the jurisdiction that this tax rate is for.

state: string Identifies the state, region, or county that this tax rate is for.

type: enum Identifies the type of tax. One of salesTax and valueAddedTax.

meta: object Set of key-value pairs (JSON) for arbitrary usage. Used to save structured information about the object to reference elsewhere. Think of it as general purpose storage space.

updated: string datetime for when the tax rate was last updated.

created:string datetime for when the tax rate was created.