Create taxation items for invoices through API

Last updated
Save as PDF

This article describes how to use the REST API to create taxation items and how to use the SOAP API create call to import a CSV or zipped CSV file of mass taxation items to invoices.

Create taxation items via REST

You can create taxation items for invoices through Create taxation items for invoices. With this REST API, you can create multiple tax items for an invoice with one API call.

The create() call returns fail or success.

Examples

Post taxation items for invoices

Method: Post

Endpoint: v1/taxationitems/invoice/4028818585df3c6f0185e2f054da20eb

Request


{
 "taxationItems": [
   {
     "taxRate": 0.1,
     "taxCodeDescription": "taxCodeDescription",
     "jurisdiction": "Jurisdiction",
     "name": "taxNameExclusive",
     "financeInformation": {
       "accountsReceivableAccountingCode": "accountsReceivableAccountingCode",
       "salesTaxPayableAccountingCode": "salesTaxPayableAccountingCode"
     },
     "taxRateType": "Percentage",
     "locationCode": "8",
     "taxCode": "ExclusiveTaxCode",
     "taxRateDescription": "taxRateDescription",
     "taxAmount": 10,
     "taxDate": "2016-10-10",
     "invoiceItemId": "4028818585df3c6f0185e2d060951eed"
   },
   {
     "jurisdiction": "Jurisdiction",
     "taxRateType": "Percentage",
     "taxCode": "InclusiveTaxCode",
     "taxRateDescription": "taxRateDescription",
     "taxDate": "2016-10-10",
     "invoiceItemId": "4028818585df3c6f0185e2d060951eed",
     "taxRate": 0.1,
     "taxCodeDescription": "taxCodeDescription",
     "taxMode": "TaxInclusive",
     "name": "taxNameInclusive",
     "financeInformation": {
       "accountsReceivableAccountingCode": "accountsReceivableAccountingCode",
       "salesTaxPayableAccountingCode": "salesTaxPayableAccountingCode"
     },
     "locationCode": "8",
     "taxAmount": 10
   },
   {
     "jurisdiction": "Jurisdiction",
     "taxRateType": "Percentage",
     "taxCode": "ExclusiveTaxCode",
     "taxRateDescription": "taxRateDescription",
     "taxDate": "2016-10-10",
     "invoiceItemId": "4028818585df3c6f0185e2d060961eee",
     "taxRate": 0.1,
     "taxCodeDescription": "taxCodeDescription",
     "taxMode": "TaxExclusive",
     "name": "taxNameExclusive",
     "financeInformation": {
       "accountsReceivableAccountingCode": "accountsReceivableAccountingCode",
       "salesTaxPayableAccountingCode": "salesTaxPayableAccountingCode"
     },
     "locationCode": "8",
     "taxAmount": 10
   },
   {
     "jurisdiction": "Jurisdiction",
     "taxRateType": "Percentage",
     "taxCode": "InclusiveTaxCode",
     "taxRateDescription": "taxRateDescription",
     "taxDate": "2016-10-10",
     "invoiceItemId": "4028818585df3c6f0185e2d060961eee",
     "taxRate": 0.1,
     "taxCodeDescription": "taxCodeDescription",
     "taxMode": "TaxInclusive",
     "name": "taxNameInclusive",
     "financeInformation": {
       "accountsReceivableAccountingCode": "accountsReceivableAccountingCode",
       "salesTaxPayableAccountingCode": "salesTaxPayableAccountingCode"
     },
     "locationCode": "8",
     "taxAmount": 10
   }
 ]
}

Response


