Creating Tax Suppliers

About Tax Suppliers

A tax supplier is a company or corporate division responsible for collecting taxes for a transaction. Tax suppliers typically include your corporate headquarters and branch offices. Vertex uses the tax supplier to calculate taxes.

Tax supplier data can include the following information:

The name of the tax supplier.
The address to use as the ship-from locale.
The tax nexus state. You can have a tax nexus in any state where your company has a substantial presence, as defined by federal tax laws.
The VAT certificate number.

Tax software typically calculates taxes by using four locales:

Shipped-to: The address of the customer who made the purchase. BRM obtains the shipped-to address from the customer's account. For telecommunications taxation, this is the termination number.

Note:

You can configure BRM to use a customer's real-time location as the shipped-to address. This option applies to third-party client applications only. See "Overriding Shipped-To with the Real-Time Location".
Shipped-from: The address of the company supplying the product. For telecommunications taxation, this is the origination number.
Bill origin: The location from which the product was shipped (also called point of origin); for example, a warehouse. This is not used for telecommunications taxation.
Bill approval: The location where the order for the product was taken (also called point of acceptance); for example, the location of a customer service representative who creates accounts. For telecommunications taxation, this is the charge-to number.

For sales and use taxes, BRM does not differentiate between ship from, bill origin, and bill approval. Therefore, when providing the tax software with data, BRM uses the same value for all three locales. This value is derived from the tax supplier's address. For telecommunications taxation, the numbers are derived from call details records (CDRs).

Note:

For telecommunications taxation, the shipped-to, bill origin, and bill approval locales are not used and are therefore stored in BRM with a NULL value.

You specify how to supply tax supplier data to your tax software in one of the following ways:

Provide the tax supplier data with each transaction that you send to the tax software. For example, each transaction might include the ship-from locale based on the tax supplier address and the applicable VAT certificate. See "Providing the Tax Supplier Data with Each Transaction" for more information.
Allow the tax software to determine the correct tax supplier based on the transaction data plus the company and business locations you give the tax software. You provide information to the tax software by running the tax software's toolkits. The tax software then determines which ship-from locale to use, if there is a tax nexus presence, and which VAT certificate to use. See "Allowing Your Sales and Use Tax Software to Determine Tax Supplier Data" for more information.

You can also configure a default ship-from address in case BRM cannot find any tax supplier. See "Defining a Default Ship-From Locale".

Providing the Tax Supplier Data with Each Transaction

If your business uses only one tax supplier, you can define a default tax supplier to use for all charge offers. You do not need to enter any tax supplier information when creating charge offers.

You can specify multiple tax suppliers. Use PDC or Pricing Center to assign each charge offer to a tax supplier. When an event is rated, the tax supplier defined in the charge offer is sent to the tax software.

For example, if you have different charge offers for different states, you can indicate the state where the offer was sold by selecting the tax supplier for that state.

To use this method of defining tax suppliers, you edit the BRM_home/sys/data/config/pin_tax_supplier.xml file. You load tax suppliers into the database by running the load_tax_supplier utility.

You cannot add or change tax suppliers individually. Each time you run load_tax_supplier, you overwrite existing data with the entire contents of the pin_tax_supplier.xml file. To modify or remove existing tax suppliers, edit or remove their information in the file before loading it.

By default, the pin_tax_supplier.xml file is located in BRM_home/sys/data/config.

Add a TaxSupplierElement child element to the TaxSupplierConfiguration parent element for each tax supplier.

A TaxSupplierElement looks like this:

  <TaxSupplierElement>
     <Name>supplier_name</Name>
     <Description>supplier_description</Description>
     <Address>supplier_address</Address>
     <NexusInfo>nexus_values</NexusInfo>
     <RegulatedFlag>flag_value</RegulatedFlag>
     <DefaultFlag>flag_value</DefaultFlag>
     <VATInfo>
        <CanonCountry>country_code</CanonCountry>
        <VATCertificate>certificate_number</VATCertificate>
     </VATInfo>
  </TaxSupplierElement>

Table 4-1 describes the pin_tax_supplier.xml file.

Table 4-1 pin_tax_supplier.xml File

