You can create or void an existing invoice. Invoice cannot be updated; it can only be voiced or canceled. Once canceled, it cannot be undone.
It is important to note the Invoice API always operates within the context of a specific branch. In case of single branch setup, there is no need to pass the branch id parameter; however, in multi-branch setting, you need to indicate which branch by passing the branch_id. Valid branches are active branches that are not head office.
Please refer to Invoice Field Table for the meaning of individual field.
For advanced features, please refer to Advanced Usage of Invoice API article.
LIST (GET /invoices.xml)
Example 1: Listing of invoices
Retrieve list of invoices (only page 1 (first 50) of the invoices 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/invoices.xml"
Sample Result:
<?xml version="1.0" encoding="UTF-8"?>
<invoices type="array">
<invoice>
...
</invoice>
<invoice>
....
</invoice>
...
</invoices>
Sample result (if contents is empty):
<invoices/>
Example 2: Listing with page and per_page parameter
To retrieve page 1 of invoices 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/invoices.xml?page=1"
To retrieve page 2 of the invoices list:
curl -u 4acc660ce98b9d38d7fea10705aa1ebd7d836fe0:X \
-H "Accept: application/xml" -H "Content-Type: application/xml" \ "https://test_account.imonggo.com/api/invoices.xml?page=2"
To retrieve page 1 of the invoices list with page size of 50
curl -u 4acc660ce98b9d38d7fea10705aa1ebd7d836fe0:X \ -H "Accept: application/xml" -H "Content-Type: application/xml" \ "https://test_account.imonggo.com/api/invoices.xml?page=1&per_page=50"
Return Codes
CODE/STATUS | CONDITION |
200 OK | if successful |
GET (GET /invoice/{id}.xml)
Retrieve information on single invoice. Replace {id} with the invoice id. Please refer this page for return field information and meaning.
Note that invoice no is different from invoice id. Invoice no is sequential number generated within each branch while invoice id is unique number assign to the invoice within your account. Invoice no is visible to regular user while invoice id is only visible to the API and programmers.
Example 1:
curl -u 4acc660ce98b9d38d7fea10705aa1ebd7d836fe0:X \
-H "Accept: application/xml" \
-H "Content-Type: application/xml" \ "https://test_account.imonggo.com/api/invoices/179.xml"
Sample result: <?xml version="1.0" encoding="UTF-8"?>
<invoice>
<amount>-100.0</amount>
<amount_with_tax>-100.0</amount_with_tax>
<discount_text nil="true"></discount_text>
<id>179</id>
<invoice_no>1</invoice_no>
<layaway_status></layaway_status>
<quantity>-1.0</quantity>
<reference></reference>
<remark></remark>
<status>S</status>
<tax>0.0</tax>
<tax_inclusive>false</tax_inclusive>
<voided_reason nil="true"></voided_reason>
<customer_name nil="true"></customer_name>
<customer_id nil="true"></customer_id>
<utc_invoice_date>2011-04-12 10:22:20</utc_invoice_date>
<utc_post_date>2011-04-12 10:22:20</utc_post_date>
<invoice_tax_rates type="array"/>
<payments type="array">
<payment>
<amount>-100.0</amount>
<card_first_name nil="true"></card_first_name>
<card_last_4_digits nil="true"></card_last_4_digits>
<card_last_name nil="true"></card_last_name>
<card_type nil="true"></card_type>
<city nil="true"></city>
<country nil="true"></country>
<payment_type_id>1</payment_type_id>
<state nil="true"></state>
<street nil="true"></street>
<tender>-100.0</tender>
<payment_type_name>Cash</payment_type_name>
</payment>
</payments>
<invoice_lines type="array">
<invoice_line>
<discount_text></discount_text>
<line_no nil="true"></line_no>
<price>100.0</price>
<product_id>53</product_id>
<quantity>-1.0</quantity>
<retail_price>100.0</retail_price>
<subtotal>-100.0</subtotal>
<product_name>item 1</product_name>
<product_stock_no>1</product_stock_no>
</invoice_line>
</invoice_lines>
</invoice>
Return Codes:
CODE/STATUS | CONDITION |
200 OK | if successful |
404 Not found | if no invoice matches the id |
CREATE: (POST /invoices.xml)
Create a new invoice. The minimum required format, Please refer to this page for the supported fields.
Example:
Create an a simple invoice with one item with retail of price 100 and no discount. Payment is assumed cash. Note the invoice date is specified in UTC format.
curl -u 428d2622b1e717236418762c0c676def22d947dc:X \
-H "Accept: application/xml" \
-H "Content-Type: application/xml" \ "https://test_account.imonggo.com/api/invoices.xml" \
-X POST \
-d @input.txt
Contents of input.txt
<invoice>
<invoice_date>2011-04-01T00:00:00Z</invoice_date>
<invoice_lines type="array">
<invoice_line>
<product_id>54</product_id>
<quantity>1</quantity>
<retail_price>100</retail_price>
</invoice_line>
</invoice_lines>
<payments type="array">
<payment>
<amount>100</amount>
</payment>
</payments>
</invoice>
Sample result:
<?xml version="1.0" encoding="UTF-8"?>
<hash>
<id type="integer">240</id>
</hash>
For complete usage of creating invoice, please refer to this page.
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 |
CANCEL OR VOID: (DELETE /invoice/{id}.xml)
Use this command to cancel or void. When a invoice is already deleted, server will simply ignore the command and return 200 (Ok). Server will return 404 (Not found) if there is no matching invoice id.
You are require to specify a reason for cancelation. Optionally, you can indicate the user who cancel using the user_id parameter.
Example 1:
Delete invoice identified with id 13.
curl -u 4acc660ce98b9d38d7fea10705aa1ebd7d836fe0:X \
-H "Accept: application/xml" -H "Content-Type: application/xml" \ "https://test_account.imonggo.com/api/invoices/436.xml?reason=wrong%20booking" \
-X DELETE
Return Codes:
CODE/STATUS | CONDITION |
200 OK | if successful |
404 Not found | if no invoice matches the id |
422 Un-processable Entity | if validation invoice is already cancelled |
OTHER FEATURES (GET /invoices.xml)
Example 1: Counting Invoices
To count on the total number of invoices
curl -u 4acc660ce98b9d38d7fea10705aa1ebd7d836fe0:X \
-H "Accept: application/xml" -H "Content-Type: application/xml" \ "https://test_account.imonggo.com/api/invoices.xml?q=count"
Sample Result:
<?xml version="1.0" encoding="UTF-8"?>
<hash>
<count type="integer">7</count>
</hash>
Example 2: Limiting invoices listing with last updated date
To inquire on the total number of invoices updated from April 1, 2011 to present.
curl -u 4acc660ce98b9d38d7fea10705aa1ebd7d836fe0:X \
-H "Accept: application/xml" -H "Content-Type: application/xml" \ "https://test_account.imonggo.com/api/invoices.xml?q=count&from=2011-04-1"
Sample Result:
<?xml version="1.0" encoding="UTF-8"?>
<hash>
<count type="integer">1</count>
</hash>
Retrieve list of invoices updated after Dec 31, 2010.
curl -u 4acc660ce98b9d38d7fea10705aa1ebd7d836fe0:X \
-H "Accept: application/xml" -H "Content-Type: application/xml" \ "https://test_account.imonggo.com/api/invoices.xml?after=2010-12-31%2023:59"
Sample Result:
<?xml version="1.0" encoding="UTF-8"?>
<invoices type="array">
<invoice>
...
</invoice>
<invoice>
....
</invoice>
...
</invoices>
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/invoices.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>
Parameters for LIST (GET /invoices.xml) ##
Page Filters
Page filters are used in LIST to limit the invoices 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 invoices to be retrieved. Given date format is in "YYYY-MM-DD HH:MM:SS" specified in UTC time. Invalid date format will cause internal server error (status code: 500).
before: updated date < given date
after: updated date > given date
from: updated date >= give date
to: updated date <= give date
Inquiry
q=count - returns a number of invoices
q=last_updated_at - returns the last updated date of your last posted or cancelled invoice
Additional Notes for Developers
When a invoice is deleted, the status will be "D"
Listing returns both active and deleted invoices.
In case the XML is not corrected formatted, the server will return 500 (Internal server error)
Last updated at is different from invoice date
Parameter validation
If invalid user id is passed, an error will be returned
If invalid salesman id is passed, an error will be returned
When invalid invoice date is passed, current date time is used
If invalid customer id is passed, customer will be assigned as nil
When an existing customer name is passes, customer will not be re-created
Proposed Algorithm for synchronizing invoice incrementally
Keep a local persistent variable: previous_last_updated_date (which is initially nil)
GET last_updated_date from server
GET invoices after previous_last_updated_date to last_updated_date
Start with page 1 until invoices return contains an empty array
Override local variable pervious_last_updated_date with last_updated_date
Note: When invoices downloaded contains status D, you should delete the local copy of the invoice if present.