Page tree
Skip to end of metadata
Go to start of metadata

Overview

The List and Search API allows you to search and pull down inventory records so you can load that data into your system.

Though you can search in real-time, this API is not optimized for that purpose and the API caps the number of searches you can do per hour.

Best Practice Use Pattern

The pattern we encourage you to use is:


Main initial load:

  • Pull all items down (but do not include inactive items: includeInactiveItems=false)
  • Then process the JSON as inserts to your database

 

Subsequent loads:
  • Pull down items modified since the "last" load (using modifiedSince) and now include inactive items (includeInactiveItems=true)
  • Then process the JSON data into your database:
    • Update existing active items
    • Insert new active items
    • Delete inactive items (which are marked as deleted in SimpleConsign)
  • Store off the timestamp of the beginning of this load to use as the "last" load timestamp to begin on your next run. NOTE: This step is critical to get right. If you store the timestamp at the end of a run, then there may be items you miss loading on the next run. It is probably a good idea to take the last load timestamp and subtract 5 or 15 minutes. This will mean the last load and the next load will always overlap and you may process some items twice, which is not a big deal, but you will not miss any either, which is a big deal.

 

The subsequent loads using modifiedSince are much smaller as they only include what changed since the "last" load. If things get out of sync, depending on how you write the code for the subsequent loads, you can often just set the modifiedSince date for the last load further back in time and run again. How often you run these types of loads is up to you and your business requirements. Some users do "modified since" loads (not full loads!) every five minutes, and some do hourly.

HTTPS

Please utilize HTTPS when calling the API. HTTP will work–for now–but we are deprecating it.

Ecommerce Items

In SimpleConsign, users have the option of flagging items as "E-commerce" items. Using the "includeOnlyEcommerceItems" option of the API you can subset your data loads to only include these flagged items.

 

Auto-flagging E-commerce Items

  • SimpleConsign includes an option under Settings/Options for Locations to automatically flag an inventory or consignment item as an E-commerce Item when an image is added to that item. The image may be added via the SimpleConsign media tab for the item, or using the SimpleConsign Photo app for iOS and Android.
  • For companies that add images to an item as their last step before releasing the item to their e-commerce site, this can save the step of going back to the item to flag it. This is particularly true when using the SimpleConsign Photo app for iOS and Android, to upload images to an item.
  • This option may not work for companies that have additional work flow steps after they take pictures for an item, and they do not want an item to be loaded via the API until a later step.

 

Item Names and Descriptions

  • Inventory and consignment items in SimpleConsign have a "Name" and a "Description/Extra Information" field associated with them. By default, these fields will be selected as the "Name" and "Description" fields delivered by this API.
  • However, since SimpleConsign is a Point-of-Sale system, and not a consumer-facing E-commerce system, the "Name" and "Description/Extra Information" fields have often been used as internal use only fields. Often, historically, the content in these fields is not usable and sometimes not acceptable, to be displayed in an E-commerce site.
  • To address the need for fields dedicated to the purpose of E-commerce, SimpleConsign added "E-commerce Name" and "E-commerce Description" fields on inventory and consignment items. These fields are only available and enabled if an item is flagged as an E-commerce item.
  • If "E-commerce Name" is populated with a value, then this API will deliver that value as the "Name" field. Otherwise, the API will default to the original SimpleConsign "Name" field's value, if any.
  • If "E-commerce Description" is populated with a value, then this API will deliver that value as the "Description" field. Otherwise, the API will default to the original SimpleConsign "Description/Extra Information" field's value, if any.

Product Images

The images field returned in the search data includes a comma-separated list of image names stored for an inventory item (up to four images currently).
You can access the original image uploaded to SimpleConsign at: 
http://image.traxia.com/<image-name>
https://s3.amazonaws.com/image.traxia.com/<image-name>
The original images uploaded by users can be the following supported types (.png, .jpg, .jpeg, .gif, .tiff, and .bmp).

Optimized Product Images

Currently we create optimized versions of JPG/JPEG images when the original image is uploaded. We will extend support for optimizing other formats, particularly PNG in the future.

The original image is never changed.

