API Docs
API Docs
  1. Getting Started
  • Getting Started
    • Introduction to Sales Tax Calculation
    • Step By Step - Creating your first transaction
    • Step By Step - Creating VAT / Global Tax Transaction
  • Endpoints
    • Authentication
      • Authentication - Getting Started
      • Create JWT
    • Customers
      • Get to Know
      • Get Customer
      • Get All Customers
      • Upsert Customer
      • Update Customer
    • Exemptions
      • Get to Know
      • Get All Exemptions
      • Post Exemption
      • Update Exemption
      • Patch Exemption
    • Transactions
      • Get to Know
      • The Importance of Shipping Address
      • How to Use Credit Memos
      • Get Transaction (thin)
      • Get Transaction
      • Upsert Transaction
      • Delete Transaction
      • Get All Transactions (thin)
      • Get All Transactions
      • Upsert VAT / GT Transactio
    • Address Validation
      • Address Validation Intro
      • Validate Address
    • Sales Tax Rates
      • Get Sales Tax Rates
    • Vat Validation
      • Validate Vat
  • Special Features
    • Global Tax Rate
    • Partial Address
    • Discounts
    • Inclusive Tax
    • Vat Validation
    • Post exemptions from CSV
      POST
  1. Getting Started

Step By Step - Creating your first transaction

This guide walks you through the basic steps to authenticate and use Complyt API to create a customer and a 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.
Full Sequence Diagram
Full Flow Chart

Authenticate#

Request#

Use Complyt API to obtain an Auth0 bearer token. To do this, you’ll need to send a POST request to the Complyt token endpoint, passing your client ID and client secret in the request body. Here’s an example cURL command to do this:
curl --request POST \
  --url 'https://demo.complyt.io/v1/token' \
  --header 'content-type: application/json' \
  --data '{
    "clientId": "A414......................GsFf87t",
    "clientSecret": "HHCv..............gQ491nSVed35"
}'
Replace the placeholders with your actual client ID and client secret.

Response#

If the request is successful, you’ll receive a JSON response that includes an access token. The access token is your bearer token, which you can use to authenticate requests to your M2M application’s API. Here’s an example response:
{
   "accessToken":"eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
   "tokenType":"Bearer",
   "expiresIn":86400
}
CHECK
That’s it! You can now use the access token as a bearer token to authenticate requests to your M2M application’s API. Please note that the token expires in 24 hours, so either re-generate it with every request or re-generate it daily.

Create Customer#

Request#

Use the access token obtained from the previous step to make the following request to create a customer in Complyt:
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"
  }
}'
This API request uses the HTTP PUT method to create a new customer in the Complyt system. The request includes the customer details in the JSON payload of the request body. The -H 'Authorization: Bearer ...' header includes the access token obtained from the previous step, which is used to authenticate the request to the Complyt API.
Required Fields
FieldDescription
externalIdThe ID of the customer in your system. Note that it needs to be filled in the URL & in the body.
sourceUsed to distinguish between multiple systems. Needs to be filled in the URL & in the body.
nameCustomer's name.
countryCustomer's country.
stateCustomer's state. Can be an abbreviated state name - CA, or full - California.
streetCustomer's street address.
zipCustomer's ZIP code.
createdDateThe 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)
updatedDateThe 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
That’s it! You can now use the complytId from the returned customer object when creating a transaction.

Create Transaction#

Request#

To create a transaction, take the 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" 
}'
Required Fields
FieldDescription
externalIdThe ID of the transaction in your system.
sourceUsed to distinguish between multiple systems.
unitPriceUnit price of the item.
quantityQuantity of the item.
totalPriceTotal price of the item.
taxCodeTax code that represents the category of the item. This is used to determine the tax rate.
customerIdThe complytId of the customer from the previous request.
createdDateThe date the transaction was created in your system.
shippingAddress.countryThe shipping country of the customer. Can either be USA, or other VAT country.
shippingAddress.stateMandatory if USA, optional otherwise. Can be an abbreviated state name - CA, or full - California.
shippingAddress.streetShipping street address.
shippingAddress.zipShipping ZIP code.
updatedDateThe date the transaction was last updated in your system.
createdFromA reference to a previous transaction. This is used for credit memos, refunds & sales orders.
transactionStatusTransaction status (ACTIVE, CANCELLED). Use DELETE endpoint for CANCELLED status.

Response#

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",
      "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
}
Global Tax Applied Transaction
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.
Tax Rate - the rate that was applied to the transaction. This rate is either sales tax rate or global tax / vat. in both cases this rate can be found at 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#

In some cases, you would like to show your customer an estimation of the transaction’s price, including the tax amounts, without creating an invoice.

Recommended Estimation Flow#

1.
Create a transaction of the ‘ESTIMATE’ type by passing "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.
Create a transaction of the ‘INVOICE’ type by passing "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.
Previous
Introduction to Sales Tax Calculation
Next
Step By Step - Creating VAT / Global Tax Transaction
Built with