Please refer to the Product Fields table for meaning and usage of individual fields.

LIST (GET/products.xml)

Retrieve list of active products, both active and deleted products are included. To exclude deleted products, use active_only parameter. Each call returns only 1 page worth of records. The default and maximum page size is 50.

Example 1: Listing of Products

Retrieve list of products. Only page 1 or first 50 records will be returned. You can use page parameter to return more pages.

curl -u 4acc660ce98b9d38d7fea10705aa1ebd7d836fe0:X \ 
-H "Accept: application/xml" \ 
-H "Content-Type: application/xml" \ "https://test_account.imonggo.com/api/products.xml" 

Sample Result: 
<?xml version="1.0" encoding="UTF-8"?> 
<products type="array"> 
  <product> 
     ... 
  </product> 
  <product> 
     .... 
  </product> 
 ... 
</products> 

Sample result (when empty): 
<products/>

Example 2: Listing with page and per_page parameter

To retrieve page 1 of products with default page size of 50.

curl -u 4acc660ce98b9d38d7fea10705aa1ebd7d836fe0:X \ 
-H "Accept: application/xml" -H "Content-Type: application/xml" \ "https://test_account.imonggo.com/api/productsx.xml?page=1"

To retrieve page 2 of the products list:

curl -u 4acc660ce98b9d38d7fea10705aa1ebd7d836fe0:X \ 
-H "Accept: application/xml" -H "Content-Type: application/xml" \ "https://test_account.imonggo.com/api/products.xml?page=2"

Example 3: Listing of Active Products Only

This parameter is useful when you are retrieving a complete set of active products only. If you are retrieving the updated product list, it is important to include the delete products so that you know when to delete the local version of the products.

curl -u 4acc660ce98b9d38d7fea10705aa1ebd7d836fe0:X \ 
-H "Accept: application/xml" \ 
-H "Content-Type: application/xml" \ "https://test_account.imonggo.com/api/products.xml?active_only=1"

Return Codes

CODE/STATUS	CONDITION
200 OK	if successful

GET (GET/products/{id}.xml)

Retrieve information on a single product. Replace {id} with the product id.

Example 1:

curl -u 4acc660ce98b9d38d7fea10705aa1ebd7d836fe0:X \ 
-H "Accept: application/xml" \ 
-H "Content-Type: application/xml" \ "https://test_account.imonggo.com/api/products.xml" \ 
-X POST \ 
-d "<product><name>Nokia E72</name><stock_no>E72</stock_no><retail_price>200</retail_price></product>" 

Sample result (when succcessful): 
<?xml version="1.0" encoding="UTF-8"?> 
<product> 
  <allow_decimal_quantities>false</allow_decimal_quantities>
  <cost>0.0</cost> 
  <description nil="true"></description> 
  <disable_discount>false</disable_discount>
  <disable_inventory>false</disable_inventory> 
  <enable_open_price>false</enable_open_price> 
  <id>59</id> 
  <name>Nokia E71</name> 
  <retail_price>200.0</retail_price> 
  <status nil="true"></status> 
  <stock_no>E71</stock_no> 
  <tax_exempt>false</tax_exempt> 
  <tag_list></tag_list> 
  <barcode_list></barcode_list> 
  <utc_created_at>2011-04-12T11:10:10Z</utc_created_at>  
  <utc_updated_at>2011-04-12T11:10:10Z</utc_updated_at> 
  <thumbnail_url></thumbnail_url> 
  <branch_prices type="array"/> 
  <tax_rates type="array"/> 
</product> 

Sample result (with errors): 
<?xml version="1.0" encoding="UTF-8"?> 
<errors> 
  <error>Name is already used by another product with a different stock no </error> 
  <error>Stock no has already been taken</error> 
</errors>

Return Codes:

CODE/STATUS	CONDITION
200 OK	if successful
422 Un-processable Entity	if validation error occurred
500 Internal Service Error	If unexpected error occurred

