Create 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.

There are two requests for new transactions:

Evaluate: Issuing an Evaluate transaction call will calculate taxes on the transaction but will not maintain (persist) the request information or the response; no tax obligation is created. Examples of how this call can be used are shown in the e-commerce customer order workflows throughout this guide.
Commit: Issuing a Commit transaction call will automatically commit the new transaction to GTD. Once the transaction has been committed to GTD, it is available for reporting, filing, and remittance purposes.

HTTP Request

Evaluate

POST /api/basic-authsimple-connect-ar/v1/transactions?state=EVALUATE

Commit

POST /api/basic-authsimple-connect-ar/v1/transactions?state=COMMIT

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.
Authorization: (Required) Standard Basic-based string (optionally could be the 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.

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
`invoiceNumber`	Transaction’s document number	String	Min: 3 characters, Max: 40 characters
`invoiceDate`	Transaction’s invoice date default value; current date in UTC.	String – Date	Date format: yyyy-MM-dd
`currencyCode`	Transaction’s currency code; default value when null: `USD`.	String
`taxDirection`	1. `FORWARD`: Forward tax calculation. 2. `REVERSE`: Backward tax calculation. Default value when null: `FORWARD`	String – Enum	Accepted values: `FORWARD`/`REVERSE`
`customerCode`	Default value if line `customerId` value is null.	String	Min: 3 characters, Max: 40 characters
`exemptionReasonCode`	Default value if line `exemptionReasonCode` value is null.	String	Min: 3 characters, Max: 40 characters
`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` 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` field 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 number` element only (use `buyerRegistrationNumbers` field in JSON); list of registration objects. Default value if line registration number value is null.	List – RegistrationNumber	XML 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 – RegistrationNumber	XML 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 – RegistrationNumber	XML only.
`buyerRegistrationNumber`	JSON `registration number` field only (use `buyerRegistrationNumber` element in XML); list of registration objects. Default value if `line registration` value is null.	List – RegistrationNumber	JSON 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 – RegistrationNumber	JSON 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 – RegistrationNumber	JSON only.
`lineItem`	XML `line item` element only (use `lineItems` field in JSON); list of line items associated with 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 transaction.	List – LineItem	JSON only. Limit X number of line items.

Line Item 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: 1,000 characters
`grossAmount`	Line item gross amount.	BigDecimal	Max 20 digits Max 8 digits
`customerCode`	Line item sold to customer.	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.	Object – Address
`shipTo`	Address to which the item will be shipped.	Object – Address
`shipFrom`	Address from which the item will be shipped.	Object – Address
`discount`	XML `discount` element only (use `discounts` field in JSON); list of discounts applied to 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 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 – RegistrationNumber	XML only.
`sellerRegistrationNumber`	XML `registration number` element only (use `sellerRegistrationNumbers` field in JSON); list of registration objects.	List – RegistrationNumber	XML only.
`thirdPartyRegistrationNumber`	XML `registration number` element only (use `thirdPartyRegistrationNumbers` field in JSON); list of registration objects.	List – RegistrationNumber	XML only.
`buyerRegistrationNumbers`	JSON `registration number` field only (use `buyerRegistrationNumber` element in XML; list of registration objects.	List – RegistrationNumber	JSON only.
`sellerRegistrationNumbers`	JSON `registration number` field only (use `sellerRegistrationNumbers` element in XML); list of registration objects.	List – RegistrationNumber	JSON only.
`thirdPartyRegistrationNumbers`	JSON `registration number` field only (use `thirdPartyRegistrationNumbers` element in XML); list of registration objects.	List – RegistrationNumber	JSON only.
`creditDebitIndicator`	Depending on the `integer` value, the line will be either `debit` or `credit`.	Integer	1 (Debit), 2 (Credit)
`taxAmount`	Value for the amount of taxes already collected. Must be used ONLY when the tax direction in the header is `REVERSE`.	BigDecimal	Max 20 digits Max 8 digits
`exemptAmount`	Value for the exempt amount of the gross amount already corrected. Must be used ONLY when the tax direction in the header is `REVERSE`.	BigDecimal	Max 20 digits Max 8 digits

Discount 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 Fields

Field	Description	Data Type
`country`	Registration country	String
`status`	Status of the registration. Acceptable values: `IDENTIFIED` `ESTABLISHED` (default value) `DISTANCE_SALES` `SPECIAL_SCHEME` (digital goods) `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 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 Required
`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	Restrictions
`transactionId`	Transaction ID; used for altering transactional state.	String
`invoiceNumber`	Transaction invoice number.	String
`currencyCode`	Transaction currency code.	String
`invoiceDate`	Transaction invoice date.	String – Date	Date format: yyyy-MM-dd
`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: `SALES_TAX` `SELLERS_USE_TAX` `. . .` `OUTPUT_HARMONIZED_SALES_TAX`	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 specified jurisdiction.	BigDecimal
`taxRate`	Tax rate for 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