Partners can also directly create or delete branches, switch account from free, to trial or premium.

API URL:

https://api.imonggo.com/api/partner/accounts

API Functions Supported

SN

API FUNCTION

DESCRIPTION

1

create

create a new account (POST)

2

delete

delete an account (DELETE)

3

show

retrieve account information (GET)

6

subscribe_trial

upgrade account to trial (PUT)

7

subscribe_premium

subscribe account and all branches to premium membership (PUT)

8

unsubscribe_premium

cancel premium subscription (PUT)

9

show_subscriptions

retrieve list of subscriptions under an account (GET)

10

show_branches

retrieve list a branches under an account (GET)

11

create_branch

create a new branch, an associated subscription will be added (PUT)

12

delete_branch

delete a branch and its associated subscription (PUT)

13

create_user

create a new user

14

update_user

update a user

15

delete_user

delete an existing user

16

show_users

shows a list of users under this account

17

show_user_api_token

show user api token

Terms and Definitions

  • Account - an account can have multiple branches and multiple subscriptions

  • Branch - a retail branch where sales can be recorded and inventories tracked

  • Subscription - premium subscription, each premium branch will have a corresponding subscription

  • Free Account - Imonggo free account has limitation of 1 user, 1 branch, as well other feature limitations

  • Trial Account - Imonggo trial account has all the functions and features of premium account, but only supports up to 1000 products

  • Premium Account - Imonggo premium account can have multiple users, multiple branches and has the full feature and functions

Statuses

  • A - Active

  • I - Inactive

  • D - Deleted

This flag can be applicable to account, branch and subscription.

Subscription Type

  • 0 - Free

  • 1 - Trial

  • 2 - Premium

Return Codes

CODE/STATUS

CONDITION

200 OK

if successful

404 Not Found

if no account matches the id

422 Un-processable Entity

if validation error occurred

500 Internal Server Error

if unexpected error occurred

Create (POST)


Create a new account.

Required Fields:

  • name - account name - a-z, 0-9 only, 5 to 30 characters

  • email - email valid email, must not own any existing imonggo account

  • user_name - account owner name

  • user_password - account owner password

Optional Fields

  • street

  • city

  • zipcode

  • state

  • country

  • telephone

The country codes and US states can be found here.

Example:

curl -u partner_user_id:partner_key \ 
-H "Accept: application/xml" \
-H "Content-Type: application/xml" \ "https://api.myimonggo.com/api/partner/accounts.xml" \
-X POST \
-d "<account><name>test119</name><user_name>John Smity</user_name><user_password>12345</user_password><email>john@smith.com</email></account>"

Return XML:

<?xml version="1.0" encoding="UTF-8"?>
<account>
<city nil="true"></city>
<country nil="true"></country>
<email>john@smith.com</email>
<id>1051</id>
<name>test119</name>
<state nil="true"></state>
<street nil="true"></street>
<subscription_type>0</subscription_type>
<telephone nil="true"></telephone>
<user_name>John Smity</user_name>
<zipcode>NA</zipcode>
<utc_created_at nil="true"></utc_created_at>
<utc_updated_at nil="true"></utc_updated_at>
</account>

You should take note of the account id.

Show (GET)


Returns information about an account.

Example:

curl -u partner_user_id:partner_key \ 
-H "Accept: application/xml" \
-H "Content-Type: application/xml" \ "https://api.myimonggo.com/api/partner/accounts/1051.xml"

Return XML:

<?xml version="1.0" encoding="UTF-8"?> 
<account>
<city nil="true"></city>
<country nil="true"></country>
<email>john@smith.com</email>
<id>1051</id>
<name>test119</name>
<state nil="true"></state>
<street nil="true"></street>
<subscription_type>0</subscription_type>
<telephone nil="true"></telephone>
<user_name>John Smity</user_name>
<zipcode>NA</zipcode>
<utc_created_at>2013-07-28T23:11:25Z</utc_created_at>
<utc_updated_at>2013-07-28T23:11:25Z</utc_updated_at>
</account>

Subscribe Trial (PUT)


Upgrade an existing free account to trial. After account is upgraded, you can create additional branches.

Example:

curl -u partner_user_id:partner_key \ 
-H "Accept: application/xml" \
-H "Content-Type: application/xml" \ "https://api.myimonggo.com/api/partner/accounts/1053/subscribe_trial.xml" \ -X PUT

Return XML:

