Tax Control Account
A tax control account is an account to which the amounts computed for indirect taxes, such as sales tax and VAT, are posted.
The tax control account is defined in the listAcct (accounting) XSD, where it is called taxAcct.
In the UI, you can create a tax control account, and view existing ones, at Setup > Accounting > Tax Control Accounts. Note also that a tax control account is essentially an account record, with a few differences. Because they are accounts, tax control accounts also show up in the full list of accounts at Lists > Accounting > Accounts.
For more information, see Creating a Tax Control Account.
Supported Operations
The following operations can be used with the tax control account record.
add | addList | get | getList | update | updateList | upsert | upsertList
You can also use the asynchronous equivalents of SOAP web services list operations. For information about asynchronous operations, see SOAP Web Services Asynchronous Operations. For more information about request processing, see Synchronous Versus Asynchronous Request Processing.
Updating
The update operation is permitted, but you can update only certain fields: Description, External ID, IsInactive, and Name. However, you may be able to change other fields when interacting with the tax control account as an account. For details, see Account.
Alternatives to Deleting
The delete operation is not permitted, because a tax control account cannot be deleted (either through the UI or through SOAP web services). If the Advanced Taxes feature is enabled, you can effectively remove the tax control account by deleting the nexus that the account is associated with. If the Advanced Taxes feature is not enabled, you cannot remove the account.
An alternative to deleting the account is to make it account inactive, by setting the IsInactive field to true.
For more details on accounts that cannot be deleted in NetSuite, refer to the help topic Deleting Accounts and Making Accounts Inactive.
Field Definitions
This section describes some of the key fields on the tax control account.
Country
The value for country is derived from the nexus value and is read-only. Note that, if your account does not have the Advanced Taxes feature enabled, the value for country will always be the same for all your tax control accounts.
Description
The description of the record can include only up to 50 characters. Otherwise, the operation fails with an error reading “The field description contained more than the maximum number ( 50 ) of characters allowed.” Description is one of the few fields that can be modified during an update.
Description is one of the few fields that can be modified during an update.
External ID
ExternalID is one of the few fields that can be modified during an update.
IsInactive
Because a tax control account cannot be deleted, you might want to make it inactive.
IsInactive is one of the few fields that can be modified during an update.
Name
The name of the record must be unique. If you try to add a tax control account using a non-unique value for the name field, the system returns an error reading “This record already exists,” even if you included a unique external ID.
Name is one of the few fields that can be modified during an update.
Nexus
You can set a value for nexus only if the Advanced Taxes feaure is enabled. If your NetSuite account does not use the Advanced Taxes feature, the value for nexus is set automatically and will always be the same for all your tax control accounts.
When Advanced Taxes is enabled, referencing a nexus value is required. However, after the account is created, the value for nexus cannot be changed.
Note that Advanced Taxes is enabled in all OneWorld accounts and cannot be turned off.
Tax Account Type
All tax control accounts have a tax account type, but you only actively choose a tax account type for accounts in certain countries. For example:
-
When you are creating a tax code for an account in the United Kingdom, valid choices include _sale and _purchase. These two choices are elements of type accountingTypes: TaxAcctType.
-
When creating a tax code for an account in the United States, only one option exists (_sale), so you do not set a value for this field.
In countries where both _sale and _purchase are valid choices, the tax account type field is required. Further, after an account has been created, the tax account type cannot be changed.
In countries where only one choice is allowed, tax account type is automatically set, and you cannot change it through SOAP web services (or through the UI).
Note that if your account uses Advanced Taxes and has nexuses in many countries, you may need to set this field for some tax control accounts and not others.
For More Information
The SOAP Schema Browser includes definitions for all body fields, sublist fields, search filters, and search joins available to this record. For details, see the SOAP Schema Browser’s tax account reference page.
Usage Notes
This section includes additional details on interacting with the tax record.
Finding the Internal ID
If you need the internal ID for an existing tax control account, note that you cannot find it through Setup > Accounting > Tax Control Accounts. However, you can find it at Lists > Accounting > Accounts. Make sure you have configured your NetSuite preference to “Show Internal IDs.” (You can find this choice at Home > Set Preferences.)
When sorting accounts at Lists > Accounting > Accounts, be aware that:
-
Tax control accounts of type “_sale” show up as Other Current Liability.
-
Tax control accounts of type “_purchase” show up as Other Curret Asset.
Be aware that you can also add and update values for the external ID field.
Relationship to the Account Record
You can interact with the tax control account in many of the same ways you can interact with any account. However, some exceptions exist. For example, a tax control account cannot be deleted, and there are limits to what you can update, as described in Updating. However, when you interact with the record as an account, you may be able to update additional fields.
For details on interacting with the account record, see Account.
Code Samples
Refer to the following examples for help interacting with the tax control account record.
Creating a Record Example
The following example shows how to create a tax control account when the Advanced Taxes feature is enabled.
Java
public void testAddTaxAccount() throws Exception
{
c.useRequestLevelCredentials();
TaxAcct taxAcct = new TaxAcct();
RecordRef nexusRef = new RecordRef();
nexusRef.setType(RecordType.nexus);
nexusRef.setInternalId("6");
taxAcct.setNexus(nexusRef);
taxAcct.setName("WS Added TaxAcct");
taxAcct.setDescription("WS Added Testing Tax Control Account");
taxAcct.setTaxAcctType(TaxAcctType._purchase);
taxAcct.setExternalId("WSTaxAcct1234567890");
c.addRecord(taxAcct);
}
SOAP Request
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<soapenv:Header>
<ns1:passport soapenv:actor="http://schemas.xmlsoap.org/soap/actor/next" soapenv:mustUnderstand="0" xmlns:ns1="urn:messages_2017_1.platform.webservices.netsuite.com">
<ns2:email xmlns:ns2="urn:core_2017_1.platform.webservices.netsuite.com">johnsmith@netsuite.com</ns2:email>
<ns3:password xmlns:ns3="urn:core_2017_1.platform.webservices.netsuite.com">welcome</ns3:password>
<ns4:account xmlns:ns4="urn:core_2017_1.platform.webservices.netsuite.com">1326288</ns4:account>
<ns5:role internalId="37" xmlns:ns5="urn:core_2017_1.platform.webservices.netsuite.com"/>
</ns1:passport>
</soapenv:Header>
<soapenv:Body>
<add xmlns="urn:messages_2017_1.platform.webservices.netsuite.com">
<record externalId="WSTaxAcct1234567890" xsi:type="ns6:TaxAcct" xmlns:ns6="urn:accounting_2017_1.lists.webservices.netsuite.com">
<ns6:name xsi:type="xsd:string">WS Added TaxAcct</ns6:name>
<ns6:description xsi:type="xsd:string">WS Added Testing Tax Control Account</ns6:description>
<ns6:nexus internalId="6" type="nexus" xsi:type="ns7:RecordRef" xmlns:ns7="urn:core_2017_1.platform.webservices.netsuite.com"/>
<ns6:taxAcctType xsi:type="ns8:TaxAcctType" xmlns:ns8="urn:types.accounting_2017_1.lists.webservices.netsuite.com">_purchase</ns6:taxAcctType>
</record>
</add>
</soapenv:Body>
</soapenv:Envelope>
SOAP Response
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<soapenv:Header>
<platformMsgs:documentInfo xmlns:platformMsgs="urn:messages_2017_1.platform.webservices.netsuite.com">
<platformMsgs:nsId>WEBSERVICES_1326288_042520131100061755935117479_6033b31321c2</platformMsgs:nsId>
</platformMsgs:documentInfo>
</soapenv:Header>
<soapenv:Body>
<addResponse xmlns="urn:messages_2017_1.platform.webservices.netsuite.com">
<writeResponse>
<platformCore:status isSuccess="true" xmlns:platformCore="urn:core_2017_1.platform.webservices.netsuite.com"/>
<baseRef internalId="286" externalId="WSTaxAcct1234567890" type="taxAcct" xsi:type="platformCore:RecordRef" xmlns:platformCore="urn:core_2017_1.platform.webservices.netsuite.com"/>
</writeResponse>
</addResponse>
</soapenv:Body>
</soapenv:Envelope>
Updating a Record Example
The following example shows how to modify a tax control account. Note that the only fields which can be updated are Name, Description, and IsInactive.
Java
public void testUpdateTaxAccount() throws Exception
{
c.useRequestLevelCredentials();
Record taxAcctRec = c.getRecord("186", RecordType.taxAcct);
TaxAcct taxAcct = (TaxAcct) taxAcctRec;
taxAcct.setName("WS Updated TaxAcct nr 4");
taxAcct.setDescription("WS Updated Testing Tax Control Account number 4");
taxAcct.setExternalId("WSTaxAcct004");
taxAcct.setIsInactive(true);
c.updateRecord(taxAcct);
}
SOAP Request
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<soapenv:Header>
<ns1:passport soapenv:actor="http://schemas.xmlsoap.org/soap/actor/next" soapenv:mustUnderstand="0" xmlns:ns1="urn:messages_2017_1.platform.webservices.netsuite.com">
<ns2:email xmlns:ns2="urn:core_2017_1.platform.webservices.netsuite.com">johnsmith@netsuite.com</ns2:email>
<ns3:password xmlns:ns3="urn:core_2017_1.platform.webservices.netsuite.com">welcome</ns3:password>
<ns4:account xmlns:ns4="urn:core_2017_1.platform.webservices.netsuite.com">1326288</ns4:account>
<ns5:role internalId="37" xmlns:ns5="urn:core_2017_1.platform.webservices.netsuite.com"/>
</ns1:passport>
</soapenv:Header>
<soapenv:Body>
<update xmlns="urn:messages_2017_1.platform.webservices.netsuite.com">
<record externalId="WSTaxAcct004" internalId="186" xsi:type="ns6:TaxAcct" xmlns:ns6="urn:accounting_2017_1.lists.webservices.netsuite.com">
<ns6:name xsi:type="xsd:string">WS Updated TaxAcct nr 4</ns6:name>
<ns6:description xsi:type="xsd:string">WS Updated Testing Tax Control Account number 4</ns6:description>
<ns6:nexus internalId="1" xsi:type="ns7:RecordRef" xmlns:ns7="urn:core_2017_1.platform.webservices.netsuite.com"/>
<ns6:country xsi:type="ns8:Country" xmlns:ns8="urn:types.common_2017_1.platform.webservices.netsuite.com">_unitedStates</ns6:country>
<ns6:taxAcctType xsi:type="ns9:TaxAcctType" xmlns:ns9="urn:types.accounting_2017_1.lists.webservices.netsuite.com">_sale</ns6:taxAcctType>
<ns6:isInactive xsi:type="xsd:boolean">true</ns6:isInactive>
</record>
</update>
</soapenv:Body>
</soapenv:Envelope>
SOAP Response
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<soapenv:Header>
<platformMsgs:documentInfo xmlns:platformMsgs="urn:messages_2017_1.platform.webservices.netsuite.com">
<platformMsgs:nsId>WEBSERVICES_1326288_042520131118845977808995829_ea95975e7048</platformMsgs:nsId>
</platformMsgs:documentInfo>
</soapenv:Header>
<soapenv:Body>
<updateResponse xmlns="urn:messages_2017_1.platform.webservices.netsuite.com">
<writeResponse>
<platformCore:status isSuccess="true" xmlns:platformCore="urn:core_2017_1.platform.webservices.netsuite.com"/>
<baseRef internalId="186" externalId="WSTaxAcct004" type="taxAcct" xsi:type="platformCore:RecordRef" xmlns:platformCore="urn:core_2017_1.platform.webservices.netsuite.com"/>
</writeResponse>
</updateResponse>
</soapenv:Body>
</soapenv:Envelope>
Getting a Record Example
The following example shows how to get a tax control account record.
Java
//Getting existing Tax Control Account
public void testGetTaxAccount() throws Exception
{
c.useRequestLevelCredentials();
RecordRef acct = new RecordRef();
acct.setType(RecordType.taxAcct);
acct.setExternalId("nove");
c.getPort().get(acct);
}
SOAP Request
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<soapenv:Header>
<ns1:passport soapenv:actor="http://schemas.xmlsoap.org/soap/actor/next" soapenv:mustUnderstand="0" xmlns:ns1="urn:messages_2017_1.platform.webservices.netsuite.com">
<ns2:email xmlns:ns2="urn:core_2017_1.platform.webservices.netsuite.com">nlbuild@netsuite.com</ns2:email>
<ns3:password xmlns:ns3="urn:core_2017_1.platform.webservices.netsuite.com">********</ns3:password>
<ns4:account xmlns:ns4="urn:core_2017_1.platform.webservices.netsuite.com">3604360</ns4:account>
<ns5:role internalId="37" xmlns:ns5="urn:core_2017_1.platform.webservices.netsuite.com"/>
</ns1:passport>
</soapenv:Header>
<soapenv:Body>
<get xmlns="urn:messages_2017_1.platform.webservices.netsuite.com">
<baseRef externalId="nove" type="taxAcct" xsi:type="ns6:RecordRef" xmlns:ns6="urn:core_2017_1.platform.webservices.netsuite.com"/>
</get>
</soapenv:Body>
</soapenv:Envelope
SOAP Response
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<soapenv:Header>
<platformMsgs:documentInfo xmlns:platformMsgs="urn:messages_2017_1.platform.webservices.netsuite.com">
<platformMsgs:nsId>WEBSERVICES_1326288_042520131118845977808995829_ea95975e7048</platformMsgs:nsId>
</platformMsgs:documentInfo>
</soapenv:Header>
<soapenv:Body>
<updateResponse xmlns="urn:messages_2017_1.platform.webservices.netsuite.com">
<writeResponse>
<platformCore:status isSuccess="true" xmlns:platformCore="urn:core_2017_1.platform.webservices.netsuite.com"/>
<baseRef internalId="186" externalId="WSTaxAcct004" type="taxAcct" xsi:type="platformCore:RecordRef" xmlns:platformCore="urn:core_2017_1.platform.webservices.netsuite.com"/>
</writeResponse>
</updateResponse>
</soapenv:Body>
</soapenv:Envelope>