# CreateMultiDocumentTransaction

Create a new MultiDocument transaction

`POST /api/v2/transactions/multidocument`

**API:** AvaTax API
**Tag:** MultiDocument
**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/MultiDocument/CreateMultiDocumentTransaction/

## Description

Records a new MultiDocument transaction in AvaTax.
            
A traditional transaction requires exactly two parties: a seller and a buyer.  MultiDocument transactions can
involve a marketplace of vendors, each of which contributes some portion of the final transaction.  Within
a MultiDocument transaction, each individual buyer and seller pair are matched up and converted to a separate
document.  This separation of documents allows each seller to file their taxes separately.
            
This API will report an error if you attempt to create a transaction when one already exists with the specified `code`.
If you would like the API to automatically update the transaction when it already exists, please set the `allowAdjust`
value to `true`.
            
To generate a refund for a transaction, use the `RefundTransaction` API.
            
The field `type` identifies the kind of transaction - for example, a sale, purchase, or refund.  If you do not specify
a `type` value, you will receive an estimate of type `SalesOrder`, which will not be recorded.
            
The origin and destination locations for a transaction must be identified by either address or geocode.  For address-based transactions, please
provide addresses in the fields `line`, `city`, `region`, `country` and `postalCode`.  For geocode-based transactions, please provide the geocode
information in the fields `latitude` and `longitude`.  If either `latitude` or `longitude` or both are null, the transaction will be calculated
using the best available address location information.
            
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)
* Summary (implies details)
* Addresses
* SummaryOnly (omit lines and details - reduces API response size)
* LinesOnly (omit details - reduces API response size)
* ForceTimeout - Simulates a timeout.  This adds a 30 second delay and error to your API call.  This can be used to test your code to ensure it can respond correctly in the case of a dropped connection.
            
If you omit the `$include` parameter, the API will assume you want `Summary,Addresses`.
            
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, ReturnsOnlyAccountAdmin, ReturnsOnlyCompanyAdmin, SSTAdmin, TechnicalSupportAdmin, TechnicalSupportUser.
* This API depends on the following active services:*Required* (all):  AvaTaxPro.

## Parameters

