Create a product tax rule

POST https://api.tamio.com/v2/taxes/product-tax/create

Creates a new product tax rule with geographical targeting, payment method filtering, and flexible application scope. The tax can apply to all products, selected products, or selected categories. Specify either a percentage rate or a fixed amount (when rate is 0).

Body Parameters

label string*

Human-readable name for the tax rule.

rate number*

Percentage tax rate (0–100). When 0, a fixed amount is required.

amount number

Fixed tax amount in smallest currency unit. Required when rate is 0.

country string*

Country code where the tax applies.

active boolean

Whether the tax rule is active.

applies_to string*

all_products — applies to every product; selected_products — requires products array; selected_categories — requires categories object.

all_productsselected_productsselected_categories

states array of string

State/province codes to restrict the tax to (up to 10).

postcodes array of string

Postal codes to restrict the tax to (up to 10, max 10 characters each).

payments array of string

Payment methods this tax applies to. Use ["all"] for all methods (default).

products array of string

Product UUIDs (required when applies_to is selected_products).

categories object

Category selections (required when applies_to is selected_categories).

JSON

{ "categories": { "digital": [ "ebooks", "software" ], "services": [ "consulting" ] } }

physical array of string

Physical product categories.

digital array of string

Digital product categories.

services array of string

Service categories.

billing_plans array of string

Billing plan categories.

Responses

200 Product tax rule created

Product tax rule created

status integer

tax Tax

400 Validation or business-logic error.

Validation or business-logic error.

Code	Description
`400`	Invalid request (e.g. selected_products scope with no products provided)
`1002`	One or more referenced products not found
`10239`	Fair use limit reached for tax rules

status integer

error string

error_code integer

401 Missing or invalid API key

Retrieve a tax rule

Update a product tax rule

/taxes/product-tax/create

1 const response = await fetch("https://api.tamio.com/v2/taxes/product-tax/create", {
2   method: "POST",
3   headers: {
4     "Authorization": "Bearer YOUR_API_KEY",
5     "Content-Type": "application/json"
6   },
7   body: JSON.stringify({
8     "label": "EU VAT 20%",
9     "rate": 20,
10     "amount": 0,
11     "country": "GB",
12     "active": true,
13     "applies_to": "all_products",
14     "states": [
15       "CA",
16       "NY"
17     ],
18     "postcodes": [
19       "10001",
20       "90210"
21     ],
22     "payments": [
23       "all"
24     ],
25     "products": [
26       "ccc34567-e89b-12d3-a456-426614174000"
27     ],
28     "categories": {
29       "digital": [
30         "ebooks",
31         "software"
32       ],
33       "services": [
34         "consulting"
35       ]
36     }
37   })
38 });
39 const data = await response.json();

1 require "uri"
2 require "net/http"
3 require "json"
4 
5 url = URI("https://api.tamio.com/v2/taxes/product-tax/create")
6 
7 https = Net::HTTP.new(url.host, url.port)
8 https.use_ssl = true
9 
10 request = Net::HTTP::Post.new(url)
11 request["Accept"] = "application/json"
12 request["Authorization"] = "Bearer YOUR_API_KEY"
13 request["Content-Type"] = "application/json"
14 request.body = {
15   label: "EU VAT 20%",
16   rate: 20,
17   amount: 0,
18   country: "GB",
19   active: true,
20   applies_to: "all_products",
21   states: ["CA", "NY"],
22   postcodes: ["10001", "90210"],
23   payments: ["all"],
24   products: ["ccc34567-e89b-12d3-a456-426614174000"],
25   categories: {
26     digital: ["ebooks", "software"],
27     services: ["consulting"]
28   }
29 }.to_json
30 
31 response = https.request(request)
32 puts response.read_body

Responses

{
  "status": 200,
  "tax": {
    "id": "aaa14567-e89b-12d3-a456-426614174000",
    "object": "tax",
    "rate": 0.2,
    "amount": 0,
    "label": "EU VAT 20%",
    "active": true,
    "country": "GB",
    "type": "product_tax",
    "applies_to": "all_products",
    "postcodes": null,
    "states": null,
    "payments": null,
    "categories": null,
    "products": null
  }
}

1	const response = await fetch("https://api.tamio.com/v2/taxes/product-tax/create", {
2	method: "POST",
3	headers: {
4	"Authorization": "Bearer YOUR_API_KEY",
5	"Content-Type": "application/json"
6	},
7	body: JSON.stringify({
8	"label": "EU VAT 20%",
9	"rate": 20,
10	"amount": 0,
11	"country": "GB",
12	"active": true,
13	"applies_to": "all_products",
14	"states": [
15	"CA",
16	"NY"
17	],
18	"postcodes": [
19	"10001",
20	"90210"
21	],
22	"payments": [
23	"all"
24	],
25	"products": [
26	"ccc34567-e89b-12d3-a456-426614174000"
27	],
28	"categories": {
29	"digital": [
30	"ebooks",
31	"software"
32	],
33	"services": [
34	"consulting"
35	]
36	}
37	})
38	});
39	const data = await response.json();

1	require "uri"
2	require "net/http"
3	require "json"
4
5	url = URI("https://api.tamio.com/v2/taxes/product-tax/create")
6
7	https = Net::HTTP.new(url.host, url.port)
8	https.use_ssl = true
9
10	request = Net::HTTP::Post.new(url)
11	request["Accept"] = "application/json"
12	request["Authorization"] = "Bearer YOUR_API_KEY"
13	request["Content-Type"] = "application/json"
14	request.body = {
15	label: "EU VAT 20%",
16	rate: 20,
17	amount: 0,
18	country: "GB",
19	active: true,
20	applies_to: "all_products",
21	states: ["CA", "NY"],
22	postcodes: ["10001", "90210"],
23	payments: ["all"],
24	products: ["ccc34567-e89b-12d3-a456-426614174000"],
25	categories: {
26	digital: ["ebooks", "software"],
27	services: ["consulting"]
28	}
29	}.to_json
30
31	response = https.request(request)
32	puts response.read_body