UPDATE (PUT /product/{id}.xml)

Example 1:

Change the product cost to 199 and retail price to 299.95. The product is identified with id of 53.

curl -u 4acc660ce98b9d38d7fea10705aa1ebd7d836fe0:X \ 
-H "Accept: application/xml" \ 
-H "Content-Type: application/xml" \ "https://test_account.imonggo.com/api/products/53.xml" \ 
-X PUT \ 
-d "<product><cost>999</cost><retail_price>9999</retail_price></product>"

Disable discounting for product with id 53

curl -u 4acc660ce98b9d38d7fea10705aa1ebd7d836fe0:X \ 
-H "Accept: application/xml" \ 
-H "Content-Type: application/xml" \ "https://test_account.imonggo.com/api/products/53.xml" \ 
-X PUT \ 
-d "<product><disable_discount>true</disable_discount></product>"

Return Codes:

CODE/STATUS	CONDITION
200 OK	if successful
404 Not Found	if no product matches the id
422 Un-processable Entity	if validation error occurred
500 Internal Service Error	if unexpected error occurred

DELETE (DELETE /product{id}.xml)

Use this command to mark a product as deleted.

Example 1:

Delete product identified with id 59.

curl -I -u 4acc660ce98b9d38d7fea10705aa1ebd7d836fe0:X \ 
-H "Accept: application/xml" -H "Content-Type: application/xml" \ "https://test_account.imonggo.com/api/products/599.xml" \ 
-X DELETE

Return Codes:

CODE/STATUS	CONDITION
200 OK	if successful
404 Not Found	if no product matches the id

Parameters for LIST (GET /products.xml)

Page Filters

Page filters are used in LIST to limit the products to be retrieved. You can combine page filter with data filters (_before_, after, from and to).

before: updated date < given date
after: updated date > given date
from: update date >= give date
to: updated date <= give date

Status Filter

active_only: when setup to 1 to true, the list will exclude deleted products

Inquiry

q=count - returns a number of products
q=list_updated_at - return the last updated date for your product database.

More Examples

Example 1: Counting Products

To count on the total number of active products

curl -u 4acc660ce98b9d38d7fea10705aa1ebd7d836fe0:X \ 
-H "Accept: application/xml" 
-H "Content-Type: application/xml" \ "https://test_account.imonggo.com/api/products.xml?q=count" 

Sample Result: 
<?xml version="1.0" encoding="UTF-8"?> 
<hash> 
  <count type="integer">7</count> 
</hash>

To count on the total number of active products updated after Jan 1, 2011.

curl -u 4acc660ce98b9d38d7fea10705aa1ebd7d836fe0:X \ 
-H "Accept: application/xml" -H "Content-Type: application/xml" \ "https://test_account.imonggo.com/api/products.xml?q=count&after=2011-01-01T00:00:00Z"

Example 2: Limiting Products Listing with Last Updated Date

To inquire on the total number of products updated after April 1, 2011.

curl -u 4acc660ce98b9d38d7fea10705aa1ebd7d836fe0:X \ 
-H "Accept: application/xml" -H "Content-Type: application/xml" \ "https://test_account.imonggo.com/api/products.xml?q=count&after=2011-04-1T00:00:00Z" 

Sample Result: 
<?xml version="1.0" encoding="UTF-8"?> 
<hash> 
  <count type="integer">1</count> 
</hash>

Retrieve list of products updated after Dec 31, 2010.

curl -u 4acc660ce98b9d38d7fea10705aa1ebd7d836fe0:X \ 
-H "Accept: application/xml" -H "Content-Type: application/xml" \ "https://test_account.imonggo.com/api/products.xml?after=2010-12-31T23:59:00Z" 

Sample Result: 
<?xml version="1.0" encoding="UTF-8"?> 
<products type="array"> 
  <product> 
    ... 
  </product> 
  <product> 
    .... 
  </product> 
  ... 
