List and Search Inventory

Search…
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:
1
http://image.traxia.com/<image-name>
2
https://s3.amazonaws.com/image.traxia.com/<image-name>
Copied!
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:
1
http://image.traxia.com/<thumbnail|small|medium|large>/<image-name>
2
https://s3.amazonaws.com/image.traxia.com/<thumbnail|small|medium|large>/<image-name>
Copied!
For example, for this mugshot image:
Size
URL
Original
​http://image.traxia.com/1454513967293EBAGMYYIIP7Y3EGZ8LKJ.jpg​
Thumbnail
​http://image.traxia.com/thumbnail/1454513967293EBAGMYYIIP7Y3EGZ8LKJ.jpg​
Small
​http://image.traxia.com/small/1454513967293EBAGMYYIIP7Y3EGZ8LKJ.jpg​
Medium
​http://image.traxia.com/medium/1454513967293EBAGMYYIIP7Y3EGZ8LKJ.jpg​
Large
​http://image.traxia.com/large/1454513967293EBAGMYYIIP7Y3EGZ8LKJ.jpg​
API USAGE
To list or search the inventory, make a GET or POST request to:
1
https://user.traxia.com/app/api/inventory
Copied!
Request Example
This endpoint accepts JSON data as the query request. The query will look like this:
1
{
2
   "key": "Your API Key Here",
3
   "consignorId": "123456",
4
   "includeItemsWithQuantityZero": "false"
5
}
Copied!
A Curl example would look like this:
1
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
Copied!
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
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.
HTTP Response Codes
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
Likely this is our fault, and you should email [email protected] to get the issue resolved.
503
Server at Capacity
Wait 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.
1
{
2
   "results":
3
   [
4
      {
5
         "consignmentItem":true,
6
         "consignorId":"1234567",
7
         "startDate":"10/03/2012",
8
         "expireDate":"12/02/2012",
9
         "status":"ACTIVE"
10
         "sku":"K9L28Q",
11
         "name":"Cardigan",
12
         "description":"woman's sweater",
13
         "category":"CLOTHING",
14
         "quantity":1,
15
         "cost":0,
16
         "retail":1000,
17
         "buyersFee":100,
18
         "discount":10,
19
         "currentPrice":990,
20
         "doNotDiscount":false,
21
         "familyGroup":"women",
22
         "brand":"Fashionables!"
23
         "size":"med",
24
         "color":"black",
25
         "images":[],
26
         "dateCreated": 1497289834000,
27
         "lastUpdated": 1510305307000
28
      },
29
      {
30
         "category":"GAMES",
31
         "consignmentItem":false,
32
         "quantity":4,
33
         "cost":718,
34
         "retail":1512,
35
         "buyersFee" : 0,
36
         "dicsount":0,
37
         "currentPrice":1512,
38
         "sku":"AW5NE7",
39
         "name":"Mario Bros."
40
         "dateCreated": 1500495930000,
41
         "lastUpdated": 1501574262000
42
      }
43
   ]
44
}
Copied!
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 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
Possible Errors:
Invalid API key
You have made too many API requests in the last ten minutes
API Docs
CURL Examples
Last modified 9mo ago
Copy link
Contents
Overview
Best Practice Use Pattern
HTTPS
Ecommerce Items
Product Images
Optimized Product Images