When a JPEG product image is uploaded, we do the following:
  • Make thumbnail, small, medium and large versions of the JPEG. We only resize the image for width, and maintain the image's aspect ratio. If the image's original width is smaller than the target size's width, then we do not resize the image for that target size, but rather maintain the image's original width. For example, if an image is 800px wide, we just use that width for a "large" image rather than upsize to 900px wide. We never upsize images.
    • Thumbmail is 125px wide.
    • Small is 300px wide.
    • Medium is 600px wide.
    • Large is 900px wide.
  • We optimize the image to reduce its size, but do so conservatively to reduce loss of quality.

You can access the optimized images at:

http://image.traxia.com/<thumbnail|small|medium|large>/<image-name>
https://s3.amazonaws.com/image.traxia.com/<thumbnail|small|medium|large>/<image-name>

 

For example, for this mugshot image: 

API USAGE

To list or search the inventory, make a GET or POST request to:

 

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

Request Example

This endpoint accepts JSON data as the query request.  The query will look like this:

 

{
   "key": "Your API Key Here",
   "query": "some query", 
   "consignorId": "123456",
   "includeItemsWithQuantityZero": "false"
}

 

A Curl example would look like this:

curl 'https://user.traxia.com/app/api/inventory/' --data '{ "key": "MY API KEY HERE", "query": "SOME SEARCH DATA", "includeItemsWithQuantityZero": "false"}' -H 'Accept: application/json' -H 'Content-Type: application/json' -X GET

HTTP Requests

Make sure you include the Accepts and Content-Type HTTP headers when making the HTTP request. They should be set to "application/json".

Request Parameters

ParameterRequiredDescription
keytrueThe API key for the location you are accessing.
queryfalseAny text you want to filter your results by. This could be a SKU, item name, category etc.
categoryfalseThe name of a category from SimpleConsign. This will cause that only items in that category will be returned. If the category name is not found for your company in SimpleConsign, then an error will be returned by the API.
consignorIdfalse

Setting this will limit the results to only inventory for the specified consignor.

includeOnlyEcommerceItemsfalseWhen set to 'true' the search will only return items whose Ecommerce Item flag is set to 'true'.
includeItemsWithQuantityZerofalseBy default the results will not include inventory items that have a quantity of zero. If you want them included set this to 'true'.
modifiedSincefalseModified implies that the item's record was created, updated, or marked Inactive. This parameter takes a UNIX-style timestamp, which we define as "Milliseconds since the Epoch." The datetime value is a UTC date and time. For example, if I have a UTC timestamp for Fri, 06 Nov 2015 18:17:56 GMT, the milliseconds value would be 1446833876000. Therefore, adding this parameter to the API search ("modifiedSince": "1446833876000") would return a store's items that were changed since November 6, 2015 at 18:17:56 UTC.
includeInactiveItemsfalseBy default, items that have been "deleted," or, more accurately, marked Inactive, are not included in API search results. By setting this to true, Inactive items are included in the results. The state value of an item is now included in the results. The possible state values are "A" (active) and "I" (inactive). For example: "includeInactiveItems: "true". This parameter is designed to be used with "modifedSince" (see above). By using the combination of modifedSince and includeInactiveItems, the user can retrieve all items that have been created, updated or "deleted" since a given date and time.

HTTP Response Codes

The API may return more HTTP response codes than these, but these are likely the ones you will run into.

Response CodeMeaningWhat You Should Do
200SuccessParse and Use the data that was returned from SimpleConsign
400Bad RequestThere is something wrong with the parameters that you sent in. You need to adjust the request so that the SimpleConsign API can understand your request. This can also be caused by not setting the Accepts and Content-Type headers to application/json.
500Internal Server ErrorLikely this is our fault, and you should email support@traxia.com to get the issue resolved.
503Server at CapacityWait and make the request at a later time while we resolve our capacity issues.

 

The Response

The API will return data in the JSON format.

