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 corporate headquarters and branch offices. Vertex uses the tax supplier to calculate taxes.

Tax supplier data can include:

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 origination and termination numbers are derived from call detail records (CDRs).

Note:

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

If you are using the Vertex Tax Q Series software, you specify how to supply tax supplier data to the 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.

If you are using the Vertex O Series tax software, see "Providing the Tax Supplier Data for Vertex O Series".

You can also:

Configure a default ship-from address in case BRM cannot find any tax supplier. See "Defining a Default Ship-From Locale".
Override the shipped-to locale with your customers' real-time location when calculating taxes. See "Overriding Shipped-To with the Real-Time Location".

Providing the Tax Supplier Data with Each Transaction

Note:

This applies only to Vertex Tax Q Series. If you use Vertex O Series, see "Providing the Tax Supplier Data for Vertex O Series".

If your business uses only one tax supplier, define a default tax supplier 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 charge offer’s tax supplier 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, 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 pin_tax_supplier.xml. To modify or remove tax suppliers, edit the file before loading it.

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

In pin_tax_supplier.xml, 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 Taxation Gateway for Vertex O Series" 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 in the same directory as pin_tax_supplier.xml, include the full path to the file.
Stop and restart the CM.

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

Note:

This applies only to Vertex Tax Q Series. If you use Vertex O Series, see "Providing the Tax Supplier Data for Vertex O Series".

If your business has customers in multiple countries or operates under other conditions where complex tax laws are involved, allow your sales and use tax software to determine the correct tax supplier. The trade-off is that you must include every BRM charge offer in the tax_supplier_map file and update it 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 stored 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

Note:

This applies only to Vertex Tax Q Series. If you use Vertex O Series, see "Providing the Tax Supplier Data for Vertex O Series."

Some companies operate divisions with locations that can impact the tax calculation. Use the Business Loc column in the tax_supplier_map file to specify divisions for tax suppliers. The data in this column is mapped to the Division field in Sales Tax Q Series. This value must match the Division value 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.

Providing the Tax Supplier Data for Vertex O Series

Note:

This only applies to Vertex O Series.

BRM sends tax supplier and location details with each tax request to Vertex O Series by using the Taxation Gateway. Each request includes the tax supplier's name and the customer's destination, along with line items and prices. Vertex O Series returns jurisdiction-level results, including effective rates, calculated taxes, and document totals used for billing. To support this flow, BRM maps tax codes to Vertex O Series by using the config_taxcodes_map.xml file.

You configure the Vertex O Series provider, endpoints, and mapper specifications in the BRM application.yaml file, and you define how each tax code is treated by Vertex.

Defining a Default Ship-From Locale

Use this option to provide a ship-from locale if a tax supplier cannot be found. You must 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; subsequent tax calculations use the updated address. A CM restart is not required.

Overriding Shipped-To with the Real-Time Location

This option overrides the shipped-to locale with the customer’s 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 these 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, configure real-time locations through zone maps.

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

4 Creating Tax Suppliers

About Tax Suppliers

Providing the Tax Supplier Data with Each Transaction

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

Specifying Divisions for Tax Suppliers

Providing the Tax Supplier Data for Vertex O Series

Defining a Default Ship-From Locale

Overriding Shipped-To with the Real-Time Location