Customer Type API

Customer Types API allows you to retrieve the list of customer types or individual customer. You can create, update or delete an exiting customer.

Please refer Customer Type Field Table for the meaning of individual field.

LIST (GET /customer_types.xml)

Retrieve list of active customer types, both active and deleted are included. To exclude deleted customer types, use active_only parameter.

Example: Listing of customer types

Retrieve list of customer types. If you have more than 50 entries. 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/customer_types.xml"

Sample Result:

<?xml version="1.0" encoding="UTF-8"?>
<customer-types type="array">
  <customer_type>
    <discount_percent>0.05</discount_percent>
    <id>1</id>
    <name>Regular</name>
    <status></status>
    <utc_created_at>2011-04-29T03:20:33Z</utc_created_at>
    <utc_updated_at>2011-04-29T03:20:33Z</utc_updated_at>
  </customer_type>
  <customer_type>
    <discount_percent>0.1</discount_percent>
    <id>2</id>
    <name>Gold</name>
    <status></status>
    <utc_created_at>2011-04-29T03:20:40Z</utc_created_at>
    <utc_updated_at>2011-04-29T03:20:40Z</utc_updated_at>
  </customer_type>
</customer-types>

Return Codes:

• 200 OK - if successful

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

Retrieve information on single customer type. Replace {id} with the customer type id.

Example:

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

Sample result:

<?xml version="1.0" encoding="UTF-8"?>
<customer_type>
  <discount_percent>0.1</discount_percent>
  <id>2</id>
  <name>Gold</name>
  <status></status>
  <utc_created_at>2011-04-29T03:20:40Z</utc_created_at>
  <utc_updated_at>2011-04-29T03:20:40Z</utc_updated_at>
</customer_type>

Return Codes:

• 200 OK - if successful
• 404 Not found - if no customer matches the id

CREATE: (POST /customer_types.xml)

Create a new customer type. The minimum require format Please refer to this page for the supported fields.

Example:

Create a new customer type with name of Platinum and discount percent of 20%.

curl -u 4acc660ce98b9d38d7fea10705aa1ebd7d836fe0:X \
-H "Accept: application/xml" \
-H "Content-Type: application/xml" \
"https://test_account.imonggo.com/api/customer_types.xml" \
-X POST \
-d "<customer_type><name>Platinum</name><discount_text>20%</discount_text></customer_type>"

Return Codes:

• 200 OK - if successful
• 422 Un-processable Entity - if validation error occurred
• 500 Internal Server Error - if unexpected error occurred

UPDATE: (/customer/{id}.xml)

Example:

Change platinum customer type to 25% discount. Assuming the customer type id is 3.

curl -u 4acc660ce98b9d38d7fea10705aa1ebd7d836fe0:X \
-H "Accept: application/xml" \
-H "Content-Type: application/xml" \
"https://test_account.imonggo.com/api/customer_types/3.xml" \
-X PUT \
-d "<customer_type><discount_text>25%</discount_text></customer_type>"

Return Codes:

• 200 OK - if successful
• 404 Not found - if no customer matches the id
• 422 Un-processable Entity - if validation error occurred
• 500 Internal Server Error - if unexpected error occurred

DELETE: (DELETE /customer/{id}.xml)

Use this command to mark a customer as deleted. When a customer is already deleted, server will simply ignore the command and return 200 (Ok). Server will return 404 (Not found) if there is no matching customer id.

Example:

Delete customer identified with id 13.

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

Return Codes:

• 200 OK - if successful
• 404 Not found - if no customer matches the id

OTHER FEATURES (GET /customer_types.xml)

Example 1: Counting customer types

To count on the total number of customer types

curl -u 4acc660ce98b9d38d7fea10705aa1ebd7d836fe0:X \
-H "Accept: application/xml" -H "Content-Type: application/xml" \
"https://test_account.imonggo.com/api/customer_types.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 customer types only.

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

To count on the total number of customer types updated after Jan 1, 2011.

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

Example 2: Limiting customer types Listing with Last updated date

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

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

Sample Result:

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

Retrieve list of customer types updated after Dec 31, 2010.

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

Sample Result:

<?xml version="1.0" encoding="UTF-8"?>
<customer types type="array">
  <customer>
    ...
  </customer>
  <customer>
    ....
  </customer>
  ...
</customer types>

Note that we escaped space with %20 in "after=2010-12-31%2023:59".

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/customer_types.xml?q=last_upda..."

Sample Result: 

<?xml version="1.0" encoding="UTF-8"?>
<hash>
  <last_updated_at>2011-04-29 03:48:16</last_updated_at>
</hash>

Parameters for LIST (GET /customer_types.xml) ##

Page Filters

Page filters are used in LIST to limit the customer types 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 100 (e.g. per_page=10)

Date Filters

Date filtered are used in LIST to limit the customer types to be retrieved. Given date format is in "YYYY-MM-DD HH:MM:SS" specified in UTC time.

• 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 set to 1 or true, the list will exclude deleted customer types

Inquiry

• q=count - returns a number of customer types
• q=last_updated_at - returns the last updated date for your customer database

Additional Notes for Developers

1. When a customer is deleted, the status will be "D"
2. Listing returns both active and deleted customer types.
3. In case the XML is not corrected formatted, the server will return 500 (Internal server error)

Proposed Algorithm for synchronizing customer incrementally

1. Keep a local persistent variable: previous_last_updated_date (which is initially nil)
2. GET last_updated_date from server
3. GET customer types after previous_last_updated_date to last_updated_date
4. Start with page 1 until customer types return contains an empty array
5. Override local variable pervious_last_updated_date with last_updated_date

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