Submit Online Transactions and Online Returns

The Online Transactions API allows you to record external sales and returns with SimpleConsign, such as those placed via an ecommerce site. Version 1 of this API only recorded sales, did not record returns, and did not record the external e-commerce order/invoice number. Version 2 of this API introduced the ability to do returns. To do returns, you must record the order/invoice number (orderNumber) on both the sale and the return. Any sale without an orderNumber cannot be returned later. The only difference between version 1 and 2 of the API is whether you include the order type and orderNumber or not. Version 1 API calls will continue to work with the Version 2 API, with the exception about returns noted above.To submit a transaction, submit a POST request to
1
https://user.traxia.com/app/api/transaction
Copied!
Submit Online Sale/Return Transaction - Request Example
This URL receives a JSON post, the request will look like this:
HTTP Requests
Make sure you set the Accept and Content-Type HTTP headers to "application/json" when making the HTTP request.
Online Sale Transaction of two SKUs with different quantities for online order/invoice # "1234".
1
{ 
2
   "key":"Your API key here",
3
   "orderNumber":"1234",
4
   "type":"SALE",
5
   "nonTaxableSaleTotal": 7998,
6
   "taxableSaleTotal": 0,
7
   "tax": 0,
8
   "items": [
9
      {
10
         "sku": "GFFY72",
11
         "price": 5400,
12
         "quantity": 1
13
      },
14
      {
15
         "sku": "AD4J56",
16
         "price": 1299,
17
         "quantity": 2
18
      }
19
   ]
20
}
Copied!
Online Return Transaction of one SKU with a quantity of 2 items for online order/invoice # "1234"
1
{ 
2
   "key":"Your API key here",
3
   "orderNumber":"1234",
4
   "type":"RETURN",
5
   "nonTaxableSaleTotal": 2598,
6
   "taxableSaleTotal": 0,
7
   "tax": 0,
8
   "items": [
9
      {
10
         "sku": "AD4J56",
11
         "price": 1299,
12
         "quantity": 2
13
      }
14
   ]
15
}
Copied!
How Traxia Handles Money Values
When working with monetary values, Traxia stores and passes the values as integers. For example, a dollar decimal value of $42.42 multiplied by 100 to convert to integer, and then stored or passed as 4242. When a monetary value is displayed, we convert back by dividing by 100 to go from 4242 to 42.42. This is necessary because differences in how decimal values are handled in different architectures and languages like JavaScript. There is the possibility of losing precision otherwise.
You must follow this same pattern when sending nonTaxableSaleTotal, taxableSaleTotal, tax and price to the Online Transaction and Online Return API. Please convert your dollars to cents when calling the API. If not, then your dollar value of 42.42 will be sent to SimpleConsign, be divided by 100, and become .4242 and not 42.42.
Online Sale/Return Transaction - Request Parameters
Parameter
Required
Description
key
true
the API key for the location you are accessing
type
v1: false; v2: true
the type of transaction as SALE or RETURN. This is now required in version 2 of this API, and must be included if you intend to record Sales and Returns with SimpleConsign. If you continue to use the version 1 API, you can exclude this field, but will not be able to do Returns.
orderNumber
v1: false; v2: true
a string that is the online order/invoice # of the SALE or RETURN. This is now required in version 2 of this API, and must be included if you intend to record Sales and Returns with SimpleConsign. If you continue to use the version 1 API, you can exclude this field, but will not be able to do Returns. NOTE: The order/invoice number must be unique in the system. You can have sale order # 1234, and multiple returns for # 1234, but you cannot have multiple sales with the same number. Note: we require a string datatype here as some systems utilize alphanumeric order numbers.
nonTaxableSaleTotal
true
the total in pennies/cents of non taxable sale items (see note above)
taxableSaleTotal
true
the total in pennies/cents of the taxable sale items (see note above)
tax
true
the total iin pennies/cents of tax collected (see note above)
items
false
a list of items in this transaction
sku
true
the Simple Consign SKU of the item being sold or returned, this must be a SKU from the Simple Consign system. NOTE: If there were multiple line items of this SKU in the order or return, they must be consolidated into ONE line item in the Online Transaction API call. For example, if your systems allows an order to have SKU ABC as lines two and four, each with a quantity of one, then the online transaction call expects one line item for SKU ABC and a quantity of two.
price
true
amount in pennies/cents the item was sold for (see note above)
quantity
true
the number of this item that was sold or is being returned
A successful transaction will get a response like this:
1
{
2
   "success": true
3
}
Copied!
1
​
Copied!
If an error occurred you will get an error response like this:
1
{
2
   "success": false,
3
   "error": "error message here"
4
}
Copied!
Error Checking
We highly recommend that you check the API responses for error conditions, and not assume that the call will work. The following errors are possible:
invalid API key
too many API requests in the last ten minutes
this location's price plan is not authorized for API access
could not find item with SKU
taxableSaleTotal and nonTaxableSaleTotal is $0.00
transaction item is missing a SKU
total of items price does not match transaction sub total
taxableSaleTotal is greater than zero, but no tax was collected
taxableSaleTotal is zero, but tax was collected
transaction type must be either 'SALE' or 'RETURN' (triggered only if the type or orderNumber fields are included in the data)
a unique order/invoice number (orderNumber) from the remote service must be provided (triggered only if the type or orderNumber fields are included in the data)
the type of transaction (SALE or RETURN) must be provided for an orderNumber
an online SALE transaction already exists for the provided orderNumber
could not find original online SALE transaction for the provided orderNumber to be returned  
PHP Examples
Partner Status Pages
Last modified 8mo ago
Copy link
Contents
Submit Online Sale/Return Transaction - Request Example
Online Sale/Return Transaction - Request Parameters
Error Checking