Page tree
Skip to end of metadata
Go to start of metadata
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


https://user.traxia.com/app/api/transaction

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

{ 
   "key":"Your API key here",
   "orderNumber":"1234",
   "type":"SALE",
   "nonTaxableSaleTotal": 7998,
   "taxableSaleTotal": 0,
   "tax": 0,
   "items": [
      {
         "sku": "GFFY72",
         "price": 5400,
         "quantity": 1
      },
      {
         "sku": "AD4J56",
         "price": 1299,
         "quantity": 2
      }
   ]
}


Online Return Transaction of one SKU with a quantity of 2 items for online order/invoice # "1234"

{ 
   "key":"Your API key here",
   "orderNumber":"1234",
   "type":"RETURN",
   "nonTaxableSaleTotal": 2598,
   "taxableSaleTotal": 0,
   "tax": 0,
   "items": [
      {
         "sku": "AD4J56",
         "price": 1299,
         "quantity": 2
      }
   ]
}

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

ParameterRequiredDescription
keytrue

the API key for the location you are accessing

typev1: 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.
nonTaxableSaleTotaltruethe total in pennies/cents of non taxable sale items (see note above)
taxableSaleTotaltruethe total in pennies/cents of the taxable sale items (see note above)
taxtruethe total iin pennies/cents of tax collected (see note above)
itemsfalsea list of items in this transaction
skutruethe 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.
pricetrueamount in pennies/cents the item was sold for (see note above)
quantitytruethe number of this item that was sold or is being returned

A successful transaction will get a response like this:


{
   "success": true
}
 
If an error occurred you will get an error response like this:


{
   "success": false,
   "error": "error message here"
}

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

  • No labels