</products>

Example 3: Last Updated At

To inquire on the last updated date, use q=last_updated_at

curl -u 4acc660ce98b9d38d7fea10705aa1ebd7d836fe0:X \ 
-H "Accept: application/xml" -H "Content-Type: application/xml" \ "https://test_account.imonggo.com/api/products.xml?q=last_updated_at" 

Sample Result: 
<?xml version="1.0" encoding="UTF-8"?> 
<hash> 
  <last-updated-at>2011-04-13 04:37:45</last-updated-at> 
</hash>

Additional Notes for Developers

When a product is deleted, the status will be "D"
Listing returns both active and deleted products.
In case the XML is malformed, the server will return 500 (Internal server error)

Proposed Algorithm for synchronizing product incrementally

Keep a local persistent variable: previous_last_updated_date (which is initially nil).
GET last_dated_date from server.
GET products after previous_last_updated_date to last_updated_date.
Start with page 1 until products return contains an empty array.
Override local variable previous_last_dated_date with last_updated_date.

Note: When products downloaded contains status D, you should delete the local copy of the product if present.

Products API allows you to retrieve the list of products or individual product. You can create, update or delete an existing product. Please refer to Product Fields table for meaning and usage of individual field.

LIST (GET /products.xml)

Retrieve list of active products, both active and deleted are included. To exclude deleted products, use active_only parameter. Each call returns only 1 page worth of records. The default and maximum page size is 50.

Example 1: Listing of Products

Retrieve list of products. Only page 1 or first 50 records will be returned. You can use page parameter to return more pages.

curl -u 4acc660ce98b9d38d7fea10705aa1ebd7d836fe0:X \
-H "Accept: application/xml" \
-H "Content-Type: application/xml" \
"https://test_account.imonggo.com/api/products.xml"

Sample Result:
<?xml version="1.0" encoding="UTF-8"?>
<products type="array">
  <product>
    ...
  </product>
  <product>
    ....
  </product>
  ...
</products>

Sample result (when empty): 
<products/>

Example 2: Listing with page and per_page parameter

To retrieve page 1 of products with default page size of 50.

curl -u 4acc660ce98b9d38d7fea10705aa1ebd7d836fe0:X \
-H "Accept: application/xml" -H "Content-Type: application/xml" \
"https://test_account.imonggo.com/api/productsx.xml?page=1"

To retrieve page 2 of the products list:

curl -u 4acc660ce98b9d38d7fea10705aa1ebd7d836fe0:X \
-H "Accept: application/xml" -H "Content-Type: application/xml" \
"https://test_account.imonggo.com/api/products.xml?page=2"

Example 3: Listing of Active Products Only

curl -u 4acc660ce98b9d38d7fea10705aa1ebd7d836fe0:X \
-H "Accept: application/xml" \
-H "Content-Type: application/xml" \
"https://test_account.imonggo.com/api/products.xml?active_only=1"

Return Codes:

200 OK - if successful

GET (GET /products/{id}.xml)

Retrieve information on single product. Replace {id} with the product id.

Example 1:

curl -u 4acc660ce98b9d38d7fea10705aa1ebd7d836fe0:X \
-H "Accept: application/xml" \
-H "Content-Type: application/xml" \
"https://test_account.imonggo.com/api/products/53.xml"

Sample result:
<?xml version="1.0" encoding="UTF-8"?>
<product>
  <allow_decimal_quantities>false</allow_decimal_quantities>
  <cost>90.0</cost>
  <description nil="true"></description>
  <disable_discount>false</disable_discount>
  <disable_inventory>false</disable_inventory>
  <enable_open_price>false</enable_open_price>
  <id>53</id>
  <name>Sample Item 1</name>
  <retail_price>100.0</retail_price>
  <status nil="true"></status>
  <stock_no>1</stock_no>
  <tax_exempt>false</tax_exempt>
  <tag_list></tag_list>
  <barcode_list></barcode_list>
  <utc_created_at>2011-04-12T10:21:50Z</utc_created_at>
  <utc_updated_at>2011-04-12T10:21:50Z</utc_updated_at>
  <thumbnail_url></thumbnail_url>
  <branch_prices type="array"/>
  <tax_rates type="array"/>
