Product API

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

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 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:

  • 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:

  • 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:

  • 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:

  • 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:

  • 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

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

Proposed Algorithm for synchronizing product incrementally

  1. Keep a local persistent variable: previous_last_updated_date (which is initially nil)
  2. GET last_updated_date from server
  3. GET products after previous_last_updated_date to last_updated_date
  4. Start with page 1 until products return contains an empty array
  5. 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.

Recent Discussions

29 Dec, 2016 10:36 AM
30 Sep, 2016 06:57 AM
13 May, 2016 12:21 PM
01 May, 2016 11:56 PM
26 Apr, 2016 11:30 AM