Skip to content
API | Direct Integration Guides
Share
Explore
API | Direct Integration Guides

icon picker
Partial Address Flow - State/Zip Only

Calculating tax with partial address details

error

Do not use this flow without approving with Complyt’s integration team.

Using this flow might remove rate calculation guarantees.
The use of partial address details can negatively impact the accuracy of sales tax rates. In order to ensure that sales tax is calculated correctly, it is important to have complete address information. This includes the street address, city, state, and zip code. When any of these details are missing or incomplete, it becomes difficult to accurately determine the correct sales tax rate. As a result, it is important to make sure that all necessary address details are included in order to avoid any potential errors in the calculation of sales tax.
We only allow this flow for selected partners that considered the risks and implications, approved contractually.

Create Transaction

Request

To create a transaction, take the customerId from the customer you created in the previous request and place it in the ​(We are working on a single request that creates a transactions and a customer, once it’s available all clients will be updated)
To use the partial address flow, you need to add a flag to the address object ,isPartial: true , toghther the state name/abbreviation and ZIP code. Below you can see a comparison of a partial address transaction and a full address (regular) transaction:
curl -X 'PUT' \ 'https://demo.complyt.io/v1/transactions/source/1/externalId/465813' \ -H 'accept: application/json' \ -H 'Authorization: Bearer eyJhbGciOiJSUzI1NiIs....' \ -H 'Content-Type: _/_' \ -d '{
"externalId": "465813",
"source": "1",
"items": [
{
"unitPrice": 0,
"quantity": 0,
"totalPrice": 0,
"description": "string",
"name": "string",
"taxCode": "C1S1",
"manualSalesTax": true,
"manualSalesTaxRate": 0
}
],
"billingAddress": { // Optional
"city": "",
"country": "US",
"county": null,
"state": "CA",
"street": "3098 N Remington Ave",
"zip": "93711-5508"
},
// Requires only ZIP/State values while "isPartial" is true.
"shippingAddress":
"isPartial": true,
"country": "US",
"county": null
"state": "CA",
"street": null
"zip": "93711-5508"
},
"customerId": "dbb5c569-c6b4-4fea-b9ac-1d4f3770f94a", // Generated from the PUT Customer request
"externalTimestamps": {
"createdDate": "2023-02-05T12:24:43.193Z",
"updatedDate": "2023-02-05T12:24:43.193Z"
},
"transactionStatus": "ACTIVE",
"transactionType": "INVOICE",
"createdFrom": "string"
}

Required Fields

externalId - This is the ID of the transaction in your system.
source (integer) - Used to distinguish between multiple systems. Go
to select relevant source number.
unitPrice
quantity
totalPrice
tax_code - This is a tax code that represents the category of the item. This is used to determine the tax rate.
customerId -
createdDate - the date the transaction was created in your system.
updatedDate - the date the transaction was last updated in your system.
createdFrom - This is a reference to previous transaction. This is used to credit memos, refunds & sales orders
transactionStatus - can receive 3
ACTIVE
CANCELLED

Response

