API Docs
API Docs
  1. Endpoints
  2. 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
  1. Endpoints
  2. Transactions

Upsert Transaction

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
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 (Item Request) {9}] 
required
unitPrice
number 
required
The price of one unit, can be positive and negative
quantity
number 
required
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. If totalPrice exist it will override the unitPrice and quantity calculation
description
string 
optional
name
string 
required
>= 1 characters<= 256 characters
taxCode
string 
required
>= 0 characters<= 256 characters
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
<= 0.2
discount
number 
optional
The discount of the line items, must be positive
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 Copy) 
required
The address that the tax calculation based on
country
string 
required
>= 0 characters<= 50 characters
region
string 
optional
>= 0 characters<= 20 characters
city
string 
optional
>= 0 characters<= 100 characters
county
string 
optional
>= 0 characters<= 100 characters
state
string 
optional
>= 0 characters<= 100 characters
street
string 
optional
>= 0 characters<= 200 characters
zip
string 
optional
>= 0 characters<= 20 characters
isPartial
boolean 
optional
whether country, city or street are necessary
customerId
string <uuid>
required
The Complyt ID of the customer associated with the transaction
transactionStatus
enum<string> 
required
The status of the transaction
Allowed values:
ACTIVECANCELLEDPAID
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
createdDate
string 
required
The creation time of the transaction
updatedDate
string 
required
The last update time of the transaction
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
transactionLevelDiscount
number 
optional
The discount to apply on the overall transaction
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
refRate
number 
optional
The manual currency exchange rate
subsidiary
string 
optional
isRefundLinked
boolean 
optional
If set to true, the sales tax will be taken from the invoice specified in the createdFrom field and returned as the refund's salesTax.amount
Example
{
  "externalId": "{{transactionExternalId}}",
  "source": "{{source}}",
  "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": {
    "city": "fresno",
    "country": "US",
    "county": null,
    "state": "CA",
    "street": "3098 N Remington Ave",
    "zip": "93711-5508",
    "region": "string",
    "isPartial": false
  },
  "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",
  "currency": "USD"
}

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": "",
    "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": {
        "city": "fresno",
        "country": "US",
        "county": null,
        "state": "CA",
        "street": "3098 N Remington Ave",
        "zip": "93711-5508",
        "region": "string",
        "isPartial": false
    },
    "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",
    "currency": "USD"
}'

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. Required only on update operations.
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 (Item Response) {16}] 
required
unitPrice
number 
required
The price of one unit, can be positive and negative
quantity
number 
required
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 (JurisdictionalSalesTaxRules) 
optional
salesTaxRates
object (SalesTaxRates) 
optional
gtRates
object (GtRates) 
optional
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
<= 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 
required
The address that the tax calculation based on
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> 
required
Indicates whether the customer is 'retail'/'reseller'/'marketplace'
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, tax excluded
tangibleItemsAmount
number 
optional
The amount of tangible items in the transaction, tax excluded
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 and 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
refRate
number 
optional
The manual currency exchange rate
exchangeRateInfo
object (ExchangeRateInfo) 
optional
Details regarding the currency conversion
totalItemsAmountInUsd
number 
optional
The transaction totalItemsAmount converted to USD
transactionSalesTaxInUsd
number 
optional
The transaction salesTax.amount converted to USD
finalTransactionAmountInUsd
number 
optional
The transaction final amount converted to USD (items and sales tax)
fromCurrency
string 
optional
The original currency specified in the transaction
toCurrency
string 
optional
The target currency (USD)
fxRate
number 
optional
The exchange rate that applied on the transaction
source
enum<string> 
optional
The source of fxRate. If entered manually in refRate then the value would be CLIENT.
Allowed values:
COMPLYTCLIENT
isExchangeRateEstimated
boolean 
optional
Flag that specified whether the exchange rate is estimate. true for future transactions
exchangeRateDate
string 
optional
The date in which the exchange rate was taken
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,
         "matchedAddressData": {
            "address": {
                "city": "string",
                "country": "string",
                "county": "string",
                "state": "string",
                "zip": "string"
            },
            "scoring": {
                "matchLevel": "string",
                "score": 1.0,
                "fieldScore": {
                    "countryMatch": "string",
                    "stateMatch": "string",
                    "cityMatch": "string",
                    "zipMatch": "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",
            "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
🟠400ERR-ADDR-001
Modified at 2025-02-12 15:50:11
Previous
Get Transaction
Next
Delete Transaction
Built with