Hook up your own application with The Machine's functionality.

invoice.new

This method let you add a new invoice. You can also add a client and payment, send and download the invoice.

You call this method with the following URL:

Parameters

Parameters are the data you will pass with the call.

api_token

Your secret identifier. You find your API Token under Account Overview in the Account section.

Rules: Required.

client

The ID of the client you want to invoice. If you want to add a new client on the fly you should use the new_client parameter instead. If you use both the client and new_client parameter this parameter will be ignored.

Rules: Required if you don't use the the new_client parameter.

new_client

If this parameter is used it will ignore the client parameter and add a new client instead.

Rules: Required if you don't use the the client parameter. If parameter is used it must be set to "true". Otherwise it will be ignored.

new_client_name

The new client's name.

Rules: Required if you add a new client. If parameter is used the new_client parameter must be set to "true". Otherwise it will be ignored.

new_client_email

The new client's email.

Rules: Required if you add a new client. The email must be in a valid email format. If parameter is used the new_client parameter must be set to "true".

new_client_company (optional)

The new client's company.

Rules: If this parameter is not specified it will use the client's name as a company. If parameter is used the new_client parameter must be set to "true". Otherwise it will be ignored.

new_client_address_line_01 (optional)

The new client's address line 1.

Rules: If parameter is used the new_client parameter must be set to "true".

new_client_address_line_02 (optional)

The new client's address line 2.

Rules: If parameter is used the new_client parameter must be set to "true".

new_client_city (optional)

The new client's city.

Rules: If parameter is used the new_client parameter must be set to "true".

new_client_zip_code (optional)

The new client's zip code.

Rules: If parameter is used the new_client parameter must be set to "true".

new_client_state (optional)

The new client's state.

Rules: If parameter is used the new_client parameter must be set to "true".

new_client_country

The new client's country.

Rules: If parameter is used the new_client parameter must be set to "true". Must be set to a supported country. Please see the list of supported countries.

new_client_tax_id (optional)

The new client's Tax ID (VAT).

Rules: If parameter is used the new_client parameter must be set to "true".

date (optional)

The new client's Tax ID (VAT).

Rules: The date must be formatted as "YYYY-MM-DD". If this parameter is not specified it will use the current date.

invoice_id (optional)

The Invoice ID. Please note that the invoice_id is not the same as the id of an invoice.

Rules: If this parameter is not specified it will generate a Invoice ID based of your last invoice.

po (optional)

P.O Number for the invoice.

Rules: None.

due (optional)

The number of days until the the invoice is due.

Rules: Must be a natural number or set to "immediately" if you want the invoice to be due immediately. If this parameter is not set it will use the default due from your Settings.

tax (optional)

If this parameter is set to "true", the invoice will use the tax rate either specified in the tax_rate parameter or the default tax rate from your Settings.

Rules: If used, it must be set to "true", otherwise it will be ignored.

tax_rate (optional)

The tax rate in procent for the invoice.

Rules: Can only include numeric characters. If this parameter is not specified and the tax parameter is set, it will use the default tax rate from your Settings. The parameter will be ignored if the tax parameter is not set to "true".

discount (optional)

If this parameter is set to "true", the invoice will use the discount rate either specified in the tax_rate parameter or the default tax rate from your Settings.

Rules: If used, it must be set to "true", otherwise it will be ignored.

discount_rate (optional)

The discount rate in procent for the invoice.

Rules: Can only include numeric characters. If this parameter is not specified and the discount parameter is set, it will use the default discount rate from your Settings. The parameter will be ignored if the discount parameter is not set to "true".

shipping

If this parameter is set to "true", the invoice will use the shipping amount either specified in the shipping_amount parameter or the default shipping amount from your Settings.

Rules: If used, it must be set to "true", otherwise it will be ignored.

shipping_amount (optional)

The shipping amount for the invoice.

Rules: Can only include numeric characters. If this parameter is not specified and the shipping parameter is set, it will use the default shipping amount from your Settings. The parameter will be ignored if the shipping parameter is not set to "true".

currency_symbol (optional)

The leading currency symbol you want to use.

