# SettleTransaction

Perform multiple actions on a transaction

`POST /api/v2/companies/{companyCode}/transactions/{transactionCode}/settle`

**API:** AvaTax API
**Tag:** Transactions
**API Version:** v2
**Base URL:** https://sandbox-rest.avatax.com/
**Content-Type:** `application/json`
**Accepts:** `application/json`
**Authentication:** API Key (`Authorization` in header) or OAuth 2.0 or Basic (username + license key)

Source: https://developer.avalara.com/products/crossborder/api/methods/Transactions/SettleTransaction/

## Description

Performs one or more actions against the current transaction uniquely identified by this URL.
            
The `SettleTransaction` API call can perform the work of `ChangeCode`, `VerifyTransaction`, and `CommitTransaction`.
            
A transaction represents a unique potentially taxable action that your company has recorded, and transactions include actions like
sales, purchases, inventory transfer, and returns (also called refunds).
            
If you have more than one document with the same `code`, specify the `documentType` parameter to choose between them.
            
This API is available for users who want to execute more than one action at a time.
            
You may specify one or more of the following values in the `$include` parameter to fetch additional nested data, using commas to separate multiple values:
            
* Lines
* Details (implies lines)
* AccountPayableSalesTaxDetails (implies lines - only for Account Payable transaction)
* Summary (implies details)
* Addresses
* SummaryOnly (omit lines and details - reduces API response size)
* LinesOnly (omit details - reduces API response size)
* TaxDetailsByTaxType - Includes the aggregated tax, exempt tax, taxable and non-taxable for each tax type returned in the transaction summary.
            
NOTE: If your companyCode or transactionCode contains any of these characters /, +, ? or a space please use the following encoding before making a request:
* Replace '/' with '\_-ava2f-\_'  For example: document/Code becomes document_-ava2f-_Code
* Replace '+' with '\_-ava2b-\_'  For example: document+Code becomes document_-ava2b-_Code
* Replace '?' with '\_-ava3f-\_'  For example: document?Code becomes document_-ava3f-_Code
* Replace '%' with '\_-ava25-\_'  For example: document%Code becomes document_-ava25-_Code
* Replace '#' with '\_-ava23-\_'  For example: document#Code becomes document_-ava23-_Code
* Replace ' ' with '%20'  For example: document Code becomes document%20Code

### Security Policies

* This API requires one of the following user roles: AccountAdmin, AccountOperator, AccountUser, AvaTaxOnlyAccountAdmin, AvaTaxOnlyAccountUser, AvaTaxOnlyCompanyAdmin, AvaTaxOnlyCompanyUser, BatchServiceAdmin, CompanyAdmin, CompanyUser, CSPTester, ProStoresOperator, SSTAdmin, TechnicalSupportAdmin.

## Parameters

| Name | Type | In | Required | Description |
|---|---|---|---|---|
| `companyCode` | string | path | Yes | The company code of the company that recorded this transaction |
| `transactionCode` | string | path | Yes | The transaction code to settle |
| `documentType` | string | query | No | (Optional): The document type of the transaction to settle. If not provided, the default is SalesInvoice. |
| `$include` | string | query | No | Specifies objects to include in this fetch call |
| `X-Avalara-Client` | string | header | No | Identifies the software you are using to call this API.  For more information on the client header, see [Client Headers](https://developer.avalara.com/avatax/client-headers/) . |

## Request Body

**Schema:** `SettleTransactionModel`

Settle this transaction with your ledger by executing one or many actions against that transaction.
            
You may use this endpoint to verify the transaction, change the transaction's code, and commit the transaction for reporting purposes.
This endpoint may be used to execute any or all of these actions at once.

| Property | Type | Required | Description |
|---|---|---|---|
| `verify` | VerifyTransactionModel | No | To verify this transaction, you may provide information in this field.
            
If you leave this field null, the transaction will not be verified. |
| `changeCode` | ChangeTransactionCodeModel | No | To change the code for this transaction, you may provide information in this field.
            
If you leave this field null, the transaction's code will not be changed. |
| `commit` | CommitTransactionModel | No | To commit this transaction so that it can be reported on a tax filing, you may provide information in this field.
            
If you leave this field null, the transaction's commit status will not be changed.
            
If you use Avalara's Managed Returns Service, committing a transaction will allow that transaction to be filed. |

## Responses

| Status | Description | Schema |
|---|---|---|
| 200 | Success | `TransactionModel` |
| 400 | Bad Request |  |
| 401 | Unauthorized |  |
| 404 | Not Found |  |

### 200 Response: `TransactionModel`

This object represents a single transaction; for example, a sales invoice or purchase order.

| Property | Type | Required | Description |
|---|---|---|---|
| `id` | integer | No | The unique ID number of this transaction. Example: `123456789`. |
| `code` | string | No | A unique customer-provided code identifying this transaction. Example: `0cd694b3-8e99-431d-a845-41dc182a8fa6`. |
| `companyId` | integer | No | The unique ID number of the company that recorded this transaction. Example: `12345`. |
| `date` | string | No | The date on which this transaction occurred. Example: `2026-07-02T00:00:00+00:00`. |
| `paymentDate` | string | No | DEPRECATED - Date: 07/25/2018, Version: 18.7, Message: This field is deprecated and will return null till its removed.
The date when payment was made on this transaction.  By default, this should be the same as the date of the transaction. |
| `status` | string | No | The status of the transaction. Values: `Temporary`, `Saved`, `Posted`, `Committed`, `Cancelled`, `Adjusted`, `Queued`, `PendingApproval`, `Uncommitted`, `Any`. Example: `Temporary`. |
| `type` | string | No | The type of the transaction.
            
Transactions of type `SalesOrder`, `ReturnOrder`, and so on are temporary estimates and will not be saved.
            
Transactions of type `SalesInvoice, `ReturnInvoice`, and so on are permanent transactions that can be reported to tax authorities
if they are in status `Committed`.
            
A sales transaction represents a sale from the company to a customer.  A purchase transaction represents a purchase made by the company.
A return transaction represents a customer who decided to request a refund after purchasing a product from the company.  An inventory
transfer transaction represents goods that were moved from one location of the company to another location without changing ownership. Values: `SalesOrder`, `SalesInvoice`, `PurchaseOrder`, `PurchaseInvoice`, `ReturnOrder`, `ReturnInvoice`, `InventoryTransferOrder`, `InventoryTransferInvoice`, `ReverseChargeOrder`, `ReverseChargeInvoice`, `CustomsInvoice`, `CustomsOrder`, `InventoryTransferOutboundInvoice`, `InventoryTransferOutboundOrder`, `Any`. Example: `SalesOrder`. |
| `batchCode` | string | No | If this transaction was created as part of a batch, this code indicates which batch. |
| `currencyCode` | string | No | The three-character ISO 4217 currency code representing the ‘invoice currency’ (the currency the transaction was invoiced in). 
If this is different than the currency the tax liability needs to be reported in, you’ll also need to provide the 
`exchangeRateCurrencyCode` and the `exchangeRate` for conversion to the reporting country. Example: `USD`. |
| `exchangeRateCurrencyCode` | string | No | The three-character ISO 4217 currency code representing the ‘reporting currency’ (the currency the transaction’s tax liability needs to be reported in). 
You can leave this blank if the invoice currency provided in the `currencyCode` field is also the reporting currency. Example: `USD`. |
| `customerUsageType` | string | No | DEPRECATED - Date: 10/16/2017, Version: 17.11, Message: Please use entityUseCode instead.
The customer usage type for this transaction.  Customer usage types often affect exemption or taxability rules. |
| `entityUseCode` | string | No | The entity use code for this transaction.  Entity use codes often affect exemption or taxability rules. Example: ``. |
| `customerVendorCode` | string | No | DEPRECATED - Date: 3/1/2018, Version: 18.3, Message: Please use `customerCode`
This field has been renamed to `customerCode` to match documentation for other APIs related to exemption customers. Example: `ABC`. |
| `customerCode` | string | No | Unique code identifying the customer that requested this transaction.
            
When you specify a `customerCode`, AvaTax will look to see if a customer exists with this code in the exemption certificate system.
If that customer exists, and if that customer has uploaded an exemption certificate that applies to this transaction, the relevant
parts of this transaction that can use the exemption certificate will be treated as exempt. Example: `ABC`. |
| `exemptNo` | string | No | The customer Tax Id Number (tax_number) associated with a certificate - Sales tax calculation requests first determine if there is an applicable
ECMS entry available, and will utilize it for exemption processing. If no applicable ECMS entry is available, the AvaTax service
will determine if an Exemption Number field is populated or an Entity/Use Code is included in the sales tax calculation request,
and will perform exemption processing using either of those two options. Example: ``. |
| `reconciled` | boolean | No | If this transaction has been reconciled against the company's ledger, this value is set to true. Example: `true`. |
| `locationCode` | string | No | DEPRECATED - Date: 3/1/2018, Version: 18.3, Message: In order to ensure consistency of field names, Please use reportingLocationCode instead.
This field has been replaced by the reportingLocationCode field Example: `DEFAULT`. |
| `reportingLocationCode` | string | No | For customers who use [location-based tax reporting](https://developer.avalara.com/avatax/dev-guide/locations/location-based-reporting),
this field controls how this transaction will be filed for multi-location tax filings.
            
If you specify a non-null value for this field, AvaTax will ensure that this transaction is reported on the tax return associated
with the [LocationModel](https://developer.avalara.com/api-reference/avatax/rest/v2/models/LocationModel/) identified by this code.
            
This field does not affect any addresses for the transaction.  It only controls the tax filing behavior of this transaction.
            
If you are looking for information about how to set up addresses for a transaction, please see [Using Address Types](https://developer.avalara.com/avatax/dev-guide/customizing-transaction/address-types/)
in the AvaTax Developer Guide. |
| `purchaseOrderNo` | string | No | The customer-supplied purchase order number of this transaction. |
| `referenceCode` | string | No | A user-defined reference code for this transaction. |
| `salespersonCode` | string | No | The salesperson who provided this transaction.  Not required. Example: `DEF`. |
| `taxOverrideType` | string | No | If a tax override was applied to this transaction, indicates what type of tax override was applied. Values: `None`, `TaxAmount`, `Exemption`, `TaxDate`, `AccruedTaxAmount`, `DeriveTaxable`, `OutOfHarbor`, `TaxAmountByTaxType`, `VendorChargedTax`. Example: `None`. |
| `taxOverrideAmount` | number | No | If a tax override was applied to this transaction, indicates the amount of tax that was requested by the customer. Example: `0`. |
| `taxOverrideReason` | string | No | If a tax override was applied to this transaction, indicates the reason for the tax override. Example: ``. |
| `totalAmount` | number | No | The total amount of this transaction. Example: `1000`. |
| `totalExempt` | number | No | The amount of this transaction that was exempt. Example: `0`. |
| `totalDiscount` | number | No | The total amount of discounts applied to all lines within this transaction. Example: `0`. |
| `totalTax` | number | No | The total tax for all lines in this transaction.
            
If you used a `taxOverride` of type `taxAmount` for any lines in this transaction, this value
may be different than the amount of tax calculated by AvaTax.  The amount of tax calculated by
AvaTax will be stored in the `totalTaxCalculated` field, whereas this field will contain the
total tax that was charged on the transaction.
            
You can compare the `totalTax` and `totalTaxCalculated` fields to check for any discrepancies
between an external tax calculation provider and the calculation performed by AvaTax. Example: `62.5`. |
| `totalTaxable` | number | No | The portion of the total amount of this transaction that was taxable. Example: `1000`. |
| `totalTaxCalculated` | number | No | The amount of tax that AvaTax calculated for the transaction.
            
If you used a `taxOverride` of type `taxAmount` for any lines in this transaction, this value
will represent the amount that AvaTax calculated for this transaction without applying the override.
The field `totalTax` will be the total amount of tax after all overrides are applied.
            
You can compare the `totalTax` and `totalTaxCalculated` fields to check for any discrepancies
between an external tax calculation provider and the calculation performed by AvaTax. Example: `62.5`. |
| `adjustmentReason` | string | No | If this transaction was adjusted, indicates the unique ID number of the reason why the transaction was adjusted. Values: `NotAdjusted`, `SourcingIssue`, `ReconciledWithGeneralLedger`, `ExemptCertApplied`, `PriceAdjusted`, `ProductReturned`, `ProductExchanged`, `BadDebt`, `Other`, `Offline`. Example: `NotAdjusted`. |
| `adjustmentDescription` | string | No | If this transaction was adjusted, indicates a description of the reason why the transaction was adjusted. Example: ``. |
| `locked` | boolean | No | If this transaction has been reported to a tax authority, this transaction is considered locked and may not be adjusted after reporting. Example: `false`. |
| `region` | string | No | The two-or-three character ISO region code of the region for this transaction. Example: `CA`. |
| `country` | string | No | The two-character ISO 3166 code of the country for this transaction. Example: `US`. |
| `version` | integer | No | If this transaction was adjusted, this indicates the version number of this transaction.  Incremented each time the transaction
is adjusted. Example: `0`. |
| `softwareVersion` | string | No | The software version used to calculate this transaction. |
| `originAddressId` | integer | No | The unique ID number of the origin address for this transaction. Example: `123456789`. |
| `destinationAddressId` | integer | No | The unique ID number of the destination address for this transaction. Example: `123456789`. |
| `exchangeRateEffectiveDate` | string | No | If this transaction included foreign currency exchange, this is the date as of which the exchange rate was calculated. Example: `2026-07-02T00:00:00+00:00`. |
| `exchangeRate` | number | No | The currency exchange rate from the invoice currency (`currencyCode`) to the reporting currency (`exchangeRateCurrencyCode`).
This only needs to be set if the invoice currency and the reporting currency are different. It defaults to 1.0. Example: `2`. |
| `isSellerImporterOfRecord` | boolean | No | By default, the value is null, when the value is null, the value can be set at nexus level and used.
If the value is not null, it will override the value at nexus level.
            
If true, this seller was considered the importer of record of a product shipped internationally.
            
If this transaction is not an international transaction, this field may be left blank.
            
The "importer of record" is liable to pay customs and import duties for products shipped internationally.  If
you specify that the seller is the importer of record, then estimates of customs and import duties will be added
as tax details to the transaction.  Otherwise, the buyer is considered the importer of record, and customs
and import duties will not be added to the tax details for this transaction. Example: `false`. |
| `description` | string | No | Description of this transaction.  Field permits unicode values. Example: `Yarn`. |
| `email` | string | No | Email address associated with this transaction. |
| `businessIdentificationNo` | string | No | VAT business identification number used for this transaction. |
| `modifiedDate` | string | No | The date/time when this record was last modified. |
| `modifiedUserId` | integer | No | The user ID of the user who last modified this record. |
| `taxDate` | string | No | Tax date for this transaction Example: `2026-07-02T00:00:00+00:00`. |
| `lines` | TransactionLineModel[] | No | A list of line items in this transaction.  To fetch this list, add the query string `?$include=Lines` or `?$include=Details` to your URL. |
| `addresses` | TransactionAddressModel[] | No | A list of line items in this transaction.  To fetch this list, add the query string `?$include=Addresses` to your URL.
            
For more information about transaction addresses, please see [Using Address Types](https://developer.avalara.com/avatax/dev-guide/customizing-transaction/address-types/)
in the AvaTax Developer Guide. |
| `locationTypes` | TransactionLocationTypeModel[] | No | A list of location types in this transaction.  To fetch this list, add the query string `?$include=Addresses` to your URL. |
| `summary` | TransactionSummary[] | No | Contains a summary of tax on this transaction. |
| `taxDetailsByTaxType` | TaxDetailsByTaxType[] | No | Contains the tax details per tax type |
| `parameters` | TransactionParameterModel[] | No | Contains a list of extra parameters that were set when the transaction was created. |
| `userDefinedFields` | TransactionUserDefinedFieldModel[] | No | Custom user fields/flex fields for this transaction. |
| `messages` | AvaTaxMessage[] | No | List of informational and warning messages regarding this API call.  These messages are only relevant to the current API call. |
| `invoiceMessages` | InvoiceMessageModel[] | No | Invoice messages associated with this document. Currently, this stores legally-required VAT messages. |
| `customerSupplierName` | string | No | The name of the supplier / exporter / seller.
For sales doctype this will be the name of your own company for which you are reporting.
For purchases doctype this will be the name of the supplier you have purchased from. |
| `dataSourceId` | integer | No | The Id of the datasource from which this transaction originated.
This value will be overridden by the system to take the datasource Id from the call header. |
| `deliveryTerms` | string | No | Delivery Terms (or Incoterms) refer to agreed-upon conditions between a buyer and a seller for the delivery of goods. They are three-letter 
trade terms that describe the practical arrangements for the delivery of goods from sellers to buyers and set out the obligations, costs, and 
risks between the two parties.
The DeliveryTerms field determines who acts as the Importer of Record and who arranges the Transport of the goods when this 
information is not separately sent to AvaTax in the request. When used in conjunction with isSellerImporterOfRecord, this parameter can also 
influence whether AvaTax includes Import Duty and Tax in the transaction totals. If the fields for transport or isSellerImporterOfRecord are 
passed in the request and conflict with the DeliveryTerms, the values provided in the first will take priority over the DeliveryTerms 
parameter. If neither transport nor isSellerImporterOfRecord is passed in the request and DeliveryTerms is passed, AvaTax will determine who 
acts as Importer of Record and who arranges the Transport of the goods based on the specified DeliveryTerms. If none of these fields is 
passed, AvaTax will keep the current behavior and default transport to "Seller" for goods and isSellerImporterOfRecord to "False" (i.e., the 
AvaTax user does not act as Importer of record)."
Finally, this field is also used for reports.

The Delivery Terms that the user can pass are the following:
1. Ex Works (EXW)
2. Free Carrier (FCA)
3. Carrier and Insurance Paid to (CIP)
4. Carriage Paid To (CPT)
5. Delivered at Place (DAP)
6. Delivered at Place Unloaded (DPU)
7. Delivered Duty Paid (DDP)
8. Free Alongside Ship (FAS)
9. Free on Board (FOB)
10. Cost and Freight (CFR)
11. Cost, Insurance and Freight (CIF)

DAP and DDP are two delivery terms that indicate that Import Duty and Tax should be included in the transaction total. Values: `DAP`, `DDP`, `FOB`, `FCA`, `FAS`, `EXW`, `DPU`, `CPT`, `CIP`, `CIF`, `CFR`. Example: `DAP`. |
| `apStatusCode` | string | No | Users can set tolerance or threshold limits on transactions and inform users of appropriate actions to take
if a transaction falls outside of these values. 
An Accounts Payable (AP) status code indicates the action that needs to be taken when the tolerance/threshold 
falls above or below the tolerance/threshold limits.
            
Available AP status codes are:
1. NoAccrualMatch
2. NoAccrualUndercharge
3. NoAccrualOvercharge
4. NoAccrualAmountThresholdNotMet
5. NoAccrualTrustedVendor
6. NoAccrualExemptedCostCenter
7. NoAccrualExemptedItem
8. NoAccrualExemptedVendor
9. NoAccrualRejectMatch
10. NoAccrualRejectUndercharge
11. NoAccrualShortPayAvalaraCalculated
12. NoAccrualRejectOvercharge
13. NoAccrualExemptedGLAccount
14. AccruedUndercharge
15. AccruedVendor
16. AccruedShortPayItemsMatch
17. AccruedShortPayItemsUndercharge
18. AccruedShortPayItemsOvercharge
19. NeedReviewUndercharge
20. NeedReviewVendor
21. NeedReviewMatch
22. NeedReviewOvercharge
23. PendingAccrualVendor
24. PendingAccrualUndercharge
25. PendingShortPayItemsUndercharge
26. PendingShortPayItemsMatch
27. PendingShortPayItemsOvercharge Values: `NoAccrualMatch`, `AccruedShortPayItemsMatch`, `NeedReviewMatch`, `NoAccrualRejectMatch`, `NoAccrualUndercharge`, `AccruedUndercharge`, `AccruedShortPayItemsUndercharge`, `NeedReviewUndercharge`, `NoAccrualRejectUndercharge`, `NoAccrualOvercharge`, `NoAccrualShortPayAvalaraCalculated`, `AccruedShortPayItemsOvercharge`, `NeedReviewOvercharge`, `NoAccrualRejectOvercharge`, `NoAccrualAmountThresholdNotMet`, `NoAccrualExemptedCostCenter`, `NoAccrualExemptedItem`, `NoAccrualTrustedVendor`, `AccruedVendor`, `NeedReviewVendor`, `NoAccrualExemptedVendor`, `NoAccrualExemptedGLAccount`, `PendingAccrualVendor`, `PendingAccrualUndercharge`, `PendingShortPayItemsUndercharge`, `PendingShortPayItemsMatch`, `PendingShortPayItemsOvercharge`, `NoAccrualExemptedMapping`, `ShortPayItemsAccrueMatch`, `MarkForReviewMatch`, `RejectMatch`, `ShortPayItemsAccrueUndercharge`, `RejectUndercharge`, `ShortPayAvalaraCalculated`, `ShortPayItemsAccrueOvercharge`, `MarkForReviewOvercharge`, `RejectOvercharge`. Example: `NoAccrualMatch`. |
| `apStatus` | string | No | An Accounts Payable (AP) status indicates an action that needs to be taken when the tolerance amount falls 
above or below certain threshold limits. |
| `vendorName` | string | No | The name of the vendor |
| `varianceAmount` | number | No | The transaction-level variance (the difference between Vendor Charged Tax and AvaTax Calculated Tax) that has been calculated for this AP transaction. |

## Example Request

```bash
curl -X POST "https://sandbox-rest.avatax.com/api/v2/companies/{companyCode}/transactions/{transactionCode}/settle" \
  -H "Authorization: Basic <credentials>" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
  "verify": {
    "verifyTransactionDate": "2026-07-02T00:00:00+00:00",
    "verifyTotalAmount": 100,
    "verifyTotalTax": 6.25
  },
  "changeCode": {
    "newCode": "de46acbd-f0f7-47c7-bd92-ebe2ac3ddace"
  },
  "commit": {
    "commit": true
  }
}'
```