{
   "results":
   [
      {
         "consignmentItem":true,
         "consignorId":"1234567",
         "startDate":"10/03/2012",
         "expireDate":"12/02/2012",
         "status":"ACTIVE"
         "sku":"K9L28Q",
         "name":"Cardigan",
         "description":"woman's sweater",
         "category":"CLOTHING",
         "quantity":1,
         "cost":0,
         "retail":1000,
		 "buyersFee":100,
         "discount":10,
         "currentPrice":990,
         "doNotDiscount":false,
         "familyGroup":"women",
         "brand":"Fashionables!"
         "size":"med",
         "color":"black",
         "images":[],
		 "dateCreated": 1497289834000,
		 "lastUpdated": 1510305307000
      },
      {
         "category":"GAMES",
         "consignmentItem":false,
         "quantity":4,
         "cost":718,
         "retail":1512,
		 "buyersFee" : 0,
         "dicsount":0,
         "currentPrice":1512,
         "sku":"AW5NE7",
         "name":"Mario Bros."
		 "dateCreated": 1500495930000,
		 "lastUpdated": 1501574262000
      }
   ]
}

How Traxia Handles Monetary 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.

You must follow this same pattern when reading cost, retail and current price in the Inventory API response below. Please convert the pennies / cents that the API sends you back to dollars by dividing by 100. If not, then your retail value in cents of 4242 will become $4242.00 in your e-commerce system rather than $42.42.

Response Parameters

Response FieldDescription
resultsThe list of items matching your request
consignmentItemtrue if this is a consignment item
consignorIdthe consignor ID of the consignor that owns this item, or null if it is store inventory
buyersFeethe buyer's fee that which is applied to the price
startDatethe start date of the consignment item, or null if it is store inventory
expireDatethe expire date of the consignment item, or null if it is store inventory
statusthe status of the item: "ACTIVE", "CONVERTED", etc.
skuthe SKU of the item
namethe "E-commerce Name" of the item in SimpleConsign if the item is flagged as an E-commerce Item and if the "E-commerce Name" field has a value. Otherwise, this is the "Name" of the item in SimpleConsign. See "Item Names and Descriptions" Tip up above.
descriptionthe "E-commerce Description" of the item in SimpleConsign if the item is flagged as an E-commerce Item and if the "E-commerce Description" field has a value. Otherwise, this is the "Name" of the item in SimpleConsign. See "Item Names and Descriptions" Tip up above.
categorythe name of the category of the item
quantitythe quantity on hand of the item
costthe cost in pennies / cents of the item (see warning above)
retailthe set retail price in pennies / cents of the item (see warning above)
discountthe current discount percentage on the item
currentPricethe current price of the item after the discount in pennies / cents (see warning above)
doNotDiscount

"true" if the item should not be discounted

brandbrand of the item
familyGroupthe family group of a clothing item
sizethe size of a clothing item
colorthe color of a clothing item
subtitilethe subtitile of a book item
authorthe author of a book item
imagesURL of images that have been attached to this item
statethe state of the item is either "A" (Active) or "I" (Inactive). Inactive items only appear when using the includeInactiveItems=true
ecommerceItem

the item is flagged as an ecommerce item

upcsUPC codes associated with item
dateCreatedthe date the item was created in SimpleConsign, represented as milliseconds since the Epoch in UTC time
lastUpdated

the date the item was last updated in SimpleConsign, represented as milliseconds since the Epoch in UTC time

lengthUnitthe unit used for this item's length-based measurements (height, width, and depth). Possible values are 'IN' (Imperial Inch) or 'CM' (Metric Centimeter). The unit used for a given item is determined by the current value of "Use Metric Units For Shipping" Company Option in SimpleConsign when the item is created in the system.
weightUnitthe unit used for this item's weight measurement. Possible values are 'LBS' (Imperial Pounds) or 'KG' (Metric Kilogram). The unit used for a given item is determined by the current value of "Use Metric Units For Shipping" Company Option in SimpleConsign when the item is created in the system.
heightthe height measurement of the item in inches or centimeters as a decimal number.
widththe width measurement of the item in inches or centimeters as a decimal number.
depththe depth measurement of the item in inches or centimeters as a decimal number.
weightthe weight of the item in pounds or kilograms as a decimal number.


Possible Errors:

  • Invalid API key
  • You have made too many API requests in the last ten minutes
  • No labels