Expand Tax Provider API to include customs information, duties

Author: theromulans

reference/tax_provider.yml

@@ -939,9 +939,21 @@ components:
           default: false
         tax_properties:
           type: array
-          description: Merchants may opt to include additional properties that a tax provider can choose to support, factoring these values into tax calculation.
+          description: Merchants may opt to include additional properties that a tax provider can choose to support, factoring these values into tax calculation. See [Tax Properties API](/docs/rest-management/tax-properties) for more information on configuring tax properties.
           items:
             $ref: '#/components/schemas/request-item-tax-property'
+        customs_information:
+          type: object
+          description: Merchants may opt to include customs information data in the quote request allowing tax providers to supply calculated duties in addition to taxes. See [Customs Information API](/docs/rest-management/shipping/customs-information) for more information on configuring customs information.
+          properties:
+            country_of_origin:
+              type: string
+              description: The country of manufacture, production, or growth represented in ISO 3166-1 alpha-2 format, when available.
+              example: 'AU'
+            hs_code:
+              type: string
+              description: The item's harmonized tariff code for the document's destination country, when available.
+              example: '817355'
       required:
         - id
         - price
@@ -1227,16 +1239,21 @@ components:
     response-item:
       type: object
       description: |-
-        The tax liabilities calculated for a specific item.
+        The tax liabilities, and any duties, calculated for a specific item.
 
-        Note: Tax liabilities should be calculated with **quantity** accounted for.
+        Note: Tax liabilities and duties should be calculated with the item's **quantity** accounted for.
       title: Item
       properties:
         id:
           type: string
           description: A unique identifier for the line item these tax liabilities are calculated for. Must match the corresponding request line item ID.
         price:
           $ref: '#/components/schemas/response-taxprice'
+        duties_summary:
+          type: array
+          description: Breakdown of any duties that applied to this item.
+          items:
+            $ref: '#/components/schemas/Duties'
       required:
         - id
         - price
@@ -1301,6 +1318,19 @@ components:
         - rate
         - amount
       x-internal: false
+    Duties:
+      type: object
+      properties:
+        name:
+          type: string
+          description: The human-readable name of this custom duty. May not be empty.
+        amount:
+          type: number
+          format: double
+          description: The absolute amount that the shopper will be charged for this custom duty.
+      required:
+        - name
+        - amount
     item_type:
       type: string
       description: |-