API Docs
API Docs
  1. Transactions
  • 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
      • Get Transaction
        GET
      • Upsert Transaction
        PUT
      • Delete Transaction
        DELETE
      • Get All Transactions (thin)
        GET
      • Get All Transactions
        GET
      • Upsert VAT / GT Transactio
        PUT
    • 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
  • Applications
    • Xero - Integration & User Manual
  1. Transactions

Upsert VAT / GT Transactio

PUT
/v1/transactions/source/{source}/externalId/{externalId}
transaction
Update or Insert Transaction by External ID and source

Request

Authorization
Provide your bearer token in the
Authorization
header when making requests to protected resources.
Example:
Authorization: Bearer ********************
Path Params
externalId
string 
required
External ID
Example:
{{transactionExternalId}}
source
string 
required
Transaction Source (should be [1-9])
Example:
{{source}}
Match pattern:
[1-9]
Body Params application/json
A transaction between the API consumer and a customer
complytId
string <uuid>
optional
The unique identifier in Complyt of the transaction
externalId
string 
required
the attribute designed to receive a unique identifier provided by API consumers themselves (e.g. pass your own ID)
>= 1 characters<= 256 characters
source
string 
required
a single digit which identifies your different stores, checkout solutions, marketplaces, etc. defined by the API consumers (to avoid external id duplications)
Match pattern:
^(10|[1-9])$
documentName
string 
optional
The name of the document, as shown in the ERP systems
>= 0 characters<= 50 characters
items
array [object {16}] 
required
unitPrice
number 
optional
The price of one unit, can be positive and negative
quantity
number 
optional
The quantity of the units, must be positive
totalPrice
number 
optional
The total price of the unit prices time the quantity, can be positive and negative, value is before discount and sales tax
calculatedTotal
number 
optional
The calculated price of the items. represents the total price (or amount time quantity if not provided), after discount. calculated on run time
description
string 
optional
name
string 
required
>= 1 characters<= 256 characters
taxCode
string 
required
>= 0 characters<= 256 characters
jurisdictionalSalesTaxRules
object 
optional
Will hold the relevant rules that are applied on the item. country rules if gt / vat, state rules if USA
salesTaxRates
object (SalesTaxRates) 
optional
gtRates
object (GtRates) 
optional
manualSalesTax
boolean 
optional
manualSalesTaxRate
number 
optional
<= 0.2
discount
number 
optional
The discount of the line items, must be positive
relativeTransactionDiscount
number 
optional
The relative transaction level discount to apply on a specific item. calculated on run time
tangibleCategory
enum<string> 
optional
Allowed values:
TANGIBLEINTANGIBLE
taxableCategory
enum<string> 
optional
Allowed values:
TAXABLENOT_TAXABLE
isTaxInclusive
boolean 
optional
Indicates whether tax is included in the total items price (true) or added as a separate charge (false).
billingAddress
object (billingAddress) 
optional
The billing address for the transaction
city
string 
optional
>= 0 characters<= 100 characters
country
string 
optional
>= 0 characters<= 50 characters
county
string 
optional
>= 0 characters<= 100 characters
state
string 
optional
>= 0 characters<= 100 characters
street
string 
optional
>= 0 characters<= 200 characters
region
string 
optional
>= 0 characters<= 20 characters
zip
string 
optional
>= 0 characters<= 20 characters
shippingAddress
object (shippingAddress) 
required
The shipping address for the transaction
city
string 
required
>= 0 characters<= 100 characters
country
string 
required
>= 0 characters<= 50 characters
county
string 
optional
>= 0 characters<= 100 characters
state
string 
required
>= 0 characters<= 100 characters
street
string 
required
>= 0 characters<= 200 characters
region
string 
optional
>= 0 characters<= 20 characters
zip
string 
required
>= 0 characters<= 20 characters
isPartial
boolean 
required
whether country, city or street are necessary
matchedAddressData
object 
optional
Details of the real address in the US based on the request address.
customerId
string <uuid>
required
The Complyt ID of the customer associated with the transaction
customer
object (Customer) 
optional
The buyer. All transactions are associated with a customer
complytId
string <uuid>
optional
The unique identifier in Complyt of the customer
externalId
string 
required
the attribute designed to receive a unique identifier provided by API consumers themselves (e.g. pass your own ID)
>= 1 characters<= 256 characters
source
string 
required
a single digit which identifies your different stores, checkout solutions, marketplaces, etc. defined by the API consumers (to avoid external id duplications)
Match pattern:
^(10|[1-9])$
name
string 
optional
The customer's name
>= 1 characters<= 256 characters
address
object 
optional
email
string 
optional
An (Optional) Email address associated with the customer
customerType
enum<string> 
optional
Indicates whether the customer is 'retail'/'reseller'/'marketplace'. Defaults to 'retail' if no customer type is provided
Allowed values:
RETAILMARKETPLACERESELLERRETAIL_EXEMPT
internalTimestamps
object (internalTimestamps) 
optional
read-only. The APIs internal timestamps for this resource
externalTimestamps
object (externalTimestamps) 
required
External timestamps, which should reference the dates in your originating system since these are the timestamps used for sales tax calculation
comment
string 
optional
>= 0 characters<= 200 characters
salesTax
object 
optional
amount
number 
optional
wheter global tax / vat / sales tax are applied, this field will hold the final amount that is applied on the transaction
rate
number 
optional
wheter global tax / vat / sales tax are applied, this field will hold the final rate that is applied on the transaction
salesTaxRates
object 
optional
If sales tax are applied, this field will hold the relevant data
gtRates
object (GtRates) 
optional
If global tax / vat are applied, this field will hold the relevant data
transactionStatus
enum<string> 
required
The status of the transaction
Allowed values:
ACTIVECANCELLEDPAID
internalTimestamps
object (internalTimestamps) 
optional
read-only. The APIs internal timestamps for this resource
externalTimestamps
object (externalTimestamps) 
required
External timestamps, which should reference the dates in your originating system since these are the timestamps used for sales tax calculation
transactionType
enum<string> 
required
The type of the transaction. Only invoices are considered for nexus tracking and for actual tax calculation
Allowed values:
SALES_ORDERINVOICEESTIMATEREFUNDTAXABLE_REFUND
shippingFee
object (ShippingFee) 
optional
The shipping fee for the transaction
manualSalesTax
boolean 
optional
The tax culculation will be using manualSalesTaxRate value when manualSalesTax is True. default value is False
manualSalesTaxRate
number 
optional
In correlation to the value of manualSalesTax, this numeric value will be used to calculate the sales tand tax amount
totalPrice
number 
optional
The total price of the shipping fee
taxCode
string 
required
>= 0 characters<= 256 characters
salesTaxRates
object (SalesTaxRates) 
required
gtRates
object (GtRates) 
required
createdFrom
string 
optional
The external ID of the document that preceded this transaction creation (e.g., when creating an invoice, you can pass the ID of the sales order that it originated from here)
>= 0 characters<= 256 characters
taxableItemsAmount
number 
optional
The amount of taxable items in the transaction
tangibleItemsAmount
number 
optional
The amount of tangible items in the transaction
totalItemsAmount
number 
optional
The total amount of items in the transaction. tax and discount excluded
totalDiscount
number 
optional
The total discount of all the items combined. calculated on save
transactionLevelDiscount
number 
optional
The discount to apply on the overall transaction
finalTransactionAmount
number 
optional
The total amount of the transaction after discounts taxes
transactionFilingStatus
enum<string> 
optional
Indicates the status of the transaction in relation to its submission to a specific state. Possible values include:
NOT_FILED: The transaction has not been submitted to the state.
FILED: The transaction has been successfully submitted to the state.
Allowed values:
NOT_FILEDFILED
currency
string 
optional
The currency of the transaction. not mandatory
subsidiary
string 
optional
Example
{
    "externalId": "{{transactionExternalId}}",
    "source": "9",
    "items": [
        {
            "unitPrice": 100,
            "quantity": 1,
            "totalPrice": 100,
            "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",
        "region": "string",
        "isPartial": false
    },
    "shippingAddress": {
       "country":"Canada",
       "region":"Quebec"
    },
    "customerId": "{{customerComplytId}}",
    "externalTimestamps": {
        "createdDate": "2023-02-05T12:24:43.193Z",
        "updatedDate": "2023-02-05T12:24:43.193Z"
    },
    "transactionStatus": "ACTIVE",
    "transactionType": "INVOICE",
    "createdFrom": "string",
    "transactionFilingStatus": "NOT_FILED"
}

Request samples

Shell
JavaScript
Java
Swift
Go
PHP
Python
HTTP
C
C#
Objective-C
Ruby
OCaml
Dart
R
Request Request Example
Shell
JavaScript
Java
Swift
curl --location -g --request PUT 'https://sandbox.complyt.io/v1/transactions/source//externalId/' \
--header 'Content-Type: application/json' \
--data-raw '{
    "externalId": "",
    "source": "9",
    "items": [
        {
            "unitPrice": 100,
            "quantity": 1,
            "totalPrice": 100,
            "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",
        "region": "string",
        "isPartial": false
    },
    "shippingAddress": {
       "country":"Canada",
       "region":"Quebec"
    },
    "customerId": "",
    "externalTimestamps": {
        "createdDate": "2023-02-05T12:24:43.193Z",
        "updatedDate": "2023-02-05T12:24:43.193Z"
    },
    "transactionStatus": "ACTIVE",
    "transactionType": "INVOICE",
    "createdFrom": "string",
    "transactionFilingStatus": "NOT_FILED"
}'

Responses

🟢200Successful operation
application/json
Body
A transaction between the API consumer and a customer
complytId
string <uuid>
optional
The unique identifier in Complyt of the transaction
externalId
string 
required
the attribute designed to receive a unique identifier provided by API consumers themselves (e.g. pass your own ID)
>= 1 characters<= 256 characters
source
string 
required
a single digit which identifies your different stores, checkout solutions, marketplaces, etc. defined by the API consumers (to avoid external id duplications)
Match pattern:
^(10|[1-9])$
documentName
string 
optional
The name of the document, as shown in the ERP systems
>= 0 characters<= 50 characters
items
array [object {16}] 
required
unitPrice
number 
optional
The price of one unit, can be positive and negative
quantity
number 
optional
The quantity of the units, must be positive
totalPrice
number 
optional
The total price of the unit prices time the quantity, can be positive and negative, value is before discount and sales tax
calculatedTotal
number 
optional
The calculated price of the items. represents the total price (or amount time quantity if not provided), after discount. calculated on run time
description
string 
optional
name
string 
required
>= 1 characters<= 256 characters
taxCode
string 
required
>= 0 characters<= 256 characters
jurisdictionalSalesTaxRules
object 
optional
Will hold the relevant rules that are applied on the item. country rules if gt / vat, state rules if USA
salesTaxRates
object (SalesTaxRates) 
optional
gtRates
object (GtRates) 
optional
manualSalesTax
boolean 
optional
manualSalesTaxRate
number 
optional
<= 0.2
discount
number 
optional
The discount of the line items, must be positive
relativeTransactionDiscount
number 
optional
The relative transaction level discount to apply on a specific item. calculated on run time
tangibleCategory
enum<string> 
optional
Allowed values:
TANGIBLEINTANGIBLE
taxableCategory
enum<string> 
optional
Allowed values:
TAXABLENOT_TAXABLE
isTaxInclusive
boolean 
optional
Indicates whether tax is included in the total items price (true) or added as a separate charge (false).
billingAddress
object (billingAddress) 
optional
The billing address for the transaction
city
string 
optional
>= 0 characters<= 100 characters
country
string 
optional
>= 0 characters<= 50 characters
county
string 
optional
>= 0 characters<= 100 characters
state
string 
optional
>= 0 characters<= 100 characters
street
string 
optional
>= 0 characters<= 200 characters
region
string 
optional
>= 0 characters<= 20 characters
zip
string 
optional
>= 0 characters<= 20 characters
shippingAddress
object (shippingAddress) 
required
The shipping address for the transaction
city
string 
required
>= 0 characters<= 100 characters
country
string 
required
>= 0 characters<= 50 characters
county
string 
optional
>= 0 characters<= 100 characters
state
string 
required
>= 0 characters<= 100 characters
street
string 
required
>= 0 characters<= 200 characters
region
string 
optional
>= 0 characters<= 20 characters
zip
string 
required
>= 0 characters<= 20 characters
isPartial
boolean 
required
whether country, city or street are necessary
matchedAddressData
object 
optional
Details of the real address in the US based on the request address.
customerId
string <uuid>
required
The Complyt ID of the customer associated with the transaction
customer
object (Customer) 
optional
The buyer. All transactions are associated with a customer
complytId
string <uuid>
optional
The unique identifier in Complyt of the customer
externalId
string 
required
the attribute designed to receive a unique identifier provided by API consumers themselves (e.g. pass your own ID)
>= 1 characters<= 256 characters
source
string 
required
a single digit which identifies your different stores, checkout solutions, marketplaces, etc. defined by the API consumers (to avoid external id duplications)
Match pattern:
^(10|[1-9])$
name
string 
optional
The customer's name
>= 1 characters<= 256 characters
address
object 
optional
email
string 
optional
An (Optional) Email address associated with the customer
customerType
enum<string> 
optional
Indicates whether the customer is 'retail'/'reseller'/'marketplace'. Defaults to 'retail' if no customer type is provided
Allowed values:
RETAILMARKETPLACERESELLERRETAIL_EXEMPT
internalTimestamps
object (internalTimestamps) 
optional
read-only. The APIs internal timestamps for this resource
externalTimestamps
object (externalTimestamps) 
required
External timestamps, which should reference the dates in your originating system since these are the timestamps used for sales tax calculation
comment
string 
optional
>= 0 characters<= 200 characters
salesTax
object 
optional
amount
number 
optional
wheter global tax / vat / sales tax are applied, this field will hold the final amount that is applied on the transaction
rate
number 
optional
wheter global tax / vat / sales tax are applied, this field will hold the final rate that is applied on the transaction
salesTaxRates
object 
optional
If sales tax are applied, this field will hold the relevant data
gtRates
object (GtRates) 
optional
If global tax / vat are applied, this field will hold the relevant data
transactionStatus
enum<string> 
required
The status of the transaction
Allowed values:
ACTIVECANCELLEDPAID
internalTimestamps
object (internalTimestamps) 
optional
read-only. The APIs internal timestamps for this resource
externalTimestamps
object (externalTimestamps) 
required
External timestamps, which should reference the dates in your originating system since these are the timestamps used for sales tax calculation
transactionType
enum<string> 
required
The type of the transaction. Only invoices are considered for nexus tracking and for actual tax calculation
Allowed values:
SALES_ORDERINVOICEESTIMATEREFUNDTAXABLE_REFUND
shippingFee
object (ShippingFee) 
optional
The shipping fee for the transaction
manualSalesTax
boolean 
optional
The tax culculation will be using manualSalesTaxRate value when manualSalesTax is True. default value is False
manualSalesTaxRate
number 
optional
In correlation to the value of manualSalesTax, this numeric value will be used to calculate the sales tand tax amount
totalPrice
number 
optional
The total price of the shipping fee
taxCode
string 
required
>= 0 characters<= 256 characters
salesTaxRates
object (SalesTaxRates) 
required
gtRates
object (GtRates) 
required
createdFrom
string 
optional
The external ID of the document that preceded this transaction creation (e.g., when creating an invoice, you can pass the ID of the sales order that it originated from here)
>= 0 characters<= 256 characters
taxableItemsAmount
number 
optional
The amount of taxable items in the transaction
tangibleItemsAmount
number 
optional
The amount of tangible items in the transaction
totalItemsAmount
number 
optional
The total amount of items in the transaction. tax and discount excluded
totalDiscount
number 
optional
The total discount of all the items combined. calculated on save
transactionLevelDiscount
number 
optional
The discount to apply on the overall transaction
finalTransactionAmount
number 
optional
The total amount of the transaction after discounts taxes
transactionFilingStatus
enum<string> 
optional
Indicates the status of the transaction in relation to its submission to a specific state. Possible values include:
NOT_FILED: The transaction has not been submitted to the state.
FILED: The transaction has been successfully submitted to the state.
Allowed values:
NOT_FILEDFILED
currency
string 
optional
The currency of the transaction. not mandatory
subsidiary
string 
optional
Example
{
    "complytId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "externalId": "999444",
    "source": "1",
    "items": [
        {
            "unitPrice": 0,
            "quantity": 0,
            "totalPrice": 0,
            "calculatedTotal":0,
            "discount":0,
            "description": "string",
            "name": "string",
            "taxCode": "string",
            "jurisdictionalSalesTaxRules": {
                "name": "string",
                "abbreviation": "string",
                "taxable": true,
                "specialTreatment": true,
                "calculationType": "FIXED",
                "description": "string",
                "calculationValue": 0,
                "cities": null,
                "regions":null
            },
            "salesTaxRates": {
                "cityDistrictRate": 0,
                "cityRate": 0,
                "countyDistrictRate": 0,
                "countyRate": 0,
                "stateRate": 0,
                "taxRate": 0
            },
            "gtRates": {
                "countryRate": 0,
                "regionRate": 0,
                "taxRate": 0
            },
            "manualSalesTax": true,
            "manualSalesTaxRate": 0,
            "tangibleCategory": "TANGIBLE",
            "taxableCategory": "TAXABLE"
        }
    ],
    "billingAddress": {
        "city": "string",
        "country": "string",
        "county": "string",
        "state": "string",
        "street": "string",
        "zip": "string",
        "isPartial": false
    },
    "shippingAddress": {
        "city": "string",
        "country": "string",
        "county": "string",
        "state": "string",
        "street": "string",
        "zip": "string",
        "region":"string",
        "isPartial": false
    },
    "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",
            "isPartial": false
        },
        "email": "example@some.mail.com",
        "customerType": "RETAIL",
        "internalTimestamps": {
            "createdDate": "2023-02-05T12:24:43.193Z",
            "updatedDate": "2023-02-05T12:24:43.193Z"
        },
        "externalTimestamps": {
            "createdDate": "2023-02-05T12:24:43.193Z",
            "updatedDate": "2023-02-05T12:24:43.193Z"
        }
    },
    "salesTax": {
        "amount": 0,
        "taxRate": 0,
        "salesTaxRates": {
            "cityDistrictRate": 0,
            "cityRate": 0,
            "countyDistrictRate": 0,
            "countyRate": 0,
            "stateRate": 0,
            "taxRate": 0
        },
        "gtRates": {
             "countryRate": 0,
             "regionRate": 0,
             "taxRate": 0
        },
    },
    "transactionStatus": "ACTIVE",
    "internalTimestamps": {
        "createdDate": "2023-02-05T12:24:43.193Z",
        "updatedDate": "2023-02-05T12:24:43.193Z"
    },
    "externalTimestamps": {
        "createdDate":"2023-02-05T12:24:43.193Z",
        "updatedDate": "2023-02-05T12:24:43.193Z"
    },
    "transactionType": "SALES_ORDER",
    "shippingFee": {
        "manualSalesTax": true,
        "manualSalesTaxRate": 0,
        "totalPrice": 0,
        "calculatedTotal":0,
        "taxCode": "string",
        "taxableCategory": "TAXABLE",
        "tangibleCategory": "TANGIBLE",
        "jurisdictionalSalesTaxRules": {
            "name": "string",
            "abbreviation": "string",
            "taxable": true,
            "specialTreatment": true,
            "calculationType": "FIXED",
            "description": "string",
            "calculationValue": 0,
            "cities": null
        },
        "salesTaxRates": {
            "cityDistrictRate": 0,
            "cityRate": 0,
            "countyDistrictRate": 0,
            "countyRate": 0,
            "stateRate": 0,
            "taxRate": 0
        },
        "gtRates": {
             "countryRate": 0,
             "regionRate": 0,
             "taxRate": 0
        },
    },
    "createdFrom": "string",
    "taxableItemsAmount": 0,
    "tangibleItemsAmount": 0,
    "totalItemsAmount": 0,
    "totalDiscount" :0,
    "transactionFilingStatus": "NOT_FILED"
}
🟢201Successful operation
🟠400Something is wrong with your request
🟠401Unauthorized
🟠403Forbidden
🟠404Transaction Not Found
🔴500Internal Error
Modified at 2024-12-18 13:29:48
Previous
Get All Transactions
Next
Address Validation Intro
Built with