Skip to content

Commit 734652e

Browse files
declankirkdeclankirk
committed
docs(tax): TAX-1750 add store operations docs for tax customers and tax property type field
1 parent 5bf1992 commit 734652e

File tree

2 files changed

+210
-37
lines changed

2 files changed

+210
-37
lines changed

‎docs/store-operations/tax/tax-customers.mdx

+145
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,145 @@
1+
---
2+
title: Tax Customers
3+
keywords: tax customers, tax
4+
---
5+
6+
# Tax Customers
7+
8+
The Tax Customers API allows merchants to configure customer-specific tax data for use in tax calculations. This enables merchants to provide tax providers with additional customer-related information that may affect tax rates or exemptions.
9+
10+
This guide demonstrates how to use the Tax Customers API. For more, see the [Tax Customers API Reference](/docs/rest-management/tax-customers).
11+
12+
## Tax customers
13+
14+
Tax customers rely on `customer_id` to associate tax data with specific customers. This data is sent to tax providers during tax calculations. The examples below demonstrate how to create, update, retrieve, and delete tax customer data.
15+
16+
### Get tax customers
17+
18+
To retrieve a list of tax customers, send a request to the [Get Tax Customers](/docs/rest-management/tax-customers#get-tax-customers) endpoint. You can filter the results by specifying one or more `customer_id` values.
19+
20+
<Tabs items={[`Request`, `Response`]}>
21+
<Tab>
22+
```http filename="Example request: Get tax customers" showLineNumbers copy
23+
GET https://api.bigcommerce.com/stores/{{STORE_HASH}}/v3/tax/customers?customer_id:in=157,158
24+
X-Auth-Token: {{ACCESS_TOKEN}}
25+
Content-Type: application/json
26+
Accept: application/json
27+
```
28+
</Tab>
29+
<Tab>
30+
```json filename="Example response: Get tax customers" showLineNumbers copy
31+
{
32+
"data": [
33+
{
34+
"customer_id": 157,
35+
"tax_properties": {
36+
"A-123456789": "26",
37+
"B-6731789": "200"
38+
}
39+
},
40+
{
41+
"customer_id": 158,
42+
"tax_properties": {
43+
"A-123456789": "15"
44+
}
45+
}
46+
],
47+
"meta": {
48+
"pagination": {
49+
"total": 2,
50+
"count": 2,
51+
"per_page": 50,
52+
"current_page": 1,
53+
"total_pages": 1,
54+
"links": {
55+
"current": "?customer_id%3Ain=157%2C158&page=1&limit=50"
56+
}
57+
}
58+
}
59+
}
60+
```
61+
</Tab>
62+
</Tabs>
63+
64+
### Update tax customers
65+
66+
To add or update tax data for one or more customers, send a request to the [Update Tax Customers](/docs/rest-management/tax-customers#update-tax-customers) endpoint. This operation overwrites any existing values for the specified customers.
67+
68+
<Tabs items={[`Request`, `Response`]}>
69+
<Tab>
70+
```http filename="Example request: Update tax customers" showLineNumbers copy
71+
PUT https://api.bigcommerce.com/stores/{{STORE_HASH}}/v3/tax/customers
72+
X-Auth-Token: {{ACCESS_TOKEN}}
73+
Content-Type: application/json
74+
Accept: application/json
75+
76+
[
77+
{
78+
"customer_id": 157,
79+
"tax_properties": {
80+
"A-123456789": "30",
81+
"B-6731789": "250"
82+
}
83+
},
84+
{
85+
"customer_id": 159,
86+
"tax_properties": {
87+
"A-123456789": "10"
88+
}
89+
}
90+
]
91+
```
92+
</Tab>
93+
<Tab>
94+
```json filename="Example response: Update tax customers" showLineNumbers copy
95+
{
96+
"data": [
97+
{
98+
"customer_id": 157,
99+
"tax_properties": {
100+
"A-123456789": "30",
101+
"B-6731789": "250"
102+
}
103+
},
104+
{
105+
"customer_id": 159,
106+
"tax_properties": {
107+
"A-123456789": "10"
108+
}
109+
}
110+
],
111+
"meta": {}
112+
}
113+
```
114+
</Tab>
115+
</Tabs>
116+
117+
### Delete tax customers
118+
119+
To delete tax data associated with one or more customers, send a request to the [Delete Tax Customers](/docs/rest-management/tax-customers#delete-tax-customers) endpoint. Use the `customer_id:in` query parameter to specify the customers whose tax data you want to delete.
120+
121+
<Callout type="warning">
122+
#### Batch deletion
123+
This operation removes **all** tax properties associated with the specified customers.
124+
</Callout>
125+
126+
<Tabs items={[`Request`, `Response`]}>
127+
<Tab>
128+
```http filename="Example request: Delete tax customers" showLineNumbers copy
129+
DELETE https://api.bigcommerce.com/stores/{{STORE_HASH}}/v3/tax/customers?customer_id:in=157
130+
X-Auth-Token: {{ACCESS_TOKEN}}
131+
Content-Type: application/json
132+
Accept: application/json
133+
```
134+
</Tab>
135+
<Tab>
136+
```http filename="Example response: Delete tax customers" showLineNumbers copy
137+
HTTP 204 No content
138+
```
139+
</Tab>
140+
</Tabs>
141+
142+
## Resources
143+
- [Tax Customers API Reference](/docs/rest-management/tax-customers)
144+
- [Tax Properties API Reference](/docs/rest-management/tax-properties)
145+
- [Tax Provider API Reference](/docs/rest-contracts/tax)

‎docs/store-operations/tax/tax-properties.mdx

+65-37
Original file line numberDiff line numberDiff line change
@@ -1,25 +1,27 @@
11
---
2-
title: Tax Properties for Products
3-
keywords: get all products, tax, tax properties,
2+
title: Tax Properties
3+
keywords: tax, tax properties,
44
---
55

6-
# Tax Properties for Products
6+
# Tax Properties
77

8-
The Tax Properties API allows merchants to vary the tax information they send to tax providers for tax calculation. In some jurisdictions, tax rates for products vary by product composition. For example, accurate taxation of alcohol may require information about alcohol percentage. Using tax properties, providers can return more accurate tax quotes. The examples in this guide expand on this use case.
8+
The Tax Properties API allows merchants to vary the tax information they send to tax providers for tax calculation. In some jurisdictions, tax rates for products vary by product composition. For example, accurate taxation of alcohol may require information about alcohol percentage. Using tax properties, providers can return more accurate tax quotes. The examples in this guide expand on this use case.
99

1010
Tax providers may sometimes need multiple inputs that can vary between different types of product. For example, for products with alcohol, the alcohol percentage and the volume sold affect alcohol taxes. As shown in this guide, merchants can provide both pieces of information to tax providers.
1111

12+
The API also supports **customer tax properties**, which allow merchants to provide customer-specific tax information to tax providers. These properties can influence how tax is calculated based on the customer making the purchase.
13+
1214
<Callout type="info">
1315
#### Tax properties versus tax codes
14-
A tax code is a single code that tax providers use to invoke specific rules when calculating tax on a product.
15-
In contrast, tax properties are fields that contain information about product specifics. Tax providers use these fields to factor product specifics into their calculations.
16+
A tax code is a single code that tax providers use to invoke specific rules when calculating tax on a product or customer.
17+
In contrast, tax properties are fields that contain information about product or customer specifics. Tax providers use these fields to factor product or customer specifics into their calculations.
1618
</Callout>
1719

18-
This guide demonstrates how to use the Tax Properties API. For more, see the [Tax Properties API Reference](/docs/rest-management/tax-properties) and the [Tax Provider API Reference](/docs/rest-contracts/tax).
20+
This guide demonstrates how to use the Tax Properties API. For more, see the [Tax Properties API Reference](/docs/rest-management/tax-properties) and the [Tax Provider API Reference](/docs/rest-contracts/tax).
1921

2022
## Tax properties
2123

22-
Tax properties rely on `code`s specific to third-party tax providers. Consult a tax provider's documentation to identify supported `code`s. The `code`s used in tax properties are not tax codes. See [Tax properties versus tax codes](#tax-properties-versus-tax-codes).
24+
Tax properties rely on `code`s specific to third-party tax providers. Consult a tax provider's documentation to identify supported `code`s. The `code`s used in tax properties are not tax codes. See [Tax properties versus tax codes](#tax-properties-versus-tax-codes).
2325

2426
### Create tax properties
2527

@@ -40,12 +42,14 @@ The response provides an `id` for each tax property. Use the `id` to get, update
4042
"code": "alcohol-percentage",
4143
"display_name": "Alcohol Percentage",
4244
"description": "Beverage Industry"
45+
"type": "PRODUCT"
4346
},
4447
{
45-
"code": "fuel-type",
46-
"display_name": "Fuel Type",
47-
"description": "Oil and Natural Gas Industry"
48-
}
48+
"code": "erp-external-id",
49+
"display_name": "ERP Customer ID",
50+
"description": "External ID used to link customer records with ERP systems"
51+
"type": "CUSTOMER"
52+
}
4953
]
5054
```
5155
</Tab>
@@ -59,15 +63,17 @@ The response provides an `id` for each tax property. Use the `id` to get, update
5963
"display_name": "Alcohol Percentage",
6064
"description": "Beverage Industry",
6165
"created_at": "2022-05-17T14:25:21+00:00",
62-
"updated_at": "2022-05-17T14:25:21+00:00"
66+
"updated_at": "2022-05-17T14:25:21+00:00",
67+
"type": "PRODUCT"
6368
},
6469
{
6570
"id": 2,
66-
"code": "fuel-type",
67-
"display_name": "Fuel Type",
68-
"description": "Oil and Natural Gas Industry",
71+
"code": "erp-external-id",
72+
"display_name": "ERP Customer ID",
73+
"description": "External ID used to link customer records with ERP systems",
6974
"created_at": "2022-05-17T14:25:21+00:00",
70-
"updated_at": "2022-05-17T14:25:21+00:00"
75+
"updated_at": "2022-05-17T14:25:21+00:00",
76+
"type": "CUSTOMER"
7177
}
7278
],
7379
"meta": {}
@@ -78,7 +84,7 @@ The response provides an `id` for each tax property. Use the `id` to get, update
7884

7985
### Update tax properties
8086

81-
Send a request to the [Update tax properties](/docs/rest-management/tax-properties#update-tax-properties) endpoint to modify a tax property's `code`, `display_name`, or `description`. The request updates only fields that you specify.
87+
Send a request to the [Update tax properties](/docs/rest-management/tax-properties#update-tax-properties) endpoint to modify a tax property's `code`, `display_name`, or `description`. The request updates only fields that you specify.
8288

8389
<Tabs items={[`Request`, `Response`]}>
8490
<Tab>
@@ -92,12 +98,12 @@ Send a request to the [Update tax properties](/docs/rest-management/tax-properti
9298
{
9399
"id": 1,
94100
"description": "Alcohol Industry"
95-
}
101+
}
96102
]
97103
```
98104
</Tab>
99105
<Tab>
100-
```json filename="Example response: Update tax properties" showLineNumbers
106+
```json filename="Example response: Update tax properties" showLineNumbers
101107
{
102108
"data": [
103109
{
@@ -106,7 +112,8 @@ Send a request to the [Update tax properties](/docs/rest-management/tax-properti
106112
"display_name": "Alcohol Percentage",
107113
"description": "Alcohol Industry",
108114
"created_at": "2022-05-17T14:25:21+00:00",
109-
"updated_at": "2022-05-21T14:25:21+00:00"
115+
"updated_at": "2022-05-21T14:25:21+00:00",
116+
"type": "PRODUCT"
110117
}
111118
],
112119
"meta": {}
@@ -138,15 +145,17 @@ This endpoint supports batch operations. You can get all the tax properties in y
138145
"display_name": "Alcohol Percentage",
139146
"description": "Alcohol Industry",
140147
"created_at": "2022-05-17T14:25:21+00:00",
141-
"updated_at": "2022-05-21T14:25:21+00:00"
148+
"updated_at": "2022-05-21T14:25:21+00:00",
149+
"type": "PRODUCT"
142150
},
143151
{
144152
"id": 2,
145-
"code": "fuel-type",
146-
"display_name": "Fuel Type",
147-
"description": "Oil and Natural Gas Industry",
153+
"code": "erp-external-id",
154+
"display_name": "ERP Customer ID",
155+
"description": "External ID used to link customer records with ERP systems",
148156
"created_at": "2022-05-17T14:25:21+00:00",
149-
"updated_at": "2022-05-17T14:25:21+00:00"
157+
"updated_at": "2022-05-17T14:25:21+00:00",
158+
"type": "CUSTOMER"
150159
}
151160
],
152161
"meta": {
@@ -180,17 +189,17 @@ To delete tax properties, send a request to the [Delete tax properties](/docs/re
180189
```
181190
</Tab>
182191
<Tab>
183-
```http filename="Example response: Delete tax properties" showLineNumbers
192+
```http filename="Example response: Delete tax properties" showLineNumbers
184193
HTTP 204 No content
185194
```
186195
</Tab>
187196
</Tabs>
188197

189-
## Product tax properties
198+
## Product tax properties
190199

191-
After [creating a tax property](#create-tax-properties), you can attach it to a base product to create a product tax property. To do so, specify the product using its `product_id`. The `product_id` is the `id` from the [Get all products](/docs/rest-catalog/products#get-all-products) endpoint.
200+
After [creating a tax property](#create-tax-properties), you can attach it to a base product to create a product tax property. To do so, specify the product using its `product_id`. The `product_id` is the `id` from the [Get all products](/docs/rest-catalog/products#get-all-products) endpoint.
192201

193-
You can add multiple tax properties to a single product. The following example shows tax properties attached to alcohol products. In this example, the tax rate of alcohol products varies by both alcohol percentage and net volume.
202+
You can add multiple tax properties to a single product. The following example shows tax properties attached to alcohol products. In this example, the tax rate of alcohol products varies by both alcohol percentage and net volume.
194203

195204
<Callout type="info">
196205
#### Tax properties aren't product properties
@@ -261,11 +270,11 @@ To attach tax properties to a product, send a request to the [Update product tax
261270
}
262271
```
263272
</Tab>
264-
</Tabs>
273+
</Tabs>
265274

266-
### Get product tax properties
275+
### Get product tax properties
267276

268-
To get the tax properties attached to a product, send a request to the [Get product tax properties](/docs/rest-management/tax-properties/product-tax-properties#get-product-tax-properties) endpoint and use the `product_id:in` query parameter.
277+
To get the tax properties attached to a product, send a request to the [Get product tax properties](/docs/rest-management/tax-properties/product-tax-properties#get-product-tax-properties) endpoint and use the `product_id:in` query parameter.
269278

270279
<Tabs items={[`Request`, `Response`]}>
271280
<Tab>
@@ -319,7 +328,7 @@ To get the tax properties attached to a product, send a request to the [Get prod
319328
This endpoint removes **all** tax properties from a given product.
320329
</Callout>
321330

322-
To remove tax properties from a product, send a request to the [Delete product tax properties](/docs/rest-management/tax-properties/product-tax-properties#delete-product-tax-properties) endpoint and use the `product_id:in` query parameter. This disassociates all the tax properties from a product.
331+
To remove tax properties from a product, send a request to the [Delete product tax properties](/docs/rest-management/tax-properties/product-tax-properties#delete-product-tax-properties) endpoint and use the `product_id:in` query parameter. This disassociates all the tax properties from a product.
323332

324333

325334
<Tabs items={[`Request`, `Response`]}>
@@ -338,9 +347,13 @@ To remove tax properties from a product, send a request to the [Delete product t
338347
</Tab>
339348
</Tabs>
340349

350+
## Customer tax properties
351+
352+
See the [Tax Customers API](/docs/store-operations/tax/tax-customers) to attach tax properties to a customer.
353+
341354
## Tax Quotes
342355

343-
BigCommerce sends product tax properties to request [tax estimates](/docs/rest-contracts/tax#estimate-taxes) from a provider. The requests include tax properties for each item in a consignment.
356+
BigCommerce sends product and customer tax properties to request [tax estimates](/docs/rest-contracts/tax#estimate-taxes) from a provider. The requests include tax properties for each item in a consignment.
344357

345358
The following request uses the Tax Provider API:
346359

@@ -351,6 +364,21 @@ Content-Type: application/json
351364
Accept: application/json
352365
353366
{
367+
"customer": {
368+
"customer_id": "12345",
369+
"customer_group_id": "1",
370+
"taxability_code": "",
371+
"tax_properties": [
372+
{
373+
"code": "tax-exemption-status",
374+
"value": "exempt"
375+
},
376+
{
377+
"code": "erp-external-id",
378+
"value": "CUST-001"
379+
}
380+
]
381+
},
354382
...
355383
"items": [
356384
{
@@ -382,9 +410,9 @@ Accept: application/json
382410
...
383411
}
384412
```
385-
BigCommerce also sends product tax properties to [commit](/docs/rest-contracts/tax#commit-tax-quote) and [adjust tax quotes](/docs/rest-contracts/tax#adjust-tax-quote).
413+
BigCommerce also sends product tax properties to [commit](/docs/rest-contracts/tax#commit-tax-quote) and [adjust tax quotes](/docs/rest-contracts/tax#adjust-tax-quote).
386414

387-
## Resources
415+
## Resources
388416
- [Tax Properties API Reference](/docs/rest-management/tax-properties)
389417
- [Tax Provider API Reference](/docs/rest-contracts/tax)
390418

0 commit comments

Comments
 (0)