Step By Step - Creating your first transaction
Authenticate
Obtain a token by sending a POST request with your client ID and client secret.
Create Customer
Use the token to send a PUT request with the customer details, creating a new customer in the system.
Create Transaction
Use the customer ID returned from the previous step to create a transaction (invoice) with a PUT request.
Authenticate
Request
curl --request POST \
--url 'https://demo.complyt.io/v1/token' \
--header 'content-type: application/json' \
--data '{
"clientId": "A414......................GsFf87t",
"clientSecret": "HHCv..............gQ491nSVed35"
}'
Response
{
"accessToken":"eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
"tokenType":"Bearer",
"expiresIn":86400
}
CHECK
Create Customer
Request
curl -X 'PUT' \
'https://demo.complyt.io/v1/customers/source/1/externalId/999444' \
-H 'accept: application/json' \
-H 'Authorization: Bearer eyJhbGc...iOiJSUzI1NiIsInR5cCI6IkpXVCJ9...' \
-H 'Content-Type: */*' \
-d '{
"externalId": 999444,
"source": 1,
"name": "Complyt",
"address": {
"city": "Sacramento",
"country": "US",
"county": null,
"state": "CA",
"street": "944 W. Wintergreen St.",
"zip": "95823"
},
"customerType": "RETAIL",
"externalTimestamps": {
"createdDate": "2022-10-19T07:00:00.000Z",
"updatedDate": "2022-10-19T09:07:54.585Z"
}
}'
-H 'Authorization: Bearer ...'
header includes the access token obtained from the previous step, which is used to authenticate the request to the Complyt API.Field | Description |
---|---|
externalId | The ID of the customer in your system. Note that it needs to be filled in the URL & in the body. |
source | Used to distinguish between multiple systems. Needs to be filled in the URL & in the body. |
name | Customer's name. |
country | Customer's country. |
state | Customer's state. Can be an abbreviated state name - CA, or full - California. |
street | Customer's street address. |
zip | Customer's ZIP code. |
createdDate | The date the customer was created in your system. Supported formats: yyyy-MM-dd, yyyy-MM-ddThh:mm:ssZ, or yyyy-MM-ddThh:mm:ss±hh:mm (with a valid time zone offset) |
updatedDate | The date the customer was last updated in your system. Same format as createdDate . |
Response
{
"complytId": "dbb5c569-c6b4-4fea-b9ac-1d4f3770f94a",
"externalId": "999444",
"source": "1",
"name": "Complyt",
"address": {
"city": "Sacramento",
"country": "US",
"county": null,
"state": "CA",
"street": "944 W. Wintergreen St.",
"zip": "95823"
},
"customerType": "RETAIL",
"internalTimestamps": {
"createdDate": {
"timestamp": "2023-02-23T00:53:14.386714464"
},
"updatedDate": {
"timestamp": "2023-02-23T00:53:14.386714464"
}
},
"externalTimestamps": {
"createdDate": {
"timestamp": "2022-10-19T07:00:00"
},
"updatedDate": {
"timestamp": "2022-10-19T09:07:54.585"
}
}
}
CHECK
complytId
from the returned customer object when creating a transaction.Create Transaction
Request
customerId
from the customer you created in the previous request and place it in the payload: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": false,
"manualSalesTaxRate": 0
}
],
"billingAddress": {
"city": "",
"country": "US",
"county": null,
"state": "CA",
"street": "3098 N Remington Ave",
"zip": "93711-5508"
},
"shippingAddress": {
"city": "fresno",
"country": "US",
"county": null,
"state": "CA",
"street": "3098 N Remington Ave",
"zip": "93711-5508"
},
"customerId": "dbb5c569-c6b4-4fea-b9ac-1d4f3770f94a",
"externalTimestamps": {
"createdDate": "2023-02-05T12:24:43.193Z",
"updatedDate": "2023-02-05T12:24:43.193Z"
},
"transactionStatus": "ACTIVE",
"transactionType": "INVOICE",
"transactionLevelDiscount": 0,
"createdFrom": "string"
}'
Field | Description |
---|---|
externalId | The ID of the transaction in your system. |
source | Used to distinguish between multiple systems. |
unitPrice | Unit price of the item. |
quantity | Quantity of the item. |
totalPrice | Total price of the item. |
taxCode | Tax code that represents the category of the item. This is used to determine the tax rate. |
customerId | The complytId of the customer from the previous request. |
createdDate | The date the transaction was created in your system. |
shippingAddress.country | The shipping country of the customer. Can either be USA, or other VAT country. |
shippingAddress.state | Mandatory if USA, optional otherwise. Can be an abbreviated state name - CA, or full - California. |
shippingAddress.street | Shipping street address. |
shippingAddress.zip | Shipping ZIP code. |
updatedDate | The date the transaction was last updated in your system. |
createdFrom | A reference to a previous transaction. This is used for credit memos, refunds & sales orders. |
transactionStatus | Transaction status (ACTIVE, CANCELLED). Use DELETE endpoint for CANCELLED status. |
Response
{
"complytId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"externalId": "999444",
"source": "1",
"items": [
{
"unitPrice": 0,
"quantity": 0,
"totalPrice": 0,
"description": "string",
"name": "string",
"discount": 0,
"relativeTransactionDiscount": 0,
"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": {
"city": "string",
"country": "string",
"county": "string",
"state": "string",
"street": "string",
"zip": "string",
"region": "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,
"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,
"totalDiscount": 0,
"transactionLevelDiscount": 0,
"totalItemsAmount": 0
}
salesTax.amount
.
salesTax.rate
. inside salesTax
, you will be able to find salesTax.salesTaxRates
or salesTax.gtRates
if one of them applies (but not both).
Estimate/Quote Flow
Recommended Estimation Flow
1.
"transactionType": "ESTIMATE"
in the payload. This transaction will return all the relevant details but will not be counted against the nexus thresholds or added to the tax returns.2.
"transactionType": "INVOICE"
in the payload. The rest of the transaction payload can be identical. This transaction will be counted against the relevant state nexus thresholds and will be a part of the tax returns.Modified at 2025-03-24 15:00:03