Calculation Request
The Calculation Request method is used to create a transaction to calculate taxes. There are three types of calculation requests: Quote, In Progress and Finalized controlled by the value in the ReturnFileCode field.
For REST Integrations:
Method: PostRequest
URL: /Services/General/V01/SureTax.asmx/PostRequest
For SOAP Integrations:
Method: SoapRequest
URL: /Services/General/V01/SureTax.asmx
Request Layout
Field names formatted in BOLD are required fields that must be passed to SureTax.
All Field Names are case-sensitive.
Field values are required unless otherwise noted in their description below.
Request Record
FIELD | FIELD NAME | DESCRIPTION |
---|---|---|
Client Number | ClientNumber | Client ID Number - provided by CCH SureTax. |
Business Unit | BusinessUnit | Client's Business Unit. Value for this field is not required. Max Length: 20 |
Validation Key | ValidationKey | Validation Key provided by CCH SureTax. |
Data Year | DataYear | YYYY - The system will use the rates for the specified year when calculating taxes. |
Data Month | DataMonth | MM - The system will use the rates for the specified month when calculating taxes. Leading zero is preferred. |
Compliance Year | CmplDataYear | YYYY - Year during which a transaction occurred. This is used when remitting taxes for the specified year. |
Compliance Month | CmplDataMonth | MM - Month during which a transaction occurred. This is used when remitting taxes for the specified month. Leading zero is preferred. |
Total Revenue | TotalRevenue | Format: $$$$$$$$$.CCCC For Negative charges, the first position should have a minus (-) indicator. |
Return File Code | ReturnFileCode | Defines the type of calculation for the transaction. 0 - Finalized - taxes are computed and returned in the response message. All detailed tax information is saved in the CCH SureTax tables for immediate reporting or review. Q - Quote - taxes are computed and returned in the response message for generating quotes. No detailed tax information is saved in the CCH SureTax tables for reporting or review. T - In-Progress - taxes are computed and returned in the response message and detailed tax information is saved in the CCH SureTax tables. However, the transaction must be finalized in order for the reporting information to be available. |
Client Tracking Field | ClientTracking | Field for client transaction tracking. This value will be provided in the response data. Value for this field is not required, but preferred. Max Length: 100 |
Response Type | ResponseType | Determines the processing option, granularity of taxes, and the decimal precision for the tax amounts in the response. A Response Type is comprised of three components:
|
System Trace Audit Number | STAN | Optional value. A unique value provided by client for transaction audit purposes. If you don't need transaction audit set value as null. Max Length: 40 |
Master Trans ID | MasterTransId | Field used to modify previously ran transaction. To use this feature Transaction should be in In-Progress state with a ReturnFileCode of T |
Client Items | ItemList | List of Item records. (See: Item Layout) |
Item layout:
Field names formatted in BOLD are required fields that must be passed to SureTax API.
All Field Names are case-sensitive.
Field values are required unless otherwise noted in their description below.
FIELD | FIELD NAME | DESCRIPTION |
---|---|---|
Line Number | LineNumber | Used to identify an item within the request. If no value is provided, response are numbered sequentially. Max Length: 40 |
Invoice Number | InvoiceNumber | Invoice, Sales Order, Credit Memo, or any Document number for a given transaction. Must be alphanumeric. Max Length: 40 |
Customer Number | CustomerNumber | Customer Identifier. Must be alphanumeric. Max Length: 40 |
Location Code | LocationCode | Used to provide the location / outlet ID. Must be alphanumeric. Max Length: 40 |
Date of Transaction | TransDate | Date of transaction. Valid date formats include: MM/DD/YYYY MM-DD-YYYY |
Revenue | Revenue | Total line item amount. Format: $$$$$$$$$.CCCC For Negative charges, the first position should have a minus (-) indicator. |
Quantity | Units | Number of items associated with the revenue. Must be value greater of 0. (default 1) Format: 99999.99 |
Tax Included Code | TaxIncludedCode | Revenue includes the tax amount. SureTax will back calculate the tax included within the revenue amount. Values: 0 - No Tax Included (recommended) 1 - Tax Included in Revenue |
Tax Situs Rule | TaxSitusRule | Identifies what address to use for tax calculation purposes. Values: 22 - Use All Addresses / Zip+4 to determine the proper situs location. 23 - Use only Ship To Address / Zip+4 24 - Use only Ship From Address / Zip+4 25 - Use only Order Approval Address / Zip+4 26 - Use only Order Placement Address / Zip+4 27 - Use only ZIP+4 from the Billing Address |
Transaction Type Code | TransTypeCode | Could be either Product Identifer (SKU) or SureTax TransTypeCode or Product Group Product Item (PGPI). Max Length: 50 |
Sales Type Code | SalesTypeCode | Describes the type of customer. Values: R - Residential customer B - Business customer I - Industrial customer T - Retail (recommended) |
Regulatory Code | RegulatoryCode | Type of service being provided. Values: 70 - Retail |
Tax Exemption Codes | TaxExemptionCodeList | Tax Exemption to be applied to this item only. Tax Exemption Record Indicators for values To enter a partial exemption, enter the exemption indicator followed by the percentage as a decimal. For example, enter "02:.25" for state tax (02) and 25%. |
Tax Exempt Reason Code | ExemptReasonCode | Used only if you are adding exemption certificate information into the system Tax Exemption reason value. See Exemption Reason Codes for values. |
Auxiliary Revenue | AuxRevenue | Additional revenue related to the line item that will adhere to the same taxability application. (Example: Item Discount Amount) Format: $$$$$$$$$.CCCC |
Auxiliary Revenue Type | AuxRevenueType | Auxiliary Revenue Type. (No current types supported) |
Tax Rule Override | RuleOverride | Determines whether Default Tax Logic, Sales Tax, Sellers Use Tax or Consumers Use Tax is calculated. Values: 0 - Default Tax Logic 1 - Return only Sales Tax 2 - Return only Sellers Use Tax 3 - Consumers Use Tax |
Cost Center | CostCenter | Available for use in the rules engine. Max Length: 25 Alphanumeric |
GL Account | GLAccount | Available for use in the rules engine. Max Length: 25 Alphanumeric |
Material Group | MaterialGroup | Available for use in the rules engine. Max Length: 25 Alphanumeric |
Parameter 1 | Parameter1 | User defined field. Available for use in the rules engine. Max Length: 25 Alphanumeric |
Parameter 2 | Parameter2 | User defined field. Available for use in the rules engine. Max Length: 25 Alphanumeric |
Parameter 3 | Parameter3 | User defined field. Available for use in the rules engine. Max Length: 25 Alphanumeric |
Parameter 4 | Parameter4 | User defined field. Available for use in the rules engine. Max Length: 25 Alphanumeric |
Parameter 5 | Parameter5 | User defined field. Available for use in the rules engine. Max Length: 25 Alphanumeric |
Parameter 6 | Parameter6 | User defined field. Available for use in the rules engine. Max Length: 25 Alphanumeric |
Parameter 7 | Parameter7 | User defined field. Available for use in the rules engine. Max Length: 25 Alphanumeric |
Parameter 8 | Parameter8 | User defined field. Available for use in the rules engine. Max Length: 25 Alphanumeric |
Parameter 9 | Parameter9 | User defined field. Available for use in the rules engine. Max Length: 25 Alphanumeric |
Parameter 10 | Parameter10 | User defined field. Available for use in the rules engine. Max Length: 25 Alphanumeric |
Currency Code | CurrencyCode | Currency code based on ISO standard. As reference - http://www.xe.com/iso4217.php |
User defined field | UDF | User defined field. Not available for use in the rules engine, but is available for use in reports and extracts. Max Length: 100 |
User defined field 2 | UDF2 | User defined field. Not available for use in the rules engine, but is available for use in reports and extracts. Max Length: 100 |
Billing Address | BillingAddress | Billing address for transaction - see Address Layout definition below. |
Ship To Address | ShipToAddress | Ship To address for transaction - see Address Layout definition below. |
Ship From Address | ShipFromAddress | Ship From address for transaction - see Address Layout definition below. If not provided, Ship To Address will be used as the default. |
Order Placement Address | OrderPlacementAddress | Order Placement address for transaction - see Address Layout definition below. If not provided, Ship From Address will be used as the default. |
Order Approval Address | OrderApprovalAddress | Order Approval address for transaction - see Address Layout definition below. If not provided, Order Placement Address will be used as the default. |
Address Layout:
Field names formatted in BOLD are required fields that must be passed to SureTax API. All Field Names are case-sensitive. Field values are required unless otherwise noted in their description below.
Field | Field Name | Description |
---|---|---|
Primary Address Line | PrimaryAddressLine | Address Line 1 |
Secondary Address Line | SecondaryAddressLine | Address Line 2 |
County | County | County |
City | City | City |
State | State | State - full state name or two character abbreviation accepted |
PostalCode | PostalCode | ZIP code or Canadian postal code |
Plus4 | Plus4 | ZIP+4 |
Country | Country | International country ISO code value in format: XX |
CCH Geocode | Geocode | If provided, the CCH Geocode will take precedence and will be used instead of the address / ZIP+4 information. |
Verify Address | VerifyAddress | This feature is currently disabled. Pass 0. |
Examples
request={
"ClientNumber": "<CLIENTNUMBER>",
"ValidationKey": "<VALIDATIONKEY>",
"DataYear": "2020",
"DataMonth": "4",
"CmplDataYear": "2020",
"CmplDataMonth": "4",
"TotalRevenue": "1000",
"ReturnFileCode": "Q",
"ClientTracking": "TEST",
"ResponseType": "2D5",
"STAN": "",
"MasterTransID": "",
"ItemList": [
{
"LineNumber": "1",
"InvoiceNumber": "INV000001",
"CustomerNumber": "CUS000001",
"LocationCode": "",
"TransDate": "04/01/20",
"Revenue": "1000.00",
"Units": "1",
"TaxIncludedCode": "0",
"TaxSitusRule": "22",
"TransTypeCode": "990101",
"SalesTypeCode": "T",
"RegulatoryCode": "70",
"TaxExemptionCodeList": ["00"],
"ExemptReasonCode": "",
"AuxRevenue": "0",
"AuxRevenueType": "",
"RuleOverride": "0",
"CostCenter": "",
"GLAccount": "",
"MaterialGroup": "",
"Parameter1": "",
"Parameter2": "",
"Parameter3": "",
"Parameter4": "",
"Parameter5": "",
"Parameter6": "",
"Parameter7": "",
"Parameter8": "",
"Parameter9": "",
"Parameter10": "",
"CurrencyCode": "USD",
"UDF": "",
"UDF2": "",
"ShipToAddress": {
"PrimaryAddressLine": "9797 Rombauer Rd",
"SecondaryAddressLine": "",
"County": "",
"City": "Coppell",
"State": "TX",
"PostalCode": "75019",
},
"ShipFromAddress": {
"PrimaryAddressLine": "9797 Rombauer Rd",
"SecondaryAddressLine": "",
"County": "",
"City": "Coppell",
"State": "TX",
"PostalCode": "75019",
}
}
]
}
Response Layout
CCH SureTax supports taxes to be returned by Line Item in addition to Customer Number, Invoice Number and Location Code. The response message also includes additional detail values for each of the taxes applied to the line items.
Response Header
FIELD NAME | DESCRIPTION |
---|---|
Successful | Response will be either "Y" or "N": Y = Success / Success with Item errorN = Failure |
ResponseCode | ResponseCode: 9999 - Request was successful.1101-1400 - Range of values for a failed request (no processing occurred). 9001 - Request was successful, but items within the request have errors. The specific items with errors are provided in the ItemMessages field. |
HeaderMessage | Response message: For ResponseCode 9999 - "Success"For ResponseCode 9001 - "Success with Item errors". See the ItemMessages field for a list of items / errors. For ResponseCode 1100-1400 - Unsuccessful / declined web request. See Response Code and Messages for a list of the response code and messages. |
ItemMessages | This field contains a list of items that were not able to be processed due to bad or invalid data (see Response Code of "9001"). These invalid items will be listed by line number with the corresponding response code and message. When an item error occurs, no tax processing will occur for that item record. When an error for an item occurs, this field contains the following fields:LineNumber - a value corresponding to the line number in the web request. ResponseCode - a value in the range 9100-9400.Message - the error message corresponding to the ResponseCode. See Response Code and Messages for a list of the response code and messages.If no item errors exist, the field will have a value of empty. |
ClientTracking | Client transaction tracking provided in web request. |
TotalTax | Total Tax - a total of all taxes included in the TaxList |
TransId | Transaction ID (integer) - Unique identifier for your transaction provided by CCH SureTax |
STAN | Unique System Trace Audit Number |
MasterTransId | The "master" SureTax TransID assigned to an in-progress transaction |
GroupList | See Group (contains one-to-many Groups) |
Group
FIELD NAME | DESCRIPTION |
---|---|
LineNumber | Line Number (from Request) |
StateCode | Tax State |
InvoiceNumber | Invoice Number (from Request) |
CustomerNumber | Customer number (from Request) |
LocationCode | Location code (from Request) |
TaxList | See Tax Item(s) - contains one-to-many Tax Items |
TaxItem(s)
FIELD NAME | DESCRIPTION |
---|---|
TaxTypeCode | Tax Type Code |
TaxTypeDesc | Jurisdiction-specific Tax Type Description |
TaxAmount | Tax Amount |
Revenue | Source Revenue for Line Item |
CountyName | County Name of taxing jurisdiction |
CityName | City Name of taxing jurisdiction |
TaxRate | Tax rate for tax type applied in decimal format (if zero, see FeeRate) |
PercentTaxable | Percentage of the tax that is taxable for the tax type in decimal format. This can be less than 100% in certain circumstances. |
FeeRate | The unit based fee for the tax type in format $.CCCC (if zero, see TaxRate) |
RevenueBase | The effective revenue for the tax provided in the TaxAmount field. This amount can be different than the amount in the Revenue field when taxes are impacted by specific exemptions and/or tax on tax. |
TaxOnTax | The amount of tax on tax attributed to the final amount of tax. Note this amount is included in the TaxAmount field total and is provided here separately only for reference purposes. |
TaxAuthorityID | The ID of the Tax Authority associated with the tax (CCH SureTax defined value) |
TaxAuthorityName | The name of the Tax Authority associated with the tax |
Juriscode | The jurisdictional code associated with the tax (usually used for return compliance purposes) |
Examples
{
"ClientTracking": "TEST",
"GroupList": [
{
"CustomerNumber": "CUS000001",
"InvoiceNumber": "INV000001",
"LineNumber": "1",
"LocationCode": "",
"StateCode": "TX",
"TaxList": [
{
"CityName": "COPPELL",
"CountyName": "DALLAS",
"FeeRate": 0,
"Juriscode": "",
"PercentTaxable": 1.0,
"Revenue": "1000.00000",
"RevenueBase": "1000.00000",
"TaxAmount": "62.50000",
"TaxAuthorityID": "12043",
"TaxAuthorityName": "TEXAS, STATE OF",
"TaxOnTax": "0",
"TaxRate": 0.0625,
"TaxTypeCode": "101",
"TaxTypeDesc": "STATE SALES TAX"
},
{
"CityName": "COPPELL",
"CountyName": "DALLAS",
"FeeRate": 0,
"Juriscode": "2057262",
"PercentTaxable": 1.0,
"Revenue": "1000.00000",
"RevenueBase": "1000.00000",
"TaxAmount": "17.50000",
"TaxAuthorityID": "2031",
"TaxAuthorityName": "COPPELL, CITY OF",
"TaxOnTax": "0",
"TaxRate": 0.0175,
"TaxTypeCode": "304",
"TaxTypeDesc": "CITY SALES TAX"
},
{
"CityName": "COPPELL",
"CountyName": "DALLAS",
"FeeRate": 0,
"Juriscode": "5057501",
"PercentTaxable": 1.0,
"Revenue": "1000.00000",
"RevenueBase": "1000.00000",
"TaxAmount": "2.50000",
"TaxAuthorityID": "2031",
"TaxAuthorityName": "COPPELL, CITY OF",
"TaxOnTax": "0",
"TaxRate": 0.0025,
"TaxTypeCode": "305",
"TaxTypeDesc": "COPPELL- CRIME CONTROL DISTRICT"
}
]
}
],
"HeaderMessage": "Success",
"ItemMessages": [],
"MasterTransId": 841901837,
"ResponseCode": "9999",
"STAN": "",
"Successful": "Y",
"TotalTax": "82.50000",
"TransId": 841901837
}