<?xml version="1.0" encoding="UTF-8"?> 
<account>
<city nil="true"></city>
<country nil="true"></country>
<email>john@smith.com</email>
<id>1053</id>
<name>test119</name>
<state nil="true"></state>
<street nil="true"></street>
<subscription_type>1</subscription_type>
<telephone nil="true"></telephone>
<user_name>John Smity</user_name>
<zipcode>NA</zipcode>
<utc_created_at>2013-07-28T23:29:12Z</utc_created_at>
<utc_updated_at>2013-07-28T23:35:38Z</utc_updated_at>
</account>

*Note: notice the resulting subscription_type is now 1.

Reset Trial (PUT)


Trial status will only be active for 30 day; then the account will automatically be downgraded to free account if not upgraded to premium. Second trial will not be allowed unless you reset the internal trial flag. Reset trial allows you to reset the internal trial flag to allow another trial.

During the trial period, the users can create any number of branches.

Example:

curl -u partner_user_id:partner_key \ 
-H "Accept: application/xml" \
-H "Content-Type: application/xml" \ "https://api.myimonggo.com/api/partner/accounts/1053/reset_trial.xml" \
-X PUT

Subscribe Premium (PUT)


Subscribe an existing free or trial account to premium membership.

Example:

curl -u partner_user_id:partner_key \ 
-H "Accept: application/xml" \
-H "Content-Type: application/xml" \ "https://api.myimonggo.com/api/partner/accounts/1053/subscribe_premium.xml" \
-X PUT

Return XML:

<?xml version="1.0" encoding="UTF-8"?> 
<account>
<city>ZZ</city>
<country nil="true"></country>
<email>john@smith.com</email>
<id>1053</id>
<name>test119</name>
<state nil="true"></state>
<street nil="true"></street>
<subscription_type>2</subscription_type>
<telephone nil="true"></telephone>
<user_name>John Smity</user_name>
<zipcode>NA</zipcode>
<utc_created_at>2013-07-28T23:29:12Z</utc_created_at>
<utc_updated_at>2013-07-30T00:11:17Z</utc_updated_at>
</account>

Note: Notice subscription_type should be changed to 2 (Premium Account).

Show Subscriptions (GET)


Returns a list of subscriptions, active or in-active. A subscription becomes in-active when its associated branch is deleted.

Example:

curl -u partner_user_id:partner_key \ -H "Accept: application/xml" \ -H "Content-Type: application/xml" \ "https://api.myimonggo.com/api/partner/accounts/1053/show_subscriptions.xml"

Return XML:

<?xml version="1.0" encoding="UTF-8"?> <account-subscriptions type="array"> <account_subscription> <amount>30.0</amount> <branch_id>1138</branch_id> <reference></reference> <status>A</status> <utc_created_at>2013-07-30T00:14:33Z</utc_created_at> <utc_updated_at>2013-07-30T00:14:33Z</utc_updated_at> <utc_subscribed_at>2013-07-30T00:14:33Z</utc_subscribed_at> <utc_canceled_at nil="true"></utc_canceled_at> </account_subscription> </account-subscriptions>

Notice that the subscription status should now be "I" - indicating in-active.

Unsubscribe Premium (PUT)


Unsubscribe a premium account. The account will be converted to free account. Since free account only support single branch, all branches except owner's home branch will be deleted.

Example:

curl -u partner_user_id:partner_key \ 
-H "Accept: application/xml" \
-H "Content-Type: application/xml" \ "https://api.myimonggo.com/api/partner/accounts/1053/unsubscribe_premium.xml" \
-X PUT

Return XML:

<?xml version="1.0" encoding="UTF-8"?> 
<account>
<city>ZZ</city>
<country nil="true"></country>
<email>john@smith.com</email>
<id>1053</id>
<name>test119</name>
<state nil="true"></state>
<street nil="true"></street>
<subscription_type>0</subscription_type>
<telephone nil="true"></telephone>
<user_name>John Smity</user_name>
<zipcode>NA</zipcode>
<utc_created_at>2013-07-28T23:29:12Z</utc_created_at>
<utc_updated_at>2013-07-30T00:12:38Z</utc_updated_at>
</account>

Note: Notice subscription_type should be changed back to 0 (FREE account).

Create Branch (PUT)


Create a new branch.

Example:

