DEVDOCS-5714: Tax Zone API, add tax zone check endpoint

docs/api-docs/tax/tax-rates-zones.mdx

@@ -266,6 +266,56 @@ To delete tax zones, send a request to the [Delete tax zones](/docs/rest-managem
  </Tab>
 </Tabs>
 
+### Check tax zone
+
+You can find the tax zone that applies to a given region and customer group by sending a request to [Check tax zone](/docs/rest-management/tax-rates-and-zones/tax-zone-check#check-tax-zone).
+
+The following example request returns the tax zone that applies to a shopper in the US, not all tax zones that have the given the country code. Responses include only one tax zone.
+
+<Tabs items={[`Request`, `Response`]}>
+ <Tab>
+ ```http filename="Example request: Check tax zone" showLineNumbers copy
+ POST https://api.bigcommerce.com/stores/{{STORE_HASH}}/v3/tax/zonecheck
+ X-Auth-Token: {{ACCESS_TOKEN}}
+ Content-Type: application/json
+ Accept: application/json
+
+ {
+ "country_code": "US"
+ }
+ ```
+ </Tab>
+ <Tab>
+ ```http filename="Example response: Check tax zone" showLineNumbers copy
+ {
+ "data": {
+ "id": 3,
+ "name": "United States",
+ "enabled": true,
+ "price_display_settings": {
+ "show_inclusive": true,
+ "show_both_on_detail_view": true,
+ "show_both_on_list_view": true
+ },
+ "shopper_target_settings": {
+ "locations": [
+ {
+ "country_code": "US",
+ "subdivision_codes": [],
+ "postal_codes": []
+ }
+ ],
+ "customer_groups": [
+ 0
+ ]
+ }
+ },
+ "meta": {}
+ }
+ ```
+ </Tab>
+</Tabs>
+
 ## Tax rates
 
 After creating a zone, you can add rates to the zone. You can add multiple rates to a zone to help the store collect and report taxes to one or more taxation authorities. You can add a rate for each tax class in your store.
@@ -454,6 +504,7 @@ To delete tax rates, send a request to the [Delete tax rates](/docs/rest-managem
 - [Update tax zones](/docs/rest-management/tax-rates-and-zones/tax-zones#update-tax-zones)
 - [Get tax zones](/docs/rest-management/tax-rates-and-zones/tax-zones#get-tax-zones)
 - [Delete tax zones](/docs/rest-management/tax-rates-and-zones/tax-zones#delete-tax-zones)
+- [Check tax zone](/docs/rest-management/tax-rates-and-zones/tax-zone-check#check-tax-zone)
 
 ### Tax Rates reference
 - [Create tax rates](/docs/rest-management/tax-rates-and-zones/tax-rates#create-tax-rates)

reference/tax_rates_zones.v3.yml

@@ -18,6 +18,7 @@ servers:
 tags:
  - name: Tax Zones
  - name: Tax Rates
+ - name: Tax Zone Check
 paths:
  '/tax/zones':
  parameters:
@@ -185,6 +186,68 @@ paths:
  responses:
  '204':
  description: No Content
+ '/tax/zonecheck':
+ parameters:
+ - $ref: '#/components/parameters/Accept'
+ post:
+ tags:
+ - Tax Zone Check
+ summary: Check Tax Zone
+ description: Returns the tax zone that applies to a given region and customer group.
+ operationId: zoneCheck
+ parameters:
+ - $ref: '#/components/parameters/Content-Type'
+ requestBody:
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/ZoneCheck'
+ examples:
+ Example 1:
+ value:
+ country_code: AU
+ subdivision_code: NSW
+ customer_group_id: 2
+ required: true
+ responses:
+ "200":
+ description: OK
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ data:
+ $ref: '#/components/schemas/Tax_Zone'
+ meta:
+ $ref: '#/components/schemas/MetaOpen'
+ examples:
+ Example 1:
+ value:
+ data:
+ id: 2
+ name: example zone
+ enabled: false
+ price_display_settings:
+ show_inclusive: false
+ show_both_on_detail_view: false
+ show_both_on_list_view: false
+ shopper_target_settings:
+ locations:
+ - country_code: AR
+ subdivision_codes:
+ - T
+ - V
+ postal_codes: []
+ - country_code: AU
+ subdivision_codes:
+ - NSW
+ - QLD
+ customer_groups:
+ - 2
+ meta: {}
+ "422":
+ description: The request body does not meet specifications.
  '/tax/rates':
  parameters:
 
@@ -470,7 +533,7 @@ components:
  example:
  - NSW
  - QLD
- description: Three-letter ISO 3166-2 subdivision code
+ description: ISO 3166-2 subdivision code, up to three alphanumeric characters.
  items:
  type: string
  postal_codes:
@@ -525,13 +588,13 @@ components:
  country_code:
  type: string
  example: AU
- description: Two-letter ISO 3166-1 country code
+ description: Two-letter ISO 3166-1 country code.
  subdivision_codes:
  type: array
  example:
  - NSW
  - QLD
- description: Three-letter ISO 3166-2 subdivision code
+ description: ISO 3166-2 subdivision code, up to three alphanumeric characters.
  items:
  type: string
  postal_codes:
@@ -589,13 +652,13 @@ components:
  country_code:
  type: string
  example: AU
- description: Two-letter ISO 3166-1 country code
+ description: Two-letter ISO 3166-1 country code.
  subdivision_codes:
  type: array
  example:
  - NSW
  - QLD
- description: Three-letter ISO 3166-2 subdivision code
+ description: ISO 3166-2 subdivision code, up to three alphanumeric characters.
  items:
  type: string
  postal_codes:
@@ -731,6 +794,27 @@ components:
  - class_rates
  - name
  - tax_zone_id
+ ZoneCheck:
+ type: object
+ properties:
+ country_code:
+ type: string
+ description: Two-letter ISO 3166-1 country code.
+ example: 'AU'
+ subdivision_codes:
+ type: string
+ description: ISO 3166-2 subdivision code, up to three alphanumeric characters.
+ example: 'NSW'
+ postal_code:
+ type: string
+ description: Postal code.
+ example: '2099'
+ customer_group_id:
+ type: integer
+ description: Customer Group ID to which the customer is belongs.
+ example: 0
+ required:
+ - country_code
  Meta:
  type: object
  properties:
@@ -842,5 +926,4 @@ components:
  description: Filter by tax zone `id`. Use a comma-separated CSV string of IDs for multiple tax zones. For example, `5` or `12,34,56`.
  required: false
 security:
- - X-Auth-Token: []
-
+ - X-Auth-Token: []