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/xml or application/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
`country`	Registration country.	String
`status`	Status of the registration. Acceptable values: `IDENTIFIED` `ESTABLISHED` (default value) `DISTANCE_SALES` `SPECIAL_SCHEME` `VOLUNTARY_USE_TAX` `ESTABLISHED_UNION_SCHEME` (EU only)	String – Enum
`jurisdictionType`	Type of jurisdiction for the given registration. Acceptable values: `COUNTRY` (default value) `STATE` `COUNTY` `CITY` `DISTRICT` `DISTRICT 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
`status`	HTTP status code.	Integer
`message`	General response message.	String
`data`	Main calculation response data.	Object – Invoice

Invoice Fields

Field	Description	Data Type
`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
`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
`type`	Type of tax for the passed transaction. Possible values: `COUNTRY` `STATE` `COUNTY` `CITY` `DISTRICT` `DISTRICT 2`	String – ENUM
`jurisdictionType`	Type of jurisdiction for the passed transaction. Possible values: `COUNTRY` `STATE` `COUNTY` `CITY` `DISTRICT` `DISTRICT 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