| Name | Type | In | Required | Description |
|---|---|---|---|---|
| `$include` | string | query | No | Specifies objects to include in the response after transaction is created |
| `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:** `CreateMultiDocumentModel`

A MultiDocument transaction represents a sale or purchase that occurred between more than two companies.
            
A traditional transaction requires exactly two parties: a seller and a buyer.  MultiDocument transactions can
involve a marketplace of vendors, each of which contributes some portion of the final transaction.  Within
a MultiDocument transaction, each individual buyer and seller pair are matched up and converted to a separate
document.  This separation of documents allows each seller to file their taxes separately.

| Property | Type | Required | Description |
|---|---|---|---|
| `code` | string | No | The transaction code of the MultiDocument transaction.
            
All individual transactions within this MultiDocument object will have this code as a prefix.
            
If you leave the `code` field blank, a GUID will be assigned. |
| `lines` | MultiDocumentLineItemModel[] | **Yes** | Lines that will appear on the invoice.
            
For a MultiDocument transaction, each line may represent a different company or reporting location code.  AvaTax
will separate this MultiDocument transaction object into many different transactions, one for each pair of legal
entities, so that each legal entity can file their transactional taxes correctly. |
| `allowAdjust` | boolean | No | Set this value to true to allow this API call to adjust the MultiDocument model if one already exists.
            
If you omit this field, or if the value is `null`, you will receive an error if you try to create two MultiDocument
objects with the same `code`. |
| `type` | string | No | Specifies the type of document to create.  A document type ending with `Invoice` is a permanent transaction
that will be recorded in AvaTax.  A document type ending with `Order` is a temporary estimate that will not
be preserved.
            
If you omit this value, the API will assume you want to create a `SalesOrder`. Values: `SalesOrder`, `SalesInvoice`, `PurchaseOrder`, `PurchaseInvoice`, `ReturnOrder`, `ReturnInvoice`, `InventoryTransferOrder`, `InventoryTransferInvoice`, `ReverseChargeOrder`, `ReverseChargeInvoice`, `CustomsInvoice`, `CustomsOrder`, `InventoryTransferOutboundInvoice`, `InventoryTransferOutboundOrder`, `Any`. Example: `SalesOrder`. |
| `companyCode` | string | No | Company Code - Specify the code of the company creating this transaction here.  If you leave this value null,
your account's default company will be used instead. Example: `DEFAULT`. |
| `date` | string | **Yes** | Transaction Date - The date on the invoice, purchase order, etc. AvaTax accepts date values in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601)
format and stores the date as `yyyy-MM-dd`.
            
By default, this date will be used to calculate the tax rates for the transaction.  If you want to use a
different date to calculate tax rates, please specify a `taxOverride` of type `taxDate`. Example: `2026-07-02T00:00:00+00:00`. |
| `salespersonCode` | string | No | Salesperson Code - The client application salesperson reference code. |
| `customerCode` | string | **Yes** | Customer Code - The client application customer reference code.
Note: This field is case sensitive. To have exemption certificates apply, this value should
be the same as the one passed to create a customer. Example: `ABC`. |
| `customerUsageType` | string | No | DEPRECATED - Date: 10/16/2017, Version: 17.11, Message: Please use entityUseCode instead.
Customer Usage Type - The client application customer or usage type. |
| `entityUseCode` | string | No | Entity Use Code - The client application customer or usage type.  For a list of
available usage types, use [ListEntityUseCodes](https://developer.avalara.com/api-reference/avatax/rest/v2/methods/Definitions/ListEntityUseCodes/) API. |
| `discount` | number | No | Discount - The discount amount to apply to the document.  This value will be applied only to lines
that have the `discounted` flag set to true.  If no lines have `discounted` set to true, this discount
cannot be applied. |
| `purchaseOrderNo` | string | No | Purchase Order Number for this document.
            
This is required for single use exemption certificates to match the order and invoice with the certificate. Example: `2026-07-02-001`. |
| `exemptionNo` | string | No | Exemption Number for this document.
            
If you specify an exemption number for this document, this document will be considered exempt, and you
may be asked to provide proof of this exemption certificate in the event that you are asked by an auditor
to verify your exemptions.
Note: This is same as 'exemptNo' in TransactionModel. |
| `addresses` | AddressesModel | No | Default addresses for all lines in this document.
            
These addresses are the default values that will be used for any lines that do not have their own
address information.  If you specify addresses for a line, then no default addresses will be loaded
for that line. |
| `parameters` | TransactionParameterModel[] | No | Special parameters for this transaction.
            
To get a full list of available parameters, please use the [ListParameters](https://developer.avalara.com/api-reference/avatax/rest/v2/methods/Definitions/ListParameters/) endpoint. |
| `userDefinedFields` | TransactionUserDefinedFieldModel[] | No | Custom user fields/flex fields for this transaction. |
| `referenceCode` | string | No | Customer-provided Reference Code with information about this transaction.
            
This field could be used to reference the original document for a return invoice, or for any other
reference purpose. |
| `reportingLocationCode` | string | No | Sets the sale location code (Outlet ID) for reporting this document to the tax authority.
            
This value is used by Avalara Managed Returns to group documents together by reporting locations
for tax authorities that require location-based reporting. |
| `commit` | boolean | No | Causes the document to be committed if true.  This option is only applicable for invoice document
types, not orders. Example: `true`. |
| `batchCode` | string | No | BatchCode for batch operations. |
| `taxOverride` | TaxOverrideModel | No | Specifies a tax override for the entire document |
| `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`. |
| `serviceMode` | string | No | Specifies whether the tax calculation is handled Local, Remote, or Automatic (default).  This only
applies when using an AvaLocal server. Values: `Automatic`, `Local`, `Remote`. Example: `Automatic`. |
| `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. |
| `exchangeRateEffectiveDate` | string | No | Effective date of the exchange rate. |
| `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. |
| `posLaneCode` | string | No | Sets the Point of Sale Lane Code sent by the User for this document. |
| `businessIdentificationNo` | string | No | VAT business identification number for the customer for this transaction.  This number will be used for all lines
in the transaction, except for those lines where you have defined a different business identification number.
            
If you specify a VAT business identification number for the customer in this transaction and you have also set up
a business identification number for your company during company setup, this transaction will be treated as a
business-to-business transaction for VAT purposes and it will be calculated according to VAT tax rules. |
| `isSellerImporterOfRecord` | boolean | No | Specifies if the transaction should have value-added and cross-border taxes calculated with the seller as the importer of record.
            
Some taxes only apply if the seller is the importer of record for a product.  In cases where companies are working together to
ship products, there may be mutual agreement as to which company is the entity designated as importer of record.  The importer
of record will then be the company designated to pay taxes marked as being obligated to the importer of record.
            
Set this value to `true` to consider your company as the importer of record and collect these taxes.
            
This value may also be set at the Nexus level.  See `NexusModel` for more information. |
| `description` | string | No | User-supplied description for this transaction. Example: `Yarn`. |
| `email` | string | No | User-supplied email address relevant for this transaction. |
| `debugLevel` | string | No | If the user wishes to request additional debug information from this transaction, specify a level higher than `normal`. Values: `Normal`, `Diagnostic`. Example: `Normal`. |
| `customerSupplierName` | string | No | The name of the supplier / exporter / seller.
For sales doctype enter the name of your own company for which you are reporting.
For purchases doctype enter 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`. |

