| Field Name | Type | Value Required | Optional | Character Limits | Validations | Description | | --- | --- | --- | --- | --- | --- | | client_id | string | Required | 50 | Set value as provided | Provided in your HOST portal | | connection_source | string | Required | 50 | | Stripe, shopify, quickbooks, or free form. Implications are detailed below | | invoice_id | string | Required | 50 | | | | trans_id | string | Required | 50 | | See below discussion. | | customer_id | string | Required | 50 | | No filings implications. You can set it equal to the trans_id if needed. | | customer_exemption | string | Optional | 4 | See discussion | Blank or 'G' for resale is usually sufficient. Full options are detailed below | | trans_date | string | Required | 10 | YYYY-MM-DD | When the transaction occurred. | | trans_type | string | Required | 6 | refund or sale | | | line_no | int | Required | 3 | | Increments for each line in a given trans_id. More discussion below. | | taxability_code | string | Optional | 50 | See discussion | Detailed below, values are contingent on connection_source. | | source_total_tax | decimal | Required | 20, 2 decimals | | Pre-conversion line item tax value. | | source_amount | decimal | Required | 20, 2 decimals | | Pre-conversion line item amount value. | | account_id | string | Required | 50 | | Specific connection_source details like Shopify store name or Stripe account id. | | marketplace | boolean | Required | 5 | | Whether a sale occurred on a marketplace that already handled the sales tax. | | dest_address_line1 | string | Optional | 50 | | The street address of where the order was shipped to. If the order was placed at a physical in-store location, enter the street address of the physical in-store location. | | dest_address_line2 | string | Optional | 50 | | | | dest_city | string | Optional | 50 | | The city where the order was shipped to. If the order was placed at a physical in-store location, enter the city of the physical in-store location. | | provider | string | Optional | 50 | | Can default to account_id, but in cases where there are multiple data sources feeding into your connection, this can enhance accuracy. It does not have an implication on sales tax filings. | | dest_region | string | Required | 2 | | The two-character state code where the order was shipped to. If the order was placed at a physical in-store location, enter the two-character state code of the physical in-store location.

Official state abbreviations can be found here https://www.ssa.gov/international/coc-docs/states.html | | dest_postalcode | string | Required | 10 | ##### or #####-#### for US | The US zip code in 5 digit or 5 digit-4 digit (#####-####) format where the order was shipped to. If the order was placed at a physical in-store location, enter the US zip code in 5 digit or 5 digit-4 digit (#####-####) format of the physical in-store location. | | dest_country | string | Required | 2 | | The two-character country code where the order was shipped to. If the order was placed at a physical in-store location, enter the two-character country code of the physical in-store location. US = United States; CA = Canada | | orig_address_line1 | string | Optional | 50 | | The street address of where the order was shipped from. If the order was placed at a physical in-store location, enter the street address of the physical in-store location. | | orig_city | string | Optional | 50 | | The city where the order was shipped from. If the order was placed at a physical in-store location, enter the city of the physical in-store location. | | orig_region | string | Required | 2 | | The two-character state code where the order was shipped from. If the order was placed at a physical location, enter the two-character state code of the physical in-store location.

client_id

This field is essential in ensuring the transactions are mapped to the correct organization. The client id can be found in the Developer Access sidebar menu → scroll down to the API Key section and locate the client_id column.

Client Id.mp4

↑ Return to top

connection_source

With the exception of ‘shopify’ and ‘stripe’, this field has no implications and can be used for organizational purposes in your data. However, if this is Shopify or Stripe data, you must leave the taxability_code values in Shopify or Stripe format, as our sync processes will update those behind the scenes. Note that if the data is from Shopify or Stripe and you want to provide the taxability codes, you can “game” this requirement by using ‘shopfiy custom’ or something like that.

↑ Return to top

trans_id

For your data to sync accurately, a trans_id and line_no combination must be unique, throughout time. For example, let’s say I generate invoice #5689 in January 2026. The invoice has 1 line item, and I post the data correspondingly. In March of 2026, the same customer wants to add to return the item. If I post the data with trans_id of #5689 and line_no of 1, the return will not process. To ensure the trans_ids remain unique throughout time, either be sure to use a unique id from your source system or append a unique value like the action date or when you are posting the data. I.e. #5689-012026 and #5689-032026.

↑ Return to top

customer_exemption

The only acceptable values are ‘A’,’B’,’C’,’D’,’E’,’F’,’G’,’H’,’I’,’J’,’K’,’L’,’N’,’MED1’,’MED2’

Those values correspond to the following exemption reasons. G → Resale is by far the most common.

A=Federal government B=State government C=Tribe/Status Indian/Indian Band D=Foreign diplomat E=Charitable or benevolent organization F=Religious or educational organization G=Resale H=Commercial agricultural production I=Industrial production or manufacturer J=Direct pay permit K=Direct mail L=Other N=Local government MED1=US MDET with exempt sales tax MED2=US MDET with taxable sales tax

↑ Return to top

line_no

This value must be unique for each line within a given trans_id. You can start at 1 and increment by 1 unit when posting if your source system does not provide this value.

↑ Return to top

taxability_code

If connection_source = ‘shopify’, this field should be the Shopify-provided taxability codes: gid://shopify/TaxonomyCategory/vp-2-3-3. URL: https://shopify.github.io/product-taxonomy/releases/2025-12/

If connection_source = ‘stripe’, this field should be the Stripe-provided taxability codes: https://docs.stripe.com/tax/tax-codes.

If connection_source is something else, the taxability_codes should be one of https://taxcode.avatax.avalara.com/. You can pass other values, but they will be defaulted.

↑ Return to top

location_code

Use ‘MKPL’ if the data you are providing is a marketplace sale. Otherwise, you will double pay on the tax. Remember to also mark "marketplace": true in all relevant lines.

In most other instances, you can use ‘DEFAULT’ as the code. However, the goal is to report as accurately as possible. So, review the locations we have assigned to you (video explanation below), let us know if any need to be added, and use the selected location to inform all your origin address fields. There are states like California or Colorado in which this is essential to report accurately, or your return and amount owed will change.

location codes.mp4

↑ Return to top

Tax and Amount Fields

There are several fields worth reviewing: source_total_tax, source_amount, source_total_tax_currency, source_amount_currency, filing_amount, filing_currency, filing_amount_exchange_rate, filing_tax_exchange_rate.

To oversimplify, filing_amount and filing_tax_amount are the only fields that actually matter and influence your returns. Those are the fields that define the revenue and tax amounts reported. In case of currency conversions, ensure they have been converted to the filing_currency (USD when dest_country = US and CAD when dest_country = CA).

The source_* fields help tell and record the currency conversion story. For example, let’s say you had a transaction with an amount of $100 GBP, but the order shipped to California in the US. You have to get the amount to USD. You could just put $110 (example conversion) in the filing_amount field and move on, or you can preserve the logic applied. If you choose the latter, the source fields are at your disposal, think: My source_amount (of $100) was in source_amount_currency (GBP). It needed to be in filing_currency (USD), so I used filing_amount_exchange_rate (1.1 for example) to arrive at filing_amount ($110 USD). The same logic can be applied to the tax fields.

↑ Return to top

Trans_type and Matching Signs

To ensure proper data handling, make sure the following are true:

If trans_type = refund, then filing_tax_amount and filing_amount must both be negative or 0.

If trans_type = sale, then filing_tax_amount and filing_amount must both be positive or 0.

The signs for filing_amount and filing_tax_amount must always match and connect with trans_type for all lines.

↑ Return to top

Authentication

Utilize bearer token authentication in your calls.