</product>

Return Codes:

CODE/STATUS	CONDITION
200 OK	if successful
404 Not Found	if no product matches the id

CREATE (POST /products.xml)

Create a new product. The minimum required fields are name, stock_no and retail_price.

Example 1:

Create an item name of "Nokia" with stock_no of "E71" and retail_price of $200.

curl -u 4acc660ce98b9d38d7fea10705aa1ebd7d836fe0:X \
-H "Accept: application/xml" \
-H "Content-Type: application/xml" \
"https://test_account.imonggo.com/api/products.xml" \
-X POST \
-d "<product><name>Nokia E72</name><stock_no>E72</stock_no><retail_price>200</retail_price></product>" 

Sample result (when succcessful):
<?xml version="1.0" encoding="UTF-8"?>
<product>
  <allow_decimal_quantities>false</allow_decimal_quantities>
  <cost>0.0</cost>
  <description nil="true"></description>
  <disable_discount>false</disable_discount>
  <disable_inventory>false</disable_inventory>
  <enable_open_price>false</enable_open_price>
  <id>59</id>
  <name>Nokia E71</name>
  <retail_price>200.0</retail_price>
  <status nil="true"></status>
  <stock_no>E71</stock_no>
  <tax_exempt>false</tax_exempt>
  <tag_list></tag_list>
  <barcode_list></barcode_list>
  <utc_created_at>2011-04-12T11:10:10Z</utc_created_at>
  <utc_updated_at>2011-04-12T11:10:10Z</utc_updated_at>
  <thumbnail_url></thumbnail_url>
  <branch_prices type="array"/>
  <tax_rates type="array"/>
</product>

Sample result (with errors):    
<?xml version="1.0" encoding="UTF-8"?>
<errors>
  <error>Name is already used by another product with a different stock no.</error>
  <error>Stock no has already been taken</error>
</errors>

Return Codes:

CODE/STATUS	CONDITION
200 OK	if successful
422 Un-processable Entity	if validation error occurred
500 Internal Server Error	if unexpected error occurred

UPDATE (PUT /product/{id}.xml)

Example 1:

Change the product cost to 199 and retail price to 299.95. The product is identified with id of 53.

curl -u 4acc660ce98b9d38d7fea10705aa1ebd7d836fe0:X \
-H "Accept: application/xml" \
-H "Content-Type: application/xml" \
"https://test_account.imonggo.com/api/products/53.xml" \
-X PUT \
-d "<product><cost>999</cost><retail_price>9999</retail_price></product>"

Disable discounting for product with id 53.

curl -u 4acc660ce98b9d38d7fea10705aa1ebd7d836fe0:X \
-H "Accept: application/xml" \
-H "Content-Type: application/xml" \
"https://test_account.imonggo.com/api/products/53.xml" \
-X PUT \
-d "<product><disable_discount>true</disable_discount></product>"

Make the product tax exempt.

curl -u 4acc660ce98b9d38d7fea10705aa1ebd7d836fe0:X \
-H "Accept: application/xml" \
-H "Content-Type: application/xml" \
"https://test_account.imonggo.com/api/products/53.xml" \
-X PUT \
-d "<product><tax_exempt>true</tax_exempt></product>"

Return Codes:

CODE/STATUS	CONDITION
200 OK	if successful
404 Not Found	if no product matches the id
422 Un-processable Entity	if validation error occurred
500 Internal Server Error	if unexpected error occurred

DELETE (DELETE /product/{id}.xml)

Use this command to mark a product as deleted.

Example 1:

Delete product identified with id 59.

