For all the examples, the command below is used with input.txt containing XML; unless otherwise specified.
curl -u 4acc660ce98b9d38d7fea10705aa1ebd7d836fe0:X \
-H "Accept: application/xml" \
-H "Content-Type: application/xml" \ "https://test_account.imonggo.com/api/invoices.xml" \
-X POST \
-d @input.txt
Specifying Invoice Date and Time
Invoice date is optional. When omitted, server will simply use current date and time. Date should be specify with UTC format (YYYY-MM-DDTHH:HH:SSZ). Although server currently supports other formats, but this may not be supported in the future.
Example:
<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>
Specifying Cashier and Salesman
You can specify cashier and salesman user the user_id and salesman_id parameter. They are both optional. If they are not specified, they will both will be defaulted to the current API user (the user who owns the API key.) The cashier is specified and the salesman is not, salesman will be defaulted to be the same as the cashier.
<invoice>
<invoice_date>2011-04-01T00:00:00Z</invoice_date>
<user_id>20</user_id>
<salesman_id>21</salesman_id>
<remark>Note that cashier of John Smith while salesman is Sarah Smith.</remark>
<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>
Specifying Customer
You can specify the customer with either customer_id or customer_name. If customer id present, customer name parameter will be ignored. When using customer id, if the server cannot find a match, the customer field will be empty and no error will be returned. When using customer name, if the customer is not yet present, a new customer will be created with the given name.
If both customer id and name are used, only customer id will be taken into consideration.
Example using customer name:
<invoice>
<invoice_date>2011-04-01T00:00:00Z</invoice_date>
<customer_name>Tony Romas</customer_name>
<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>
Example using Customer Id:
<invoice>
<customer_id>21</customer_id>
<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>
Specifying Reference and Remark
Both remark and reference are optional. If reference is specified, it should be uniquely identify the invoice in the branch. In case of duplicate reference, the server will not accept the invoice and return an error.
Example:
<invoice>
<reference>1234</reference>
<remark>This is a test invoice</remark>
<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
Specifying Discounts
You can specify both percent discount and value discount using discount_text parameter. An example of percent discount is "5%". An example of value discount is "5" meaning 5 dollar (or whatever is your base currency).
Discount_text can be used in every line. If discount text is not specified, this means the line contains no discount. Retail price is the same as the net price.
Example of percent discount:
<invoice>
<invoice_lines type="array">
<invoice_line>
<product_id>54</product_id>
<quantity>1</quantity>
<retail_price>200</retail_price>
<discount_text>5%</discount_text>
</invoice_line>
</invoice_lines>
<payments type="array">
<payment>
<amount>190</amount>
</payment>
</payments>
</invoice>
Note: 200 Less 5% is 190.
Example of value discount:
<invoice>
<invoice_lines type="array">
<invoice_line>
<product_id>54</product_id>
<quantity>1</quantity>
<retail_price>200</retail_price>
<discount_text>5</discount_text>
</invoice_line>
</invoice_lines>
<payments type="array">
<payment>
<amount>195</amount>
</payment>
</payments>
</invoice>
Note: $200 - $5 is $195.
Different Payment Types
Following payment types are supported. When payment type id not given, the server assumes cash.
PAYMENT_TYPE_ID | NAME |
1 | Cash |
2 | Credit Card |
3 | Debit Card |
4 | Gift Certificate |
5 | Check |
6 | Other |
Both check payment and credit card payment can accept additional parameters to be stored for information. Imonggo supports different 6 payment types. You can distinguish each payment type with payment_type_id. Optional tender field can be used to indicate the amount given by customer. The difference between tender and actual amount is the change.
**Example invoice with cash tender amount of 200 and amount due of 195. The implied change is 5.
<invoice>
<invoice_lines type="array">
<invoice_line>
<product_id>54</product_id>
<quantity>1</quantity>
<retail_price>195</retail_price>
</invoice_line>
</invoice_lines>
<payments type="array">
<payment>
<payment_type_id>1</payment_type_id>
<amount>195</amount>
<tender>200</tender>
</payment>
</payments>
</invoice>
Check payment
When making check payment, you can also submit along the check number in the reference field.
<invoice> <invoice_lines type="array"> <invoice_line> <product_id>54</product_id> <quantity>1</quantity> <retail_price>200</retail_price> </invoice_line> </invoice_lines> <payments type="array"> <payment> <payment_type_id>5</payment_type_id> <amount>200</amount> <reference>CHK1234</reference> </payment> </payments> </invoice>
Credit Card Payment
When specifying credit card payment, following optional fields are available:
card_first_name
card_last_name
card_last_4_digits
card_expiry_year
card_expiry_month
street
city
state
zipcode
country
54 1 200 2 John Doe
1234 2012 3 1234 Main St San Francisco
CA CA12345
US 200
Multiple Payment types
You can mix different type together in one invoice. Just make sure that the amount when added up is equal to the total invoice amount due.
Example of multiple payment with 150 cash and 50 GC.
<invoice>
<invoice_lines type="array">
<invoice_line>
<product_id>54</product_id>
<quantity>1</quantity>
<retail_price>200</retail_price>
</invoice_line>
</invoice_lines>
<payments type="array">
<payment>
<amount>150</amount>
</payment>
<payment>
<payment_type_id>4</payment_type_id>
<amount>50</amount>
</payment>
</payments>
</invoice>
Specifying Tax
Tax can be specified using invoice_tax_rates array. Each tax should have parameter of rate and amount.
By default, taxes are computed exclusive of item prices. This means that they are added to the total amount. You can use tax_inclusive parameter to override the invoice setting. When tax inclusive parameter is set to true. Taxes are not added to the total amount.
Example of tax exclusive invoice
<invoice>
<tax_inclusive>false</tax_inclusive>
<invoice_lines type="array">
<invoice_line>
<product_id>54</product_id>
<quantity>1</quantity>
<retail_price>200</retail_price>
</invoice_line>
</invoice_lines>
<invoice_tax_rates type="array">
<invoice_tax_rate>
<rate>0.1</rate>
<amount>20.0</amount>
</invoice_tax_rate>
</invoice_tax_rates>
<payments type="array">
<payment>
<amount>220</amount>
</payment>
</payments>
</invoice>
Example of tax inclusive invoice
<invoice>
<tax_inclusive>true</tax_inclusive>
<invoice_lines type="array">
<invoice_line>
<product_id>54</product_id>
<quantity>1</quantity>
<retail_price>200</retail_price>
</invoice_line>
</invoice_lines>
<invoice_tax_rates type="array">
<invoice_tax_rate>
<rate>0.1</rate>
<amount>20.0</amount>
</invoice_tax_rate>
</invoice_tax_rates>
<payments type="array">
<payment>
<amount>220</amount>
</payment>
</payments>
</invoice>
Multiple tax rates
You can specify multiple tax rates and identify each tax with the tax_rate_id. To get a list current tax rates. You can use GET /tax_settings.xml command. See this page for additional information.
Example:
Below example shows an invoice containing 2 lines. Two different taxes were also applied. Each tax rate is identified with the tax_rate_id. The 1st tax rate is 10% while the 2nd tax rate is 5%.
<invoice>
<tax_inclusive>false</tax_inclusive>
<invoice_lines type="array">
<invoice_line>
<product_id>62</product_id>
<quantity>1.0</quantity>
<retail_price>120.0</retail_price>
</invoice_line>
<invoice_line>
<product_id>63</product_id>
<quantity>1.0</quantity>
<retail_price>20.0</retail_price>
</invoice_line>
</invoice_lines>
<invoice_tax_rates type="array">
<invoice_tax_rate>
<tax_rate_id>1</tax_rate_id>
<rate>0.1</rate>
<amount>14.0</amount>
</invoice_tax_rate>
<invoice_tax_rate>
<tax_rate_id>2</tax_rate_id>
<rate>0.05</rate>
<amount>6.0</amount>
</invoice_tax_rate>
</invoice_tax_rates>
<payments type="array">
<payment>
<amount>160.0</amount>
</payment>
</payments>
</invoice>
Multiple Branch Operation
Example:
This example creates a invoice in branch identified with id 9. Valid branch refers to active branches that are not head office.
curl -u 4acc660ce98b9d38d7fea10705aa1ebd7d836fe0:X \
-H "Accept: application/xml" \
-H "Content-Type: application/xml" \ "https://test_account.imonggo.com/api/invoices.xml?branch_id=9" \
-X POST \
-d @input.txt
Customer Discount
When a customer belongs to a membership group and has discount percent, you can retrieve the discount percentage from the customer information. Your application needs to apply the discount to individual items and submit to the server. The server will not automatically apply the discount.