{
 "taxationItems": [
   {
     "createdById": "9d83889504e74eefa936832193197e27",
     "createdDate": "2023-01-24 13:37:25",
     "exemptAmount": 0,
     "id": "4028818585df3c6f0185e2d14b031eff",
     "invoiceItemId": "4028818585df3c6f0185e2d060951eed",
     "jurisdiction": "Jurisdiction",
     "locationCode": "8",
     "name": "taxNameExclusive",
     "taxAmount": 10,
     "taxCode": "ExclusiveTaxCode",
     "taxMode": "TaxExclusive",
     "taxCodeDescription": "taxCodeDescription",
     "taxDate": "2016-10-10",
     "taxRate": 0.1,
     "taxRateDescription": "taxRateDescription",
     "taxRateType": "Percentage",
     "updatedById": "9d83889504e74eefa936832193197e27",
     "updatedDate": "2023-01-24 13:37:25",
     "financeInformation": {
       "onAccountAccountingCode": null,
       "onAccountAccountingCodeType": null,
       "salesTaxPayableAccountingCode": "salesTaxPayableAccountingCode",
       "salesTaxPayableAccountingCodeType": "SalesTaxPayable",
       "accountsReceivableAccountingCode": "accountsReceivableAccountingCode",
       "accountsReceivableAccountingCodeType": "AccountsReceivable"
     }
   },
   {
     "createdById": "9d83889504e74eefa936832193197e27",
     "createdDate": "2023-01-24 13:37:25",
     "exemptAmount": 0,
     "id": "4028818585df3c6f0185e2d14b031f00",
     "invoiceItemId": "4028818585df3c6f0185e2d060951eed",
     "jurisdiction": "Jurisdiction",
     "locationCode": "8",
     "name": "taxNameInclusive",
     "taxAmount": 10,
     "taxCode": "InclusiveTaxCode",
     "taxMode": "TaxInclusive",
     "taxCodeDescription": "taxCodeDescription",
     "taxDate": "2016-10-10",
     "taxRate": 0.1,
     "taxRateDescription": "taxRateDescription",
     "taxRateType": "Percentage",
     "updatedById": "9d83889504e74eefa936832193197e27",
     "updatedDate": "2023-01-24 13:37:25",
     "financeInformation": {
       "onAccountAccountingCode": null,
       "onAccountAccountingCodeType": null,
       "salesTaxPayableAccountingCode": "salesTaxPayableAccountingCode",
       "salesTaxPayableAccountingCodeType": "SalesTaxPayable",
       "accountsReceivableAccountingCode": "accountsReceivableAccountingCode",
       "accountsReceivableAccountingCodeType": "AccountsReceivable"
     }
   },
   {
     "createdById": "9d83889504e74eefa936832193197e27",
     "createdDate": "2023-01-24 13:37:25",
     "exemptAmount": 0,
     "id": "4028818585df3c6f0185e2d14b041f01",
     "invoiceItemId": "4028818585df3c6f0185e2d060961eee",
     "jurisdiction": "Jurisdiction",
     "locationCode": "8",
     "name": "taxNameExclusive",
     "taxAmount": 10,
     "taxCode": "ExclusiveTaxCode",
     "taxMode": "TaxExclusive",
     "taxCodeDescription": "taxCodeDescription",
     "taxDate": "2016-10-10",
     "taxRate": 0.1,
     "taxRateDescription": "taxRateDescription",
     "taxRateType": "Percentage",
     "updatedById": "9d83889504e74eefa936832193197e27",
     "updatedDate": "2023-01-24 13:37:25",
     "financeInformation": {
       "onAccountAccountingCode": null,
       "onAccountAccountingCodeType": null,
       "salesTaxPayableAccountingCode": "salesTaxPayableAccountingCode",
       "salesTaxPayableAccountingCodeType": "SalesTaxPayable",
       "accountsReceivableAccountingCode": "accountsReceivableAccountingCode",
       "accountsReceivableAccountingCodeType": "AccountsReceivable"
     }
   },
   {
     "createdById": "9d83889504e74eefa936832193197e27",
     "createdDate": "2023-01-24 13:37:25",
     "exemptAmount": 0,
     "id": "4028818585df3c6f0185e2d14b041f02",
     "invoiceItemId": "4028818585df3c6f0185e2d060961eee",
     "jurisdiction": "Jurisdiction",
     "locationCode": "8",
     "name": "taxNameInclusive",
     "taxAmount": 10,
     "taxCode": "InclusiveTaxCode",
     "taxMode": "TaxInclusive",
     "taxCodeDescription": "taxCodeDescription",
     "taxDate": "2016-10-10",
     "taxRate": 0.1,
     "taxRateDescription": "taxRateDescription",
     "taxRateType": "Percentage",
     "updatedById": "9d83889504e74eefa936832193197e27",
     "updatedDate": "2023-01-24 13:37:25",
     "financeInformation": {
       "onAccountAccountingCode": null,
       "onAccountAccountingCodeType": null,
       "salesTaxPayableAccountingCode": "salesTaxPayableAccountingCode",
       "salesTaxPayableAccountingCodeType": "SalesTaxPayable",
       "accountsReceivableAccountingCode": "accountsReceivableAccountingCode",
       "accountsReceivableAccountingCodeType": "AccountsReceivable"
     }
   }
 ],
 "success": true
}