Entry	Description
Name	Enter the tax supplier name. This name is the company ID in the tax_supplier_map file. For Vertex, this name is the company ID in the TDM or company file. If you use the TDM, the entry will be a four-character code. The name must match exactly.
Description	Enter a description for the tax supplier.
Address	Enter the address of the tax supplier. Use the following format: `city`;`state`;`zip_code`;`country`
NexusInfo	Enter a semicolon-delimited list of states where the tax supplier has a tax nexus. If you use Vertex taxation software, enter an asterisk (*) to allow Vertex to determine the tax nexus. See "Configuring Vertex Manager" for more information.
RegulatedFlag	For Communications Tax Q Series, enter whether the utility is regulated (1) or unregulated (0).
DefaultFlag	Enter 1 for the default tax supplier, and enter 0 for all other tax suppliers. If you have multiple tax suppliers, only one can be the default.
CanonCountry	Enter the country name. See the Vertex documentation for a list of valid values.
VATCertificate	Enter the VAT certificate number associated with the tax supplier. BRM currently does not use this entry. This entry can be used in a custom implementation of tax calculation.

The following pin_tax_supplier.xml file contains two tax suppliers; the first is the default tax supplier.

<TaxSupplierConfiguration> 
  <TaxSupplierElement>
     <Name>TS_1</Name>
     <Description>Tax Supplier 1</Description>
     <Address>Cupertino;CA;95014;US</Address>
     <NexusInfo>*</NexusInfo>
     <RegulatedFlag>0</RegulatedFlag>
     <DefaultFlag>1</DefaultFlag>
     <VATInfo>
        <CanonCountry>US</CanonCountry>
        <VATCertificate>vat_cert_US</VATCertificate>
     </VATInfo>
     <VATInfo>
        <CanonCountry>UK</CanonCountry>
        <VATCertificate>vat_cert_UK</VATCertificate>
     </VATInfo>
  </TaxSupplierElement>
  <TaxSupplierElement>
     <Name>TS_2</Name>
     <Description>Tax Supplier 2</Description>
     <Address>New York;NY;10013;US</Address>
     <NexusInfo>*</NexusInfo>
     <RegulatedFlag>0</RegulatedFlag>
     <DefaultFlag>0</DefaultFlag>
     <VATInfo>
        <CanonCountry>US</CanonCountry>
        <VATCertificate>vat_cert_US</VATCertificate>
     </VATInfo>
     <VATInfo>
        <CanonCountry>UK</CanonCountry>
        <VATCertificate>vat_cert_UK</VATCertificate>
     </VATInfo>
  </TaxSupplierElement>
</TaxSupplierConfiguration>

To load tax suppliers:

Enter the following command to load the tax supplier data:
```
load_tax_supplier pin_tax_supplier.xml 
```
Note:

If you are not working in the same directory as the pin_tax_supplier.xml file, include the complete path to the file.
Stop and restart the CM.

Allowing Your Sales and Use Tax Software to Determine Tax Supplier Data

If your business has customers in multiple countries or operates under other conditions where complex tax laws are involved, you should allow your sales and use tax software to choose the correct tax supplier. The disadvantage is that you need to include every BRM charge offer in the tax_supplier_map file and update the file when you add or delete charge offers.

The tax_supplier_map file lets your tax package determine the correct tax supplier company ID and business location, based on the charge offer and the ship-to locale.

For Sales Tax Q Series, the tax_supplier_map file also maps BRM tax supplier names to your company IDs stored in the company profile or Sales Tax Q Series TDM file. BRM uses this information to maintain database integrity.

The following example shows part of a tax_supplier_map file:

Product    ShipTo     Company ID     Business loc  Ship From                Reg
_______________________________________________________________________________
Item_One : ;;CA;US : Tax supplier1 : loc_1       : Cupertino;CA;95014;US :  1
Sub_One  : ;;;US   : Tax supplier1 : loc_1       : Cupertino;CA;95014;US :  1
Sub_One  : ;;;FR   : Tax supplier2 : loc_2       : Paris;;;FR            :  0

Table 4-2 lists the entries in the tax_supplier_map file.

