List and Search Inventory
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.
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.Please utilize HTTPS when calling the API. HTTP will work–for now–but we are deprecating it.
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.
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).
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:
Size | URL |
Original | |
Thumbnail | |
Small | |
Medium | |
Large |
To list or search the inventory, make a POST request to:
https://user.traxia.com/app/api/inventory
This endpoint accepts JSON data as the query request. The query will look like this:
{
"key": "Your API Key Here",
"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", "includeItemsWithQuantityZero": "false"}' -H 'Accept: application/json' -H 'Content-Type: application/json' -X GET
Make sure you include the Accepts and Content-Type HTTP headers when making the HTTP request. They should be set to "application/json".
Parameter | Required | Description |
key | true | The API key for the location you are accessing. |
category | false | The 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. |
consignorId | false | Setting this will limit the results to only inventory for the specified consignor. |
includeOnlyEcommerceItems | false | When set to 'true' the search will only return items whose Ecommerce Item flag is set to 'true'. |
includeItemsWithQuantityZero | false | By default the results will not include inventory items that have a quantity of zero. If you want them included set this to 'true'. |
modifiedSince | false | Modified 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. |
includeInactiveItems | false | By 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. |
The API may return more HTTP response codes than these, but these are likely the ones you will run into.
Response Code | Meaning | What You Should Do |
200 | Success | Parse and Use the data that was returned from SimpleConsign |
400 | Bad Request | There 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. |
500 | Internal Server Error | |
503 | Server at Capacity | Wait and make the request at a later time while we resolve our capacity issues. |
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 Field | Description |
results | The list of items matching your request |
consignmentItem | true if this is a consignment item |
consignorId | the consignor ID of the consignor that owns this item, or null if it is store inventory |
buyersFee | the buyer's fee that which is applied to the price |
startDate | the start date of the consignment item, or null if it is store inventory |
expireDate | the expire date of the consignment item, or null if it is store inventory |
status | the status of the item: "ACTIVE", "CONVERTED", etc. |
sku | the SKU of the item |
name | the "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. |
description | the "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. |
category | the name of the category of the item |
quantity | the quantity on hand of the item |
cost | the cost in pennies / cents of the item (see warning above) |
retail | the set retail price in pennies / cents of the item (see warning above) |
discount | the current discount percentage on the item |
currentPrice | the current price of the item after the discount in pennies / cents (see warning above) |
doNotDiscount | "true" if the item should not be discounted |
brand | brand of the item |
familyGroup | the family group of a clothing item |
size | the size of a clothing item |
color | the color of a clothing item |
subtitile | the subtitile of a book item |
author | the author of a book item |
images | URL of images that have been attached to this item |
state | the 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 |
upcs | UPC codes associated with item |
dateCreated | the 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 |
lengthUnit | the 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. |
weightUnit | the 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. |
height | the height measurement of the item in inches or centimeters as a decimal number. |
width | the width measurement of the item in inches or centimeters as a decimal number. |
depth | the depth measurement of the item in inches or centimeters as a decimal number. |
weight | the weight of the item in pounds or kilograms as a decimal number. |
- Invalid API key
- You have made too many API requests in the last ten minutes
Last modified 6mo ago