receipt
Sales Tax Amount - the bottom line of our calculation, this is what you usually want to add to your invoice 🎯 After adding a transaction to Complyt’s API, you can retrieve the calculated Sales Tax Amount at salesTax.amount
A successful request will result in a 200/201 HTTP response in the following format:
{
"complytId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"externalId": "999444",
"source": "1",
"items": [
{
"unitPrice": 0,
"quantity": 0,
"totalPrice": 0,
"description": "string",
"name": "string",
"taxCode": "string",
"jurisdictionalSalesTaxRules": {
"name": "string",
"abbreviation": "string",
"taxable": true,
"specialTreatment": true,
"calculationType": "FIXED",
"description": "string",
"calculationValue": 0
},
"salesTaxRate": {
"cityDistrictRate": 0,
"cityRate": 0,
"countyDistrictRate": 0,
"countyRate": 0,
"stateRate": 0,
"taxRate": 0
},
"manualSalesTax": true,
"manualSalesTaxRate": 0,
"tangibleCategory": "TANGIBLE",
"taxableCategory": "TAXABLE"
}
],
"billingAddress": {
"city": "string",
"country": "string",
"county": "string",
"state": "string",
"street": "string",
"zip": "string"
},
"shippingAddress": {
"isPartial": true,
"city": "string",
"country": "string",
"county": "string",
"state": "string",
"street": "string",
"zip": "string"
},
"customerId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"customer": {
"complytId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"externalId": "string",
"source": "7",
"name": "string",
"address": {
"city": "string",
"country": "string",
"county": "string",
"state": "string",
"street": "string",
"zip": "string"
},
"salesTax": {
"amount": 100 //the bottom line of our calculation, this is what you usually want to add to your invoice 🎯
"salesTaxRate": {
"cityDistrictRate": 0,
"cityRate": 0,
"countyDistrictRate": 0,
"countyRate": 0,
"stateRate": 0,
"taxRate": 0
}
},
"transactionStatus": "ACTIVE",
"internalTimestamps": {
"createdDate": {
"timestamp": "2023-02-05T12:24:43.193Z"
},
"updatedDate": {
"timestamp": "2023-02-05T12:24:43.193Z"
}
},
"externalTimestamps": {
"createdDate": {
"timestamp": "2023-02-05T12:24:43.193Z"
},
"updatedDate": {
"timestamp": "2023-02-05T12:24:43.193Z"
}
},
"transactionType": "SALES_ORDER",
"shippingFee": {
"manualSalesTax": true,
"manualSalesTaxRate": 0,
"totalPrice": 0,
"taxCode": "string",
"taxableCategory": "TAXABLE",
"tangibleCategory": "TANGIBLE",
"jurisdictionalSalesTaxRules": {
"name": "string",
"abbreviation": "string",
"taxable": true,
"specialTreatment": true,
"calculationType": "FIXED",
"description": "string",
"calculationValue": 0
},
"salesTaxRate": {
"cityDistrictRate": 0,
"cityRate": 0,
"countyDistrictRate": 0,
"countyRate": 0,
"stateRate": 0,
"taxRate": 0
}
},
"createdFrom": "string",
"taxableItemsAmount": 0,
"tangibleItemsAmount": 0,
"totalItemsAmount": 0
}

Get Rates

Request

You can obtain the rates for a given address by using the GET sales tax rate service. This will not create a transaction object or have any affects on nexus tracking or other compliance affects.
To use the partial address flow, you need to pass a flag as a query parameter ,isPartial=true , together the state name/abbreviation and ZIP code. Below you can see a comparison of a partial address transaction and a full address (regular) transaction:
curl -X 'GET' \
'https://demo.complyt.io/v1/sales_tax_rates?isPartial=true&country=US&state=NY&zip=10011' \
-H 'accept: application/json' \
-H 'Authorization: Bearer eyJhbGciOiJSUzI1NiIs....'

Required Query Parameters

isPartial=true
country=US
state=stateNameHere
zip=zipCodeHere

Response

receipt
Sales Tax Rate (Total)- the bottom line of our calculation, this is what you usually want to learn about the address 🎯 You can retrieve the Calculated Sales Tax Rate at salesTaxRates.taxRate
A successful request will result in a 200/201 HTTP response in the following format:
{
"address": {
"country": "US",
"state": "NY",
"zip": "10038",
"isPartial": true
},
"salesTaxRates": {
"cityDistrictRate": 0,
"cityRate": 0.045,
"countyDistrictRate": 0.00375,
"countyRate": 0,
"stateRate": 0.04,
"taxRate": 0.08875 // This is is the rate you are probably looking for - this is the combined rate, derived from the breakdown by jusrtiction rates (city, county, state etc.)
}
}

Want to print your doc?
This is not the way.
Try clicking the ⋯ next to your doc name or using a keyboard shortcut (
CtrlP
) instead.