Table 4-2 Entries in tax_supplier_map File

Entry	Description
Product	The name of the charge offer for which taxes are calculated. See "Creating Pricing Setup Components" in PDC Creating Product Offerings.
ShipTo	The address the product is shipped to (your customer's location). Enter the address in this format: `city`;`state`;`ZIP`;`country` You can leave portions of this string blank, but you must include the semicolons for each address element. Examples: ;;;US ;CA;95003;US In most cases, you do not need to enter the city. See the Vertex documentation for correct state and country entries.
Company ID	The company ID specified in the Vertex TDM (Tax Decision Maker) or company file. This name is also entered in the PIN_FLD_NAME field when you define tax suppliers. This entry must match the name in the TDM or company file. If you use the TDM, the entry will be a four-character code.
Business Loc	The business location specified in the Vertex TDM file or company file. This value indicates which location should be considered when taxes are calculated.
ShipFrom	The address the product is shipped from. Enter the address in this format: `city`;`state`;`ZIP`;`country` You can leave portions of this string blank, but you must include the semicolons for each address element. Examples: ;;;US ;CA;95003;US The ship-from address you define in the tax_supplier_map file can differ from the address used when you specified the default tax supplier. In this case, your tax package obtains the address from the tax_supplier_map file. This enables you to create multiple ship-from addresses for a single tax supplier. See the Vertex documentation for correct state and country entries.
Regulated	For telecommunications tax only, this flag identifies the utility or company that is billing as regulated (0) or unregulated (1). Some taxes apply to regulated or unregulated utilities only; this flag determines which types of taxes are used.

To specify the location of the tax_supplier_map file:

Open the CM configuration file (BRM_home/sys/cm/pin.conf).

Add the tax_supplier_map entry. For example:

-  fm_rate   tax_supplier_map  BRM_home/sys/cm/tax_supplier_map

Save and close the file.
Stop and restart the CM.

Specifying Divisions for Tax Suppliers

Some companies operate divisions with locations that can impact the tax calculation. Use the Business Loc column in the tax_supplier_map file to add information about divisions for tax suppliers. The data in this column is mapped to the Division field in Sales Tax Q Series. This data should match what is stored in the Sales Tax Q Series TDM database.

For example, suppose the tax supplier Acme has two divisions, one in California and one in Illinois. You can configure the tax_supplier_map file to assign customers to the appropriate location. For example:

# Product    ShipTo    Company Id  Business Loc   ShipFrom               Regulated
# -------    ------    ----------  ------------   --------               ---------
electrical : ;;CA;US : Acme      : West         : Cupertino;CA;95014;US : 1
electrical : ;;TX;US : Acme      : Central      : Oak Brook;IL;60523;US : 1

With this configuration, for customers in California, BRM sends West as the division to Sales Tax Q Series. The tax supplier's address will be Cupertino, CA. Similarly, customers in Texas will be assigned to the Central division with the Oak Brook, IL address.

Defining a Default Ship-From Locale

This option provides a ship-from locale in case a tax supplier cannot be found. You need to define at least one tax supplier.

To define a default ship-from locale:

Open the CM configuration file (BRM_home/sys/cm/pin.conf).

Edit the provider_loc entry. For example:

- fm_rate_pol provider_loc Middletown, CA 95222 USA

Save and close the file.

The new value becomes effective immediately, and all subsequent tax calculations use the new address. You do not need to restart the CM.

Overriding Shipped-To with the Real-Time Location

This option overrides the shipped-to locale with your customers' real-time location when calculating taxes. Using a customer's real-time location is supported only for bundle purchases, charge offer purchases, and prepaid top ups through a third-party client application.

Configure your third-party client application to call the following opcodes with the PIN_FLD_LOCALE input flist field set to "City;State;Zipcode;Country":

PCM_OP_SUBSCRIPTION_PURCHASE_DEAL
PCM_OP_SUBSCRIPTION_PURCHASE_PRODUCT
PCM_OP_PYMT_TOPUP

Alternatively, you can configure real-time locations through zone maps.

For more information, see "Overriding Customer Tax Locale for Bundle Purchases" in BRM Opcode Guide.