Evaluate Transactions
NOTE: All the URL paths listed here are relative to https://{DevHub host}/ on Sandbox Environment and relative to https://{S1 host}/ on Production Environment.
NOTE: Users of the Sandbox Environment should remove the /api/basic-auth prefix for all URL paths listed below.
Users can send a request to calculate tax on a transaction. Issuing an Evaluate transaction call will calculate taxes on the transaction but will not maintain (persist) the request information or the response. This call is used to confirm tax liability on an invoice received from a vendor, or for testing purposes.
HTTP Request
Evaluate
POST /api/pre-auth/simple-connect-ap/v1/transactions?state=EVALUATE Header Parameters
- Content-Type: (Required) Acceptable values are
application/xmlorapplication/json. x-request-date: (Required for the HMAC authentication schema) Current request date in ISO 8601 format (yyyy-MM-ddTHH:mm:ss.SSSZ). For more information, see Authentication.Authentication: (Required) Standard Basic-based string for Sandbox environment, and HMAC-based schema for Production environment. For more information, see Authentication.x-request-id: (Optional) Client-generated request ID.x-implementer-id: (Optional) External implementer ID.
The following information provides a detailed overview of Sovos Simple Connect API – AP evaluate request and response fields.
Body Parameters
Header Fields
If a transaction is sent via XML, every field should be inside of a transaction tag.
| Field | Description | Data Type | Restrictions |
|---|---|---|---|
purchaseNumber | Transaction’s document number. | String | Min: 3 characters, Max: 40 characters |
purchaseDate | Transaction’s document date default value; current date in UTC. | String – Date | Date format: yyyy-MM-dd |
currencyCode | Transaction’s currency code. Default value when null is USD. | String | |
taxDirection | 1. FORWARD: Forward tax calculation.2. BACKWARD: Backward tax calculation.Default value when null: FORWARD. | String – Enum | Accepted values: FORWARD/BACKWARD |
vendorID | Default value if line vendorId is null. | String | Min: 3 characters, MAX: 40 characters |
exemptionReasonCode | Default value if line exemptionReasonCode is null. | ||
deliveryAmount | Transaction’s header level delivery amount. | BigDecimal | Max 20 digits Max 8 digits |
billTo | Default value if line billTo value is null. | Object – Address | |
shipTo | Default value if line shipTo value is null. | Object – Address | |
shipFrom | Default value if line shipFrom value is null. | Object – Address | |
discount | XML discount element only (use discounts field for JSON); list of discounts applied to the entire transaction. | List – Discount | XML only. Limit of 5 discounts that can be applied to a transaction. |
discounts | JSON discount field only (use discount element for XML); list of discounts applied to the entire transaction. | List – Discount | JSON only. Limit of 5 discounts that can be applied to a transaction. |
buyerRegistrationNumber | XML registration element only (use buyerRegistrationNumbers field in JSON); list of line registration number value is null. | List – Registration | XML only |
buyerRegistrationNumbers | JSON registration number field only (use buyerRegistrationNumber element in XML); list of registration objects. Default value if line registration value is null. | List – Registration | JSON only |
sellerRegistrationNumber | XML registration number element only (use sellerRegistrationNumbers field in JSON); list of registration objects. Default value if line registration number value is null. | List – Registration | XML only |
sellerRegistrationNumbers | JSON registration number field only (use sellerRegistrationNumber element in XML); list of registration objects. Default value if line registration value is null. | List – Registration | JSON only |
thirdPartyRegistrationNumber | XML registration number element only (use thirdPartyRegistrationNumbers field in JSON); list of registration objects. Default value if line registration number value is null. | List – Registration | XML only |
thirdPartyRegistrationNumbers | JSON registration number field only (use thirdPartyRegistrationNumber element in XML); list of registration objects. Default value if line registration value is null. | List – Registration | JSON only |
lineItem | XML line item element only (use lineItems field in JSON); list of line items associated with the transaction. | List – LineItem | XML only. Limit X number of line items. |
lineItems | JSON line item field only (use lineItem element in XML); list of line items associated with the transaction. | List – LineItem | JSON only. Limit X number of line items. |
Line Item Request Fields
| Field | Description | Data Type | Restrictions |
|---|---|---|---|
identifier | Line item identifier. | String | Min: 1 character, Max: 40 characters |
goodServiceCode | Line item product code. | String | Min: 3 characters, Max: 40 characters |
description | Line item product description. | String | Min: 3 characters, MAX: 40 characters |
grossAmount | Line item gross amount. | BigDecimal | Max 20 digits Max 8 digits |
vendorCode | Line item purchased from vendor. | String | Min: 3 characters, Max: 40 characters |
exemptionReasonCode | Line item customer exemption reason code. | String | Min: 3 characters, Max: 40 characters |
deliveryAmount | Line item delivery amount. | BigDecimal | Max 20 digits Max 8 digits |
deliveryDate | Date the item will be delivered. | String – Date | Date format: yyyy-MM-dd |
quantity | Quantity of item purchased. | BigDecimal | Max 20 digits Max 8 digits |
billTo | Address to which the purchase will be billed. | Address | |
shipTo | Address to which the item will be shipped. | Address | |
shipFrom | Address from which the item will be shipped. | Address | |
discount | XML discount element only (use discounts List – Discount | XML only. Limit of 5 discounts that can be applied to a transaction. |
|
discounts | XML discount field only (use discount element in XML); list of discounts applied to entire transaction. | List – Discount | JSON only. Limit of 5 discounts that can be applied to a transaction. |
buyerRegistrationNumber | XML registration number element only (use buyerRegistrationNumbers field in JSON); list of registration objects. | List – Registration | XML only |
buyerRegistrationNumbers | JSON registration number field only (use buyerRegistrationNumber element in XML); list of registration objects. | List – Registration | JSON only |
sellerRegistrationNumber | XML registration element only (use sellerRegistrationNumbers field in JSON); list of registration objects. | List – Registration | XML only |
sellerRegistrationNumbers | JSON registration number field only (use sellerRegistrationNumbers element in XML); list of registration objects. | List – Registration | JSON only |
thirdPartyRegistrationNumber | XML registration number element only (use thirdPartyRegistrationNumbers field in JSON); list of registration objects. | List – Registration | |
thirdPartyRegistrationNumbers | JSON registration number field only (use thirdPartyRegistrationNumber field in JSON); list of registration objects. | List – Registration |
Discount Request Fields
| Field | Description | Data Type | Restrictions |
|---|---|---|---|
amount | Amount of discount to be applied. Will default to standard discount and adjust gross amount. | BigDecimal | Max 20 digits Max 8 digits |
type | Type of discount to be applied will default to standard discount and adjust gross amount. | String | Min 3 characters Max 1,000 characters |
Registration Number Request Fields
| Field | Descrtiption | Data Type | Restrictions |
|---|---|---|---|
country | Registration country. | String | |
status | Status of the registration. Acceptable values:IDENTIFIEDESTABLISHED (default value)DISTANCE_SALESSPECIAL_SCHEMEVOLUNTARY_USE_TAXESTABLISHED_UNION_SCHEME (EU only) | String – Enum | |
jurisdictionType | Type of jurisdiction for the given registration. Acceptable values:COUNTRY (default value)STATECOUNTYCITYDISTRICTDISTRICT 2 | String – Enum | |
number | Registration number. | String |
Address Request Fields
| Field | Description | Data Type | Restrictions |
|---|---|---|---|
address | Street address | String | Max: 40 characters |
cityMunicipality | City | String | Max: 40 characters |
county | County | String | Max: 40 characters |
stateProvince | State or Province | String | Max: 40 characters |
zipPostalCode | Base postal code | String | Max: 5 characters |
zipPostalCodeExtension | Postal code extension | String | Max: 4 characters |
country | Country | String | Max: 40 characters |
Response Fields
Header Fields
The following fields will be inside of a response tag.
| Field | Description | Data Type | Restrictions |
|---|---|---|---|
status | HTTP status code. | Integer | |
message | General response message. | String | |
data | Main calculation response data. | Object – Invoice |
Invoice Fields
| Field | Description | Data Type | Restrictions |
|---|---|---|---|
transactionId | Transaction ID; used for altering transactional state. | String | |
purchaseNumber | Transaction purchase number. | String | |
currencyCode | Transaction currency code. | String | |
invoiceDate | Transaction invoice date. | String – Date | |
customerCode | Transaction customer ID. | String | |
totalTaxAmount | Transaction order total tax amount. | BigDecimal | |
billTo | Cleansed transaction request address (if enabled). | Object – Address | |
shipTo | Cleansed transaction request address (if enabled). | Object – Address | |
shipFrom | Cleansed transaction request address (if enabled). | Object – Address | |
lineItems | Line item responses. | List – LineItem |
Line Item Fields
| Field | Description | Data Type | Restrictions |
|---|---|---|---|
identifier | Line item identifier. | String | |
billTo | Cleansed transaction request address (if enabled). | Object – Address | |
shipTo | Cleansed transaction request address (if enabled). | Object – Address | |
shipFrom | Cleansed transaction request address (if enabled). | Object – Address | |
totalTaxAmount | Line item total tax amount. | BigDecimal | |
taxInfo | Tax information associated with the line item. | List – TaxInfo |
Tax Information Fields
| Field | Description | Data Type | Restrictions |
|---|---|---|---|
type | Type of tax for the passed transaction. Possible values: COUNTRYSTATECOUNTYCITYDISTRICTDISTRICT 2 | String – ENUM | |
jurisdictionType | Type of jurisdiction for the passed transaction. Possible values:COUNTRYSTATECOUNTYCITYDISTRICTDISTRICT 2 | String – ENUM | |
authorityName | Taxing jurisdiction authority name. | String | |
cityOrCountyOrDistrict | City/County/District associated with taxing jurisdiction. | String | |
stateOrProvince | State or Province associated with taxing jurisdiction. | String | |
country | Country associated with taxing jurisdiction. | String | |
taxAmount | Tax amount for the specific jurisdiction. | BigDecimal | |
taxRate | Tax rate or the specified jurisdiction. | BigDecimal | |
exemptAmount | Exemption amount for the specified jurisdiction. | BigDecimal | |
taxableAmount | Taxable amount for the specified jurisdiction. | BigDecimal | |
messages | Messages sent by the taxing jurisdiction authority. | String – List |