curl -u partner_user_id:partner_key \ 
-H "Accept: application/xml" \
-H "Content-Type: application/xml" \ "https://api.myimonggo.com/api/partner/accounts/1053/create_branch.xml" \
-X PUT \
-d "<branch><name>San Francisco 1</name><zipcode>1234</zipcode></branch>"
  • Required fields: name - branch name

  • Optional Fields: street, city, zipcode, country, state, telephone, tin

Show Branches (GET)


Returns a list of branches, including deleted branches.

Example:

curl -u partner_user_id:partner_key \ 
-H "Accept: application/xml" \
-H "Content-Type: application/xml" \ "https://api.myimonggo.com/api/partner/accounts/1053/show_branches.xml"

Return XML:

<?xml version="1.0" encoding="UTF-8"?> 
<branches type="array">
<branch>
<city nil="true"></city>
<country nil="true"></country>
<id>1138</id>
<name>Branch 1</name>
<site_type nil="true"></site_type>
<state nil="true"></state>
<street nil="true"></street>
<subscribed_at nil="true"></subscribed_at>
<subscription_type>0</subscription_type>
<tin nil="true"></tin>
<zipcode nil="true"></zipcode>
<utc_created_at>2013-07-28T23:29:12Z</utc_created_at>
<utc_updated_at>2013-07-28T23:29:12Z</utc_updated_at>
</branch>
</branches>

Delete Branch (PUT)


Delete a branch and cancel the associated subscription. Deleting branch is only possible if the account is in premium or trial membership mode.

Example:

curl -u partner_user_id:partner_key \ 
-H "Accept: application/xml" \
-H "Content-Type: application/xml" \ "https://api.myimonggo.com/api/partner/accounts/1053/delete_branch.xml" \
-X PUT \
-d "<branch><id>1138</id></branch>"

Delete (DELETE)


Delete an account together with the associated branches and subscriptions. After deletion, the account status will be changed to 'D' and all the associated data will be deleted. Subscriptions will also be terminated (marked as 'I').

Example:

curl -u partner_user_id:partner_key \ -H "Accept: application/xml" \ -H "Content-Type: application/xml" \ "https://api.myimonggo.com/api/partner/accounts/1053.xml" \ -X DELETE

WARNING!!!

This action will delete all the data associated with the account. This action is not REVERSIBLE.

Create User (PUT)


Create a new user. When an account is created, a default user is created automatically. Additional users can be created if the account is on trial or premium subscription.

Example:

curl -u partner_user_id:partner_key \ 
-H "Accept: application/xml" \
-H "Content-Type: application/xml" \ "https://api.myimonggo.com/api/partner/accounts/1053/create_user.xml" \
-X PUT \
-d "<user><name>john01</name><password>12345</password><email>john01@imonggo2.com</email></user>"
  • Required fields: name, email, password

  • Optional Fields: role_id, home_branch_id, if not specified the default role is owner, default home branch is the same as owner's home branch.

Roles

  • 1 - Cashier

  • 2 - Supervisor

  • 3 - Manager

  • 4 - Owner

Show User API Token (GET)


Displays user API token. This token can be used to perform API login.

Example:

curl -u partner_user_id:partner_key \ 
-H "Accept: application/xml" \
-H "Content-Type: application/xml" \ "https://api.myimonggo.com/api/partner/accounts/1053/show_user_api_token.xml?user_id=1282"

Update User (PUT)


Updates the user.

Example:

Change user email to john.smith@smith.com and role to cashier.

curl -u partner_user_id:partner_key \ 
-H "Accept: application/xml" \
-H "Content-Type: application/xml" \ "https://api.myimonggo.com/api/partner/accounts/1053/udpate_user.xml" \
-X PUT \
-d "<user><id>1282</id><email>john.smith@smith.com</email><role_id>1</role_id></user>"

Delete User (PUT)


Deletes an user given the user id.

Example:

Delete user with id of 1282.

curl -u partner_user_id:partner_key \ 
-H "Accept: application/xml" \
-H "Content-Type: application/xml" \ "https://api.myimonggo.com/api/partner/accounts/1053/delete_use.xml" \
-X PUT \
-d "<user><id>1282</id></user>"

Show Users (GET)


Display list of all users under the account.

Example:

curl -u partner_user_id:partner_key \ 
-H "Accept: application/xml" \
-H "Content-Type: application/xml" \ "https://api.myimonggo.com/api/partner/accounts/1053/show_users.xml"
Did this answer your question?