Update taxation items for invoices

Method: Put

Endpoint: /v1/taxationitems/4028818585df3c6f0185e2f5ea072100

Request


{
 "name": "TAX NAME UPDATED",
 "financeInformation": {
   "accountsReceivableAccountingCode": "accountsReceivableAccountingCode",
   "salesTaxPayableAccountingCode": "salesTaxPayableAccountingCode"
 },
 "taxCode": "ExclusiveTaxCode UPDATED",
 "taxAmount": 20
}

Response


{
   "createdById": "3ac2e5db41994fa0b04aaec918443701",
   "createdDate": "2023-01-24 14:17:24",
   "exemptAmount": 0.000000000,
   "id": "4028818585df3c6f0185e2f5ea072100",
   "memoItemId": null,
   "invoiceItemId": "4028818585df3c6f0185e2f0550220ec",
   "sourceTaxItemId": null,
   "jurisdiction": "Jurisdiction",
   "locationCode": "8",
   "name": "TAX NAME UPDATED",
   "taxAmount": 20.00,
   "taxCode": "ExclusiveTaxCode UPDATED",
   "taxCodeDescription": "taxCodeDescription",
   "taxDate": "2016-10-10",
   "taxRate": 0.100000000,
   "taxMode": "TaxExclusive",
   "taxRateDescription": "taxRateDescription",
   "taxRateType": "Percentage",
   "updatedById": "3ac2e5db41994fa0b04aaec918443701",
   "updatedDate": "2023-01-24 14:32:06",
   "financeInformation": {
       "onAccountAccountingCode": null,
       "onAccountAccountingCodeType": null,
       "salesTaxPayableAccountingCode": "salesTaxPayableAccountingCode",
       "salesTaxPayableAccountingCodeType": "SalesTaxPayable",
       "accountsReceivableAccountingCode": "accountsReceivableAccountingCode",
       "accountsReceivableAccountingCodeType": "AccountsReceivable"
   },
   "success": true
}

Delete taxation items for invoices

Method: Delete

Endpoint: v1/taxationitems/4028818585df3c6f0185e2f5ea072100

Response

{
   "success": true
}

Retrieve taxation items for invoices

Method: Get

Endpoint: v1/taxationitems/4028818585df3c6f0185e2f5ea082101

Response


{
   "createdById": "3ac2e5db41994fa0b04aaec918443701",
   "createdDate": "2023-01-24 14:17:25",
   "exemptAmount": 0.000000000,
   "id": "4028818585df3c6f0185e2f5ea082101",
   "memoItemId": null,
   "invoiceItemId": "4028818585df3c6f0185e2f0550220ec",
   "sourceTaxItemId": null,
   "jurisdiction": "Jurisdiction",
   "locationCode": "8",
   "name": "taxNameInclusive",
   "taxAmount": 10.000000000,
   "taxCode": "InclusiveTaxCode",
   "taxCodeDescription": "taxCodeDescription",
   "taxDate": "2016-10-10",
   "taxRate": 0.100000000,
   "taxMode": "TaxInclusive",
   "taxRateDescription": "taxRateDescription",
   "taxRateType": "Percentage",
   "updatedById": "3ac2e5db41994fa0b04aaec918443701",
   "updatedDate": "2023-01-24 14:17:25",
   "financeInformation": {
       "onAccountAccountingCode": null,
       "onAccountAccountingCodeType": null,
       "salesTaxPayableAccountingCode": "salesTaxPayableAccountingCode",
       "salesTaxPayableAccountingCodeType": "SalesTaxPayable",
       "accountsReceivableAccountingCode": "accountsReceivableAccountingCode",
       "accountsReceivableAccountingCodeType": "AccountsReceivable"
   },
   "success": true
}
{
   "createdById": "3ac2e5db41994fa0b04aaec918443701",
   "createdDate": "2023-01-24 14:17:25",
   "exemptAmount": 0.000000000,
   "id": "4028818585df3c6f0185e2f5ea082101",
   "memoItemId": null,
   "invoiceItemId": "4028818585df3c6f0185e2f0550220ec",
   "sourceTaxItemId": null,
   "jurisdiction": "Jurisdiction",
   "locationCode": "8",
   "name": "taxNameInclusive",
   "taxAmount": 10.000000000,
   "taxCode": "InclusiveTaxCode",
   "taxCodeDescription": "taxCodeDescription",
   "taxDate": "2016-10-10",
   "taxRate": 0.100000000,
   "taxMode": "TaxInclusive",
   "taxRateDescription": "taxRateDescription",
   "taxRateType": "Percentage",
   "updatedById": "3ac2e5db41994fa0b04aaec918443701",
   "updatedDate": "2023-01-24 14:17:25",
   "financeInformation": {
       "onAccountAccountingCode": null,
       "onAccountAccountingCodeType": null,
       "salesTaxPayableAccountingCode": "salesTaxPayableAccountingCode",
       "salesTaxPayableAccountingCodeType": "SalesTaxPayable",
       "accountsReceivableAccountingCode": "accountsReceivableAccountingCode",
       "accountsReceivableAccountingCodeType": "AccountsReceivable"
   },
   "success": true
}