Rules: If this parameter is not set, it will use the default currency symbol from your Settings. If used, it must be set to a supported currency symbol. Otherwise it will be ignored. Please see the list of supported currency symbols.

currency_code (optional)

The trailing currency code you want to use.

Rules: If this parameter is not set, it will use the default currency code from your Settings. If used, it must be set to a supported currency code. Otherwise it will be ignored. Please see the list of supported currency codes.

language (optional)

The language for the invoice template you want to use.

Rules: If this parameter is not set, it will use the default language from your Settings. If used, it must be set to a supported language. Otherwise it will be ignored. Please see the list of supported languages.

display_country (optional)

You can chose if you want the country to be visible in the address.

Rules: If this parameter is not set, it will use the default from your Settings. If used, it must be set to either "true" or "false" otherwise it will be ignored.

notes (optional)

Any invoice notes.

Rules: If you don't want to include a note at all, you can set this parameter to "none".

line[1][qty]

Qty for the line.

Rules: Can only include numeric characters. You add multiple lines by increasing the [1] number for each line.

line[1][kind]

Kind for the line.

Rules: Must be set to a supported kind. The supported kinds are "hour", "day", "service" and "product". You add multiple lines by increasing the [1] number for each line.

line[1][description]

Description for the line.

Rules: You add multiple lines by increasing the [1] number for each line.

line[1][price]

Price for the line.

Rules: Can only include numeric characters. You add multiple lines by increasing the [1] number for each line.

get (optional)

If this parameter is set the result sent back will be the new invoice in XML data rather than the success message.

Rules: If parameter is used it must be set to "true". Otherwise it will be ignored. If the download parameter is set this parameter will be ignored.

download (optional)

If this parameter is set the result sent back will be a the a link to download the invoice in PDF format.

Rules: If parameter is used it must be set to "true". Otherwise it will be ignored. If used, the get parameter will be ignored.

send (optional)

Let you chose if you want the new invoice to be sent by email to the client. The status of the invoice will then be changed to "Sent".

Rules: If used, it must be set to ''true". Otherwise it will be ignored.

send_attach (optional)

If you chose to send the invoice you can attach the invoice as a PDF file in the email.

Rules: If used, it must be set to "true", the send parameter must also be set to "true". Otherwise it will be ignored.

send_copy (optional)

If you chose to send the invoice you can send a copy to yourself. The copy will be sent to the email address specified in your account.

Rules: If used, it must be set to "true", the send parameter must also be set to "true". Otherwise it will be ignored.

send_subject (optional)

If you chose to send the invoice you can specify the subject of the email.

Rules: If this parameter is not set it will use your default send invoice subject from your Settings.

send_message (optional)

If you chose to send the invoice you can specify the message for the email.

Rules: If this parameter is not set it will use your default send invoice message from your Settings.

payment (optional)

Let you add a payment on the fly. If the payment amount is more or equal to the total amount of the invoice, the status of the invoice will be changed to "Paid".

Rules: Should be the amount of the payment. Can only include numeric characters.

Return Values

This is the result that will be passed back to you when you have sent a call.

Success

Success: Invoice added.

The invoice was successfully added.

If you have set the get parameter to "true" you will rather get the new invoice in XML sent back to you. Like this:

