Overview
This article describes how to integrate with the Tax Management API to calculate taxes.
The Tax Management API offers the ability to calculate taxes for given features at the customer and/or service level. The taxes returned are summarized at the service level.
Calculate Taxes
To calculate taxes, issue an HTTP POST to api/calculateTaxes endpoint (https://api.idibilling.com/TaxManagement/2x/{environment}/api/calculateTaxes). The request should have Content-Type of application/json.
Request
The request body must be json.
Example Request:
{
"customer": {
"jurisdictionReference": "VictorNY",
"features": [ { "sku": "ProductSKU", "quantity": "2", "charge": "9.99" } ],
"services": [ {
"features": [ { "sku": "ProductSKU", "quantity": "2", "charge": "9.99" } ],
"jurisdictionReference": "VictorNY",
"serviceReference": "1",
"sku": "Wireless" } ] },
"jurisdictions": [ { "city": "Victor", "jurisdictionReference": "VictorNY", "state": "NY", "county": "Ontario" }]
}
| Name | Notes |
| customer | A customer object. Required section |
| jurisdictionReference | Required value that needs to be unique within the jurisdictions section. This value also shows up under the customer and services sections. The value links a specific jurisdiction to a customer and/or service. |
| features | List of items to be taxed. Exists under the customer and/or services sections. |
| sku | CostGuard product catalog SKU value for the item being charged. |
| quantity | Number of features being charged. If not specified the default value is 1. When quantity is a value other than 1 we assume charge is a unit rate which means the feature is taxed on a total amount equal to quantity * charge. |
| charge | The amount that will be charged for this feature. When set to null the value will be pulled from CostGuard product catalog. Quantity is 1 then this is the total amount charged for this feature. |
| services | List of service(s) associated to the customer. |
| serviceReference | Required value that needs to be unique within the services section. This value will be included in the response so you can match a unique service to the taxes associated to that service. |
| sku | CostGuard product catalog service SKU value for the type of service. |
| jurisdictions | List of jurisdiction objects. Required section. There are four different ways in which the jurisdiction object can be populated.
1. Using city, state, and county 2. Using state and taxJurisdictionIDs 3. Using state only 4. Using city, state, and zipCode See Jurisdiction sections below for details. |
Example Response:
{
"taxes": [
{
"amount": 0.000000,
"name": "Sales Tax Info & Entertainment Services",
"rate": 0.050000,
"taxID": 14917,
"serviceReference": "1"
},
{
"amount": 0.731642,
"name": "Ontario County State and Local Sales Tax",
"rate": 0.075000,
"taxID": 110371,
"serviceReference": "1"
}
]
}
| Name | Notes |
| taxes | A list of tax objects. |
| amount | The amount of tax due. This value is not rounded and will display 6 decimal places. A value of 0.000000 can be returned if the tax applied but didn’t calculate to a large enough value. The caller of the API is responsible to filter and round as need for their own display purposes. |
| name | The name of the tax. This value is not guaranteed to be unique within the results. Two taxes can have the same name but different taxID values. In those cases, it’s up to the caller to aggregate those values as needed. |
| rate | The rate of the tax if the tax is a flat rate. Other types of taxes like tiered or per line will have a value of zero. |
| taxID | Unique identifier for a tax. |
| serviceReference | Unique identifier of the service given in the request body associated to a service. Customer level taxes will have a value of 0. |
Jurisdiction (Using city, state, and county)
If the city, state, and county of the address are known for the desired jurisdiction, populate these three fields. The jurisdiction(s) matching these will be used.
If we are unable to find a jurisdiction with the given city, state, and county combination we will look for a jurisdiction with state, county, and null city. If we find a tax jurisdiction with the null city lookup that means county level taxes will be applied to the charges.
When no tax jurisdiction can be found logging number 500319 (No Tax Jurisdiction Found) will be returned. There are two ways this can be resolved.
- Validate the address through the address validation management /validateAddress end point and use the returned city, state, and county in the calculateTaxes request.
- Look up the county using the CoreDataService/TaxJurisdiction OData in the Data webservice.
Example Request (Using city, state, and county)
{
"customer": {
"jurisdictionReference": "VictorNY",
"features": [ { "sku": "ProductSKU", "quantity": "2", "charge": "9.99" } ],
"services": [ {
"features": [ { "sku": "ProductSKU", "quantity": "2", "charge": "9.99" } ],
"jurisdictionReference": "VictorNY",
"serviceReference": "1",
"sku": "Wireless" } ] },
"jurisdictions": [ { "city": "Victor", "jurisdictionReference": "VictorNY", "state": "NY", "county": "Ontario" }]
}
Jurisdiction (Using state and taxJurisdictionIDs)
If the specific taxJurisdictionIDs (unique CostGuard identifiers) are already known, populate them directly, along with state.
This option would generally be used for existing CostGuard web services where the tax jurisdiction IDs are already known. Alternately the CoreDataService/TaxJurisdiction OData in the Data webservice will return them if you wanted to look them up before calling this API.
Example Request (Using state and taxJurisdictionIDs)
{
"customer": {
"jurisdictionReference": "VictorNY",
"services": [ {
"features": [ { "sku": "Charge30_InAdv", "quantity": "2", "charge": "9.99" } ],
"jurisdictionReference": "VictorNY",
"serviceReference": "1",
"sku": "Wireless" } ] },
"jurisdictions": [ { "jurisdictionReference": "VictorNY", "state": "NY", "taxJurisdictionIDs" : [31510] }]
}
Jurisdiction (Using state only)
If only state-level (and any applicable federal-level) taxes are to be applied, populate only state.
This option is generally used for taxing outside of USA.
The state value needs to be a two-character state abbreviation. There are abbreviations for countries and places outside of USA. Valid values can be retrieved from the /CoreDataService/TaxState OData in the Data webservice.
Example Request (Using state only)
{
"customer": {
"jurisdictionReference": "Quebec",
"services": [ {
"features": [ { "sku": "Charge30_InAdv", "quantity": "2", "charge": "9.99" } ],
"jurisdictionReference": "Quebec",
"serviceReference": "1",
"sku": "Wireless" } ] },
"jurisdictions": [ { "jurisdictionReference": "Quebec", "state": "QC" }]
}
Jurisdiction (Using city, state, and zipCode)
If the county is not known directly, zipCode can be populated alongside city and state. This is the least-preferred method, because a unique county cannot always be determined. If an unqiue county cannot be determined, only one of the matching counties will be used.
When no tax jurisdiction can be found logging number 500318 (No County Found) will be returned. There are two ways this can be resolved.
- Validate the address through the address validation management /validateAddress end point and use the returned city, state, and county in the calculateTaxes request.
- Look up the county using the CoreDataService/TaxJurisdiction OData in the Data webservice.
Example Request (Using city, state, and zipCode)
{
"customer": {
"jurisdictionReference": "VictorNY",
"services": [ {
"features": [ { "sku": "Charge30_InAdv", "quantity": "2", "charge": "9.99" } ],
"jurisdictionReference": "VictorNY",
"serviceReference": "1",
"sku": "Wireless" } ] },
"jurisdictions": [ { "city": "Victor", "jurisdictionReference": "VictorNY", "state": "NY", "zipCode": "14564" }]
}
Exemptions
Tax exemptions can be set at the customer level and/or service level. They allow you to specify that a customer will be exempt from a group of taxes.
Example Request (Exemptions)
{
"customer": {
"extendedTaxExemptionIDs" : [78,130],
"jurisdictionReference": "VictorNY",
"features": [ { "sku": "ProductSKU", "quantity": "2", "charge": "9.99" } ],
"services": [ {
"extendedTaxExemptionIDs" : [43],
"features": [ { "sku": "ProductSKU", "quantity": "2", "charge": "9.99" } ],
"jurisdictionReference": "VictorNY",
"serviceReference": "1",
"sku": "Wireless",
"taxExemptFlagsE911": { "city": true, "county": true, "regional": true, "state": true } } ],
"taxExemptFlags": { "city": true, "county": true, "federal": true, "regional": true, "state": true },
"taxExemptFlagsE911": { "city": true, "county": true, "regional": true, "state": true },
"taxExemptFlagsSurcharge": { "city": true, "county": true, "federal": true, "regional": true, "state": true },
"taxExemptFlagsUSF": { "city": true, "county": true, "federal": true, "regional": true, "state": true } },
"jurisdictions": [ { "city": "Victor", "jurisdictionReference": "VictorNY", "state": "NY", "county": "Ontario" }]
}
| Name | Notes |
| extendedTaxExemptionIDs | A list of extended tax exemption IDs. These can be set at the customer and/or service level. A list of valid values can be looked up using the /CoreDataService/ExtendedTaxExemption OData in the Data web service. |
| taxExemptFlagsE911 | Is the customer/service exempt from E911 taxes? These flags can be set at the customer and/or service level. |
| taxExemptFlags | Is the customer exempt from taxes? |
| taxExemptFlagsSurcharge | Is the customer exempt from Surcharges? |
| taxExemptFlagsUSF | Is the customer exempt from USF taxes? |
Per Line Tax
Services which need to be counted more one once for per line tax calculations need to specify the perLineTaxOverride section. This allows taxing to calculate per line taxes with the correct number of lines.
Example Request (Per Line Tax)
{
"customer": {
"jurisdictionReference": "VictorNY",
"features": [ { "sku": "ProductSKU", "quantity": "2", "charge": "9.99" } ],
"services": [ {
"features": [ { "sku": "ProductSKU", "quantity": "2", "charge": "9.99" } ],
"jurisdictionReference": "VictorNY",
"perLineTaxOverride": {
"enablePerChannelTaxing": true,
"enablePerSingleLineTaxing": true,
"perLineTaxClassID": 1,
"perLineTaxConfigurations": [
{ "isPerChannel": true, "isDataUsageTaxable": true, "isVoiceUsageTaxable": false,
"isInboundTaxable": false, "isOutboundTaxable": true, "numberOfChannels": 25 },
{ "isPerChannel": false, "isDataUsageTaxable": true, "isVoiceUsageTaxable": false,
"isInboundTaxable": false, "isOutboundTaxable": true } ]
},
"serviceReference": "1",
"sku": "Wireline" } ] },
"jurisdictions": [ { "city": "Victor", "jurisdictionReference": "VictorNY", "state": "NY", "county": "Ontario" }]
}
| Name | Notes |
| perLineTaxOverride | An object that hold per line tax override information. |
| enablePerChannelTaxing | Should this service be counted based on number of channels? When true perLineTaxConfigurations should contain at least one entry with isPerChannel set to true and numberOfChannels set to an integer. |
| enablePerSingleLineTaxing | Should this service be counted as a single line? When true perLineTaxConfigurations should contain at least one entry with isPerChannel set to false. |
| perLineTaxClassID | Per-line tax class ID to use for this service. Valid values can be looked up in the /CoreDataService/PerLineTaxClass OData of the Data web service. |
| perLineTaxConfigurations | A list of per line tax configurations. |
| isPerChannel | Whether or not this configuration represents the service counting as multiple channels. If true, this configuration represents the service counting as multiple channels (numberOfChannels needs to be filled in). If false, this configuration reprints the service counting as a single line. |
| isDataUsageTaxable | Is data usage taxable for this service count? |
| isVoiceUsageTaxable | Is voice usage taxable for this service count? |
| isInboundTaxable | Is inbound usage taxable for this service count? |
| isOutboundTaxable | Is Outbound usage taxable for this service count? |
| numberOfChannels | Number of channels the service should be counted as for this configuration. When set the value of isPerChannel should be equal to true. |