Mass upload of taxation items via SOAP

Using Create call to import taxation items

Mass upload of taxation items does not prevent duplicate taxation items from being created. Taxation items will be duplicated if you upload them more than once.

The create() call lets you upload a file to support mass taxation items. The mass taxation items file is a CSV formatted file or a zipped CSV formatted file sent via Message Transmission Optimization Mechanism (MTOM). The upload and parsing of the CSV file is an asynchronous operation.

The create() call returns fail or success. On success, an Import ID is returned. You can use the Import ID to query the import process and to query the Parse status.

CSV file format

A maximum file size of 1MB is supported for CSV and CSV zipped files.

Table of fields for upload of mass taxation items CSV files:

Field Name	Column Required?	Value Required?	Description
InvoiceItemId	Required	Required	The ID of the specific invoice item that the taxation information applies to. Type: string Character limit: 32 Values: a valid invoice item ID
Name	Required	Required	The name of the tax rate, such as sales tax or GST. This name is displayed on invoices. Type: string Character limit: 128 Values: a string of 128 characters or fewer
TaxCode	Required	Optional	The tax code identifies which tax rules and tax rates to apply to a specific charge. Type: string Character limit: 32 Values: a string of 32 characters or fewer
TaxCodeDescription	Required	Optional	The description for the tax code. Type: string Character limit: 255 Values: a string of 255 characters or fewer
TaxRate	Required	Required	The tax rate applied to the charge. Type: decimal Character limit: 16 Values: a valid decimal value
TaxRateDescription	Required	Optional	The description of the tax rate. Type: string Character limit: 255 Values: a string of 255 characters or fewer
TaxRateType	Required	Required	The type of the tax rate applied to the charge. Type: string (enum) Character limit: 10 Values: `Percentage`, `FlatFee`
TaxAmount	Required	Required	The amount of the tax applied to the charge. Type: decimal (currency) Character limit: 16 Values: a decimal value
ExemptAmount	Required	Required	The calculated tax amount excluded due to the exemption. Type: decimal (currency) Character limit: 16 Values: a decimal value
Jurisdiction	Required	Optional	The jurisdiction that applies the tax or VAT. This value is typically a state, province, county, or city. Type: string Character limit: 32 Values: a string of 32 characterrs or fewer
LocationCode	Required	Optional	The identifier for the location based on the value of the `TaxCode` field. Type: string Character limit: 32 Values: automatically generated
TaxDate	Required	Required	The date that the tax is applied to the charge. Type: date Character limit: 29 Values: a valid date formatted MM/dd/yyyy
TaxMode	Required*	Required	The type of tax mode for the account. Type: string (enum) Character limit: 32 Values: `TaxExclusive`, `TaxInclusive`
AccountingCode	Optional	Optional	The accounting code for the taxation item. Accounting codes group transactions that contain similar accounting attributes. Type: string Character limit: 32 Values: an active accounting code in your Zuora Chart of Accounts

Example CSV

Supported parameters for the create call

