Invoice API

Invoice API allows you to retrieve the list of invoices or individual invoice. You can create or void an exiting invoice. Invoice cannot be updated; it can only be voided 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 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

  1. When a invoice is deleted, the status will be "D"
  2. Listing returns both active and deleted invoices.
  3. In case the XML is not corrected formatted, the server will return 500 (Internal server error)
  4. Last updated at is different from invoice date

Parameter validation

  1. If invalid user id is passed, an error will be returned
  2. If invalid salesman id is passed, an error will be returned
  3. When invalid invoice date is passed, current date time is used
  4. If invalid customer id is passed, customer will be assigned as nil
  5. When an existing customer name is passes, customer will not be re-created

Proposed Algorithm for synchronizing invoice incrementally

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