<?xml version="1.0" encoding="utf-8"?>
<request method="invoice.get">
    <invoice>
        <id>205092</id>
        <status>Paid</status>
        <date>15 Jan 2009</date>
        <due_date>16 Feb 2009</due_date>
        <invoice_id>0000004</invoice_id>
        <po></po>
        <due>30</due>
        <tax_rate>0.00</tax_rate>
        <discount_rate>0.00</discount_rate>
        <shipping_amount>0.00</shipping_amount>
        <currency_symbol>$</currency_symbol>
        <currency_code></currency_code>
        <notes>Thank you!</notes>
        <permalink>http://machine_id.invoicemachine.com/invoice/view/24192915345543</permalink>
        <download_link>http://machine_id.invoicemachine.com/invoice/download/24192915345543</download_link >
        <payment_link>http://machine_id.invoicemachine.com/invoice/payment/24192915345543</payment_link >
        <client_id>204607</client_id>
        <client_name>Sample Contact</client_name>
        <client_email>sample@invoicemachine.com</client_email>
        <client_company>Sample Company, Inc.</client_company>
        <client_address_line_01>35181 Invoice Street</client_address_line_01>
        <client_address_line_02></client_address_line_02>
        <client_city>Invoice City</client_city>
        <client_zip_code>92329</client_zip_code>
        <client_state>CA</client_state>
        <client_country>United States</client_country>
        <client_tax_id></client_tax_id>
        <your_name>Your Name</your_name>
        <your_email>your@email.com</your_email>
        <your_company>Your Company</your_company>
        <your_address_line_01>Your Address</your_address_line_01>
        <your_address_line_02></your_address_line_02>
        <your_city>Your City</your_city>
        <your_zip_code>33018</your_zip_code>
        <your_state></your_state>
        <your_country>United States</your_country>
        <your_tax_id></your_tax_id>
        <lines>
            <line>
                <qty>2</qty>
                <kind>hours</kind>
                <description>Web design</description>
                <price>120.00</price>
                <total>240.00</total>
            </line>
            <line>
                <qty>8</qty>
                <kind>hours</kind>
                <description>Web development</description>
                <price>120.00</price>
                <total>960.00</total>
            </line>
        </lines>
        <subtotal>1200.00</subtotal>
        <tax>0.00</tax>
        <discount>0.00</discount>
           <shipping>0.00</shipping>
        <total>1200.00</total>
        <paid>1200.00</paid>
        <balance_due>0.00</balance_due>	
    </invoice>
</request>

If you have set the get download to "true" you will rather get the new invoice's download link sent back to you. Like this:

http://machine_id.invoicemachine.com/invoice/download/24192915345543

Error

Error: No data passed.

No data was passed to the method.

Error: API Token is invalid.

The API Token parameter is missing or incorrectly entered.

Error: Client is invalid.

The client parameter is missing or incorrectly entered.

Error: New Client Name is invalid.

The new client name parameter is missing or incorrectly entered.

Error: New Client Email is invalid.

The new client email parameter is missing or incorrectly entered.

Error: New Client Country is invalid.

The new client country parameter is missing or incorrectly entered.

Error: Date is invalid.

The date parameter is incorrectly entered.

Error: Due is invalid.

The due parameter is incorrectly entered.

Error: Tax Rate is invalid.

The tax rate parameter is incorrectly entered.

Error: Discount Rate is invalid.

The discount rate parameter is incorrectly entered.

Error: Shipping Amount is invalid.

The shipping amount parameter is incorrectly entered.

Error: Currency Symbol is invalid.

The currency symbol parameter is incorrectly entered.

Error: Currency Code is invalid.

The currency code parameter is incorrectly entered.

Error: Language is invalid.

The language parameter is incorrectly entered.

Example

The example below is strictly a demonstration of the method and it's parameters. Methods should never be posted from a HTML form. They should be posted directly from your server script.

<form action="http://machine_id.invoicemachine.com/api/invoice.new" method="post">
    <input type="hidden" name="api_token" value="c86cea54c71sbb05a5f8297bed641944">
    <input type="hidden" name="client" value="204607">
    <input type="hidden" name="date" value="2009-01-15">
    <input type="hidden" name="due" value="30">
    <input type="hidden" name="currency_symbol" value="dollar">
    <input type="hidden" name="line[1][qty]" value="2">
    <input type="hidden" name="line[1][kind]" value="hour">
    <input type="hidden" name="line[1][description]" value="Web design">
    <input type="hidden" name="line[1][price]" value="120">
    <input type="hidden" name="line[2][qty]" value="8">
    <input type="hidden" name="line[2][kind]" value="hour">
    <input type="hidden" name="line[2][description]" value="Web development">
    <input type="hidden" name="line[2][price]" value="120">
    <input type="hidden" name="send" value="true">
    <input type="hidden" name="send_attach" value="true">
    <input type="hidden" name="send_subject" value="Invoice">
    <input type="hidden" name="send_message" value="Hello.{br}Here is your invoice.">
    <input type="hidden" name="get" value="true">
</form>