Complyt Docs
  • Getting Started
  • Endpoints
    • Authentication
    • Customers
    • Exemptions
    • Transactions
      • Get to Know
      • The Important Of Shipping Address
      • Get Transaction (thin)GET
      • Get TransactionGET
      • Upsert TransactionPUT
      • Delete TransactionDELETE
      • Get All Transactions (thin)GET
      • Get All TransactionsGET
      • Upsert VAT / GT TransactioPUT
    • Files
  • Special Features
logoPowered by Apidog
  1. Endpoints
  2. Transactions

Upsert Transaction

PUT/v1/transactions/source/{source}/externalId/{externalId}

Update or Insert Transaction by External ID and source

Request

Authorization: Bearer Token
Provide your bearer token in the
Authorization
header when making requests to protected resources.
Example
Authorization: Bearer 2f68dbbf-519d-4f01-9636-e2421b68f379
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
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) 
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

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

Responses

Successful operation(200)
Successful operation(201)
Something is wrong with your request(400)
Unauthorized(401)
Forbidden(403)
Transaction Not Found(404)
Internal Error(500)
ERR-ADDR-001(400)
Successful operation
HTTP Code: 200
Content Type : JSONapplication/json
Data Schema
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

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
    },
    "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"
}
Last modified: 20 days ago