Skip to main content

Create taxation items for invoices through API

Zuora

Create taxation items for invoices through API

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
ValuesPercentageFlatFee

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

csv_final2.png

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:

success2.png

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:

csv_final3.png

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:

  1. Unrecognized column name or required column is missing.

  2. The value of a field is incorrectly formatted or exceeds the maximum length.

  3. 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>