Parameter	Required?	Description
FileContent	Required	The file containing mass tax items
ImportType	Required	The type of file imported
Md5	Optional	A check to validate file integrity
Name	Optional	A descriptive name for the import

Notifications

After completion of the upload and parse operation, an email will be sent on either success or failure. On success, the email will contain a Total Count (the total number of items processed), a link to the resulting CSV file, and an Import ID. The linked file will be a CSV formatted file containing the taxation IDs in the first column. The data from the original input will begin from the second column as you can see in the following image:

On failure of the parse operation, an email will be sent with a failure message and a link to the resulting CSV file. The success of the parse operation is dependent on every record being valid. One invalid record will result in the failure of the parse operation. The linked file will contain a CSV file containing the original input file contents and a new column added in rightmost position including a failure message or messages if there are multiple invalid records. The message will contain information regarding the specific invalid records that caused the failure. Refer to these messages to find and fix the invalid record. Here is an example of a failure message:

Returned error messages

An error in a single item of the uploaded CSV file will result in a failure of the parse operation. There are three possible cases in which a failure will occur and return an error message:

Unrecognized column name or required column is missing.
The value of a field is incorrectly formatted or exceeds the maximum length.
Any exception occurs during the import process.

Message	Related Field
`The TaxMode does not match the tax mode on the invoice item.`	TaxMode
`The magnitude of the tax amount cannot exceed that of the invoice item amount.`	TaxAmount/ExemptAmount
`This customer account is subjected to taxes.` The ExemptAmount field must be $0.	ExemptAmount
`Tax Mode must be 'TaxExclusive' or 'TaxInclusive'.`	TaxMode
`Invoice Detail Id is invalid.`	InvoiceItemId
`Invoice is not Draft status or has been modified.` Taxation can not be applied on this invoice.	InvoiceItemId
`Tax Amount should not be negative.`	TaxAmount
`Tax Amount should not be positive.`	TaxAmount
`The invoice item using inclusive tax don't support to add new taxation item without explicitly tax mode information.`	InvoiceItemId/TaxMode
`The LocationCode field should be less than 32 characters.`	LocationCode
`The Tax Name field should be less than 128 characters.`	Name
`The Tax Rate Description should be less than 255 characters.`	TaxRate
`The Tax Code field should be less than 32 characters.`	TaxCode
`The Jurisdiction field should be less than 32 characters.`	Jurisdiction
`The Tax Code Description field should be less than 255 characters.`	TaxCodeDescription
`Tax Name is required.`	Name
`Tax Rate Type must be 'Percentage' or 'FlatFee'.`	TaxRateType
`Tax Rate must be a number not less than 0.`	TaxRate
`Tax Amount must be a number.`	TaxAmount
`Exempt Amount must be number.`	ExemptAmount
`Tax Date should be in format 'MM/dd/yyyy'.`	TaxDate

Sample code

This sample code is a simple example for uploading mass tax items. It shows the request body and example replies on success and failure.

Request:

   <soapenv:Body>
       <ns1:create
           xmlns:ns1="http://api.zuora.com/">
           <ns1:zObjects
               xmlns:ns2="http://object.api.zuora.com/"
               xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="ns2:Import">
               <ns2:FileContent>cid:taxation.csv
                       </ns2:FileContent>
               <ns2:ImportType>TaxationDetail</ns2:ImportType>
               <ns2:Name>taxation.csv</ns2:Name>
           </ns1:zObjects>
       </ns1:create>
   </soapenv:Body>

Response:

Success

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
  <soapenv:Body>
     <ns1:createResponse xmlns:ns1="http://api.zuora.com/">
        <ns1:result>
           <ns1:Id>4028901c4974cccf014974d24e150003</ns1:Id>
           <ns1:Success>true</ns1:Success>
        </ns1:result>
     </ns1:createResponse>
  </soapenv:Body>
</soapenv:Envelope>

Failure

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
  <soapenv:Body>
     <ns1:createResponse xmlns:ns1="http://api.zuora.com/">
        <ns1:result>
           <ns1:Errors>
              <ns1:Code>INVALID_VALUE</ns1:Code>
              <ns1:Message>Failure Message</ns1:Message>
           </ns1:Errors>
           <ns1:Success>false</ns1:Success>
        </ns1:result>
     </ns1:createResponse>
  </soapenv:Body>
</soapenv:Envelope>