curl -I -u 4acc660ce98b9d38d7fea10705aa1ebd7d836fe0:X \
-H "Accept: application/xml" -H "Content-Type: application/xml" \
"https://test_account.imonggo.com/api/products/599.xml" \
-X DELETE

Return Codes:

CODE/STATUS	CONDITION
200 OK	if successful
404 Not Found	if no product matches the id

Parameters for LIST (GET /products.xml)

Page Filters

Page filters are used in LIST to limit the products to be retrieved. You can combined page filter with date Filters (_before_, after, from and to).

page: default of 1 (eg. page=1)
per_page: any number between 1 to 50 (e.g. per_page=10)

Date Filters

Date filtered are used in LIST to limit the products to be retrieved. Date format must be given in UTC date/time format ("YYYY-MM-DDTHH:MM:SSZ").

before: updated date < given date
after: updated date > given date
from: updated date >= give date
to: updated date <= give date

Status Filter

active_only: when setup to 1 to true, the list will exclude deleted products

Inquiry

q=count - returns a number of products
q=last_updated_at - returns the last updated date for your product database

More Examples

Example 1: Counting Products

To count on the total number of active products

curl -u 4acc660ce98b9d38d7fea10705aa1ebd7d836fe0:X \
-H "Accept: application/xml" -H "Content-Type: application/xml" \
"https://test_account.imonggo.com/api/products.xml?q=count"

Sample Result:

<?xml version="1.0" encoding="UTF-8"?>
<hash>
  <count type="integer">7</count>
</hash>

To count on the total number of active products updated after Jan 1, 2011.

curl -u 4acc660ce98b9d38d7fea10705aa1ebd7d836fe0:X \
-H "Accept: application/xml" -H "Content-Type: application/xml" \
"https://test_account.imonggo.com/api/products.xml?q=count&after=2011-01-01T00:00:00Z"

Example 2: Limiting Products Listing with Last updated date

To inquire on the total number of products updated after April 1, 2011

curl -u 4acc660ce98b9d38d7fea10705aa1ebd7d836fe0:X \
-H "Accept: application/xml" -H "Content-Type: application/xml" \
"https://test_account.imonggo.com/api/products.xml?q=count&after=2011-04-1T00:00:00Z"

Sample Result:
<?xml version="1.0" encoding="UTF-8"?>
<hash>
  <count type="integer">1</count>
</hash>

Retrieve list of products updated after Dec 31, 2010.

curl -u 4acc660ce98b9d38d7fea10705aa1ebd7d836fe0:X \
-H "Accept: application/xml" -H "Content-Type: application/xml" \
"https://test_account.imonggo.com/api/products.xml?after=2010-12-31T23:59:00Z"

Sample Result:
<?xml version="1.0" encoding="UTF-8"?>
<products type="array">
  <product>
    ...
  </product>
  <product>
    ....
  </product>
  ...
</products>

Example 3: Last Updated At

To inquire on the last updated date, use q=last_updated_at

curl -u 4acc660ce98b9d38d7fea10705aa1ebd7d836fe0:X \
-H "Accept: application/xml" -H "Content-Type: application/xml" \
"https://test_account.imonggo.com/api/products.xml?q=last_updated_at"

Sample Result: 
<?xml version="1.0" encoding="UTF-8"?>
<hash>
  <last-updated-at>2011-04-13 04:37:45</last-updated-at>
</hash>

Additional Notes for Developers

When a product is deleted, the status will be "D"
Listing returns both active and deleted products.
In case the XML is malformed, the server will return 500 (Internal server error)

Proposed Algorithm for synchronizing product incrementally

Keep a local persistent variable: previous_last_updated_date (which is initially nil)
GET last_updated_date from server
GET products after previous_last_updated_date to last_updated_date
Start with page 1 until products return contains an empty array
Override local variable pervious_last_updated_date with last_updated_date

Note: When products downloaded contains status D, you should delete the local copy of the product if present.