Step By Step - Creating VAT / Global Tax Transaction

In addition of supporting United State's sales tax, we also support VAT / Global Tax. Those taxes may apply to international transactions.

In this guide we show case an example of a transaction that is being shipped to Canada.

Create Transaction

Request

To create a vat / gt applied transaction, take the customerId from the customer you created, and place it in this payload payload:

curl -X 'PUT' \
  'https://demo.complyt.io/v1/transactions/source/9/externalId/some-external-id' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer eyJhbGciOiJSUzI1NiIs....' \
  -H 'Content-Type: */*' \
  -d '{
    "complytId": null,
    "externalId": "some-external-id",
    "source": "9",
    "documentName": "some-document-name",
    "items": [
        {
            "unitPrice": 60000,
            "quantity": 2,
            "totalPrice": 120000,
            "description": "some description",
            "name": "some-name",
            "taxCode": "C1S1"
        }
    ],
    "billingAddress": null,
    "shippingAddress": {
        "country":"Canada",
        "region": "Quebec"
    },
    "customerId": {{customerComplytId}},
    "transactionStatus": "ACTIVE",
    "externalTimestamps": {
        "createdDate": "2024-05-27T09:47:57.625803",
        "updatedDate": "2024-05-27T09:47:57.625809"
    },
    "transactionType": "INVOICE",
   "shippingFee": {
        "manualSalesTax":false,
        "manualSalesTaxRate":0,
        "taxCode":"C6S1",
        "totalPrice":"100"
    },
    "transactionLevelDiscount": 0,
    "transactionFilingStatus": "NOT_FILED",
    "currency":"cad", //not mandatory
    "isTaxInclusive":false
}'

Required Fields

Field Name	Data Type	Required	Description	Example
externalId	String	Yes	The ID of the transaction in your system.	"ABC-123"
source	Integer	Yes	Distinguishes between multiple systems. Select the relevant source number from the provided list.	1
unitPrice	Decimal	Yes	The price per unit of the item.	19.99
quantity	Integer	Yes	The number of units purchased.	2
totalPrice	Decimal	Yes	The total price of the transaction before taxes.	39.98
transactionLevelDiscount	Decimal	No	The discount to apply on the overall transaction.	10
taxCode	String	Yes	Represents the category of the item to determine the tax rate.	"GST"
customerId	String	Yes	The ID of the customer who made the purchase.	"CUST-456"
createdDate	Date	Yes	The date the transaction was created in your system.	2024-06-25
shippingAddress	String	Yes	The shipping address of the customer.	"123 Main St"
country	String	Yes	The country of the customer (excluding USA).	"Canada"
region	String	No	The region or state of the customer.	"Ontario"
updatedDate	Date	Yes	The date the transaction was last updated in your system.	2024-06-25
createdFrom	String	No	Reference to a previous transaction for credit memos, refunds, or sales orders.	"REF-789"
transactionStatus	String	Yes	The current status of the transaction (ACTIVE or CANCELLED). Use the DELETE endpoint for cancelled transactions.	"ACTIVE"

Response

A successful request will result in a 200/201 HTTP response in the following format:

    "complytId": "{{transactionComplytId}}",
    "externalId": "some-external-id",
    "source": "9",
    "documentName": "some-document-name",
    "items": [
        {
            "unitPrice": 60000,
            "quantity": 2,
            "totalPrice": 120000,
            "calculatedTotal": 120000,
            "description": "some description",
            "name": "some-name",
            "taxCode": "C3S1",
            "jurisdictionalSalesTaxRules": {
                "name": "Canada",
                "abbreviation": "CA",
                "taxable": true,
                "specialTreatment": false,
                "calculationType": "FIXED",
                "description": "description3",
                "calculationValue": 0,
                "cities": null,
                "regions": {
                    "Quebec": {
                        "name": "Quebec",
                        "abbreviation": "Quebec",
                        "taxable": true,
                        "specialTreatment": false,
                        "calculationType": "FIXED",
                        "description": "description3",
                        "calculationValue": 0
                    },
                    "British Columbia": {
                        "name": "British Columbia",
                        "abbreviation": "British Columbia",
                        "taxable": true,
                        "specialTreatment": false,
                        "calculationType": "FIXED",
                        "description": "description3",
                        "calculationValue": 0
                    }
                }
            },
            "salesTaxRates": null,
            "gtRates": {
                "countryRate": 0.05,
                "regionRate": 0.0975,
                "taxRate": 0.1475
            },
            "manualSalesTax": false,
            "manualSalesTaxRate": 0,
            "discount": null,
            "tangibleCategory": "TANGIBLE",
            "taxableCategory": "TAXABLE"
        }
    ],
    "isTaxInclusive": false,
    "billingAddress": null,
    "shippingAddress": {
        "city": null,
        "country": "Canada",
        "county": null,
        "state": null,
        "street": null,
        "region": "Quebec",
        "zip": null,
        "isPartial": false
    },
    "customerId": "{{customerComplytId}}",
    "customer": {
        "complytId": "{{customerComplytId}}",
        "externalId": "{{customerExternalId}}",
        "source": "9",
        "name": "Customer Name",
        "address": {
            "city": "fresno",
            "country": "US",
            "county": null,
            "state": "CA",
            "street": "7498 N Remington Ave",
            "region": null,
            "zip": "93711-5508",
            "isPartial": false
        },
        "email": null,
        "customerType": "RETAIL",
        "internalTimestamps": {
            "createdDate": "2022-01-01T00:00",
            "updatedDate": "2024-03-17T14:33:16.725"
        },
        "externalTimestamps": {
            "createdDate": "2023-06-14T07:58:02.410",
            "updatedDate": "2023-06-14T07:58:02.410"
        },
        "comment": null
    },
    "salesTax": {
        "amount": 17714.7500,
        "rate": 0.14975,
        "salesTaxRates": null,
        "gtRates": {
            "countryRate": 0.05,
            "regionRate": 0.0975,
            "taxRate": 0.14975
        }
    },
    "transactionStatus": "ACTIVE",
    "internalTimestamps": {
        "createdDate": "2024-06-20T14:12:06.794024",
        "updatedDate": "2024-06-20T14:12:06.794024"
    },
    "externalTimestamps": {
        "createdDate": "2024-05-27T09:47:57.625803",
        "updatedDate": "2024-05-27T09:47:57.625809"
    },
    "transactionType": "INVOICE",
    "shippingFee": {
        "manualSalesTax": false,
        "manualSalesTaxRate": 0,
        "totalPrice": 100,
        "calculatedTotal": 100,
        "jurisdictionalSalesTaxRules": {
            "name": "Canada",
            "abbreviation": "CA",
            "taxable": true,
            "specialTreatment": false,
            "calculationType": "FIXED",
            "description": "description3",
            "calculationValue": 0,
            "cities": null,
            "regions": {
                "Quebec": {
                    "name": "Quebec",
                    "abbreviation": "Quebec",
                    "taxable": true,
                    "specialTreatment": false,
                    "calculationType": "FIXED",
                    "description": "description3",
                    "calculationValue": 0
                },
                "British Columbia": {
                    "name": "British Columbia",
                    "abbreviation": "British Columbia",
                    "taxable": true,
                    "specialTreatment": false,
                    "calculationType": "FIXED",
                    "description": "description3",
                    "calculationValue": 0
                }
            }
        },
        "salesTaxRates": null,
        "gtRates": {
            "countryRate": 0.05,
            "regionRate": 0.0975,
            "taxRate": 0.1475
        },
        "taxCode": "C6S1",
        "taxableCategory": "TAXABLE",
        "tangibleCategory": "INTANGIBLE"
    },
    "createdFrom": null,
    "taxableItemsAmount": 120100,
    "tangibleItemsAmount": 120000,
    "totalItemsAmount": 120100,
    "totalDiscount": 0,
    "transactionLevelDiscount": 0,
    "finalTransactionAmount": 120100,
    "transactionFilingStatus": "NOT_FILED",
    "currency": "cad",
    "subsidiary": null
}

:::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. In this case, this is the final rate that was calculated for a transcation that is being shipped to Quebec, Canada. you can find the rate in salesTax.rate. You can also see the different percentages that accumulate to the final rate in salesTax.gtRates.
:::

Last modified: 5 months ago