## Responses

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

### 200 Response: `MultiDocumentModel`

A MultiDocument transaction represents a sale or purchase that occurred between more than two companies.
            
A traditional transaction requires exactly two parties: a seller and a buyer.  MultiDocument transactions can
involve a marketplace of vendors, each of which contributes some portion of the final transaction.  Within
a MultiDocument transaction, each individual buyer and seller pair are matched up and converted to a separate
document.  This separation of documents allows each seller to file their taxes separately.

| Property | Type | Required | Description |
|---|---|---|---|
| `id` | integer | No | The unique ID number of this MultiDocument object. Example: `12`. |
| `accountId` | integer | No | The unique ID number of the AvaTax customer account that created this MultiDocument object. Example: `123456`. |
| `code` | string | No | The transaction code of the MultiDocument transaction.
            
All individual transactions within this MultiDocument object will have this code as a prefix. Example: `98602f3c-dfa4-4388-990a-26e8aca1e3b0`. |
| `type` | string | No | Indicates the type of MultiDocument transaction.  Common values are:
            
* SalesOrder - An estimate that is not permanently recorded
* SalesInvoice - An invoice that can be reported on a tax return
            
For more information about document types, see [DocumentType](https://developer.avalara.com/api-reference/avatax/rest/v2/models/enums/DocumentType/) Values: `SalesOrder`, `SalesInvoice`, `PurchaseOrder`, `PurchaseInvoice`, `ReturnOrder`, `ReturnInvoice`, `InventoryTransferOrder`, `InventoryTransferInvoice`, `ReverseChargeOrder`, `ReverseChargeInvoice`, `CustomsInvoice`, `CustomsOrder`, `InventoryTransferOutboundInvoice`, `InventoryTransferOutboundOrder`, `Any`. Example: `SalesOrder`. |
| `createdUserId` | integer | No | The user ID of the user who created this record. Example: `87954`. |
| `createdDate` | string | No | The date/time when this record was created. Example: `2026-07-02T00:00:00+00:00`. |
| `modifiedDate` | string | No | The date/time when this record was last modified. Example: `2026-07-02T00:00:00+00:00`. |
| `modifiedUserId` | integer | No | The user ID of the user who last modified this record. Example: `66783`. |
| `documents` | TransactionModel[] | No | A separate document will exist for each unique combination of buyer and seller in this MultiDocument transaction. |

## Example Request

```bash
curl -X POST "https://sandbox-rest.avatax.com/api/v2/transactions/multidocument" \
  -H "Authorization: Basic <credentials>" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
  "lines": [
    {
      "companyCode": "DEFAULT",
      "reportingLocationCode": "ReportLocation111",
      "number": "1",
      "quantity": 1,
      "amount": 100,
      "taxCode": "PS081282",
      "itemCode": "Y0001",
      "description": "Yarn"
    }
  ],
  "type": "SalesInvoice",
  "companyCode": "DEFAULT",
  "date": "2026-07-02",
  "customerCode": "ABC",
  "purchaseOrderNo": "2026-07-02-001",
  "addresses": {
    "singleLocation": {
      "line1": "2000 Main Street",
      "city": "Irvine",
      "region": "CA",
      "country": "US",
      "postalCode": "92614"
    }
  },
  "commit": true,
  "currencyCode": "USD",
  "description": "Yarn"
}'
```