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.

[Obtain a token](api-8041522) by sending a POST request with your client ID and client secret. Use the token to send a PUT request with the customer details, [creating a new customer](api-7838831) in the system. Use the customer ID returned from the previous step to [create a transaction](api-7838825) (invoice) with a PUT request. ```mermaid sequenceDiagram participant Client participant Complyt API

Note over Client, Complyt API: Step 1: Authenticate
Client->>Complyt API: POST /v1/token<br>Payload: <br>{"clientId": "A414...GsFf87t",<br>"clientSecret": "HHCv...gQ491nSVed35"}
Note right of Client: Sending authentication request
Complyt API-->>Client: 200 OK<br>Response: <br>{"accessToken":"eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",<br>"tokenType":"Bearer",<br>"expiresIn":86400}
Note left of Complyt API: Access token returned

Note over Client, Complyt API: Step 2: Create Customer
Client->>Complyt API: PUT /v1/customers/source/1/externalId/999444<br>Payload: <br>{"externalId": 999444, "name": "Complyt",...}
Note right of Client: Sending request to create a customer
Complyt API-->>Client: 201 Created<br>Response: <br>{"complytId":"dbb5c569-c6b4-4fea-b9ac-1d4f3770f94a",...}
Note left of Complyt API: Customer created

Note over Client, Complyt API: Step 3: Create Transaction (Invoice)
Client->>Complyt API: PUT /v1/transactions/source/1/externalId/465813<br>Payload: <br>{"externalId": 465813, "customerId": "dbb5c569-c6b4-4fea-b9ac-1d4f3770f94a",...}
Note right of Client: Sending request to create a transaction (invoice)
Complyt API-->>Client: 201 Created<br>Response: <br>{"complytId":"3fa85f64-5717-4562-b3fc-2c963f66afa6",...}
Note left of Complyt API: Transaction (invoice) created


```
</Accordion>

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

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
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

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

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
}

{
  "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": {
    "country": "string", //not usa
    "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,
     "gtRates": {
            "countryRate": 0,
            "regionRate": 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
}

:::highlight gray
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.
:::
:::highlight gray
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

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.
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.

Last modified: 2 months ago