Working with Invoices in FreshBooks

[ 1 Overview ] [ 2 Operation details ] [ 3 Sample configuration ]

Overview

The following operations allow you to work with invoices. Click an operation name to see details on how to use it.

For a sample proxy service that illustrates how to work with invoices, see Sample configuration.

Operation	Description

Operation	Description
createInvoice	Creates an invoice.
deleteInvoice	Deletes an invoice.
getInvoice	Retrieves an invoice.
listInvoices	Lists invoices.
updateInvoice	Updates an invoice.
sendInvoiceByEmail	Sends an invoice by email.
addInvoiceLine	Adds an invoice line.
deleteInvoiceLine	Deletes an invoice line.
updateInvoiceLine	Updates an invoice line.

Operation details

This section provides details on the operation.

Creating an invoice

The createInvoice operation creates a new invoice complete with line items.

If you don’t specify an invoice <number>, it will increment from the last one.
You may optionally specify a different address on the invoice. Otherwise, the address will be pulled from your client details.
You may optionally specify a <return_uri> element. If provided, users will be presented with a link to the URI when they pay the invoice. More details of the return_uri element are available on the FreshBooks blog.

createInvoice

<freshbooks.createInvoice>
	<returnUri>{$ctx:returnUri}</returnUri>
    <pState>{$ctx:pState}</pState>
    <terms>{$ctx:terms}</terms>
    <pCode>{$ctx:pCode}</pCode>
    <pCity>{$ctx:pCity}</pCity>
    <date>{$ctx:date}</date>
    <contacts>{$ctx:contacts}</contacts>
    <estimateId>{$ctx:estimateId}</estimateId>
    <organization>{$ctx:organization}</organization>
    <firstName>{$ctx:firstName}</firstName>
    <lastName>{$ctx:lastName}</lastName>
    <currencyCode>{$ctx:currencyCode}</currencyCode>
    <status>{$ctx:status}</status>
    <pCountry>{$ctx:pCountry}</pCountry>
    <gateways>{$ctx:gateways}</gateways>
    <poNumber>{$ctx:poNumber}</poNumber>
    <number>{$ctx:number}</number>
    <pStreet1>{$ctx:pStreet1}</pStreet1>
    <clientId>{$ctx:clientId}</clientId>
    <pStreet2>{$ctx:pStreet2}</pStreet2>
    <discount>{$ctx:discount}</discount>
    <vatName>{$ctx:vatName}</vatName>
    <lines>{$ctx:lines}</lines>
    <language>{$ctx:language}</language>
    <vatNumber>{$ctx:vatNumber}</vatNumber>
    <notes>{$ctx:notes}</notes>
</freshbooks.createInvoice>

Properties

returnUri: The return URI of the invoice.
pState: The state of the address.
terms: The terms of the invoice.
pCode: The postal code of the invoice address.
pCity: The city of the address.
date: The invoice date. If not provided, defaults to today's date.
contacts: The details of the contact.
estimateId: The ID of the associated estimate.
organization: The name of the organization.
firstName: The first name to be displayed in the invoice.
lastName: The last name to be displayed in the invoice.
currencyCode: The currency code to be used on the invoice. Defaults to the base currency.
status: The status of the invoice ("sent", "viewed", or "draft")
pCountry: The country of the invoice.
gateways: One or more gateways.
poNumber: The purchase order number of the invoice.
number: The invoice number. Defaults to the one greater than the last invoice number.
pStreet1: The first street address line.
clientId: Required - The ID of the client who is being invoiced.
pStreet2: The second street address line.
discount: The percentage of discount.
vatName: The VAT name.
lines: Line items for the invoice.
language: The language code.
vatNumber: The VAT number.
notes: Additional notes.

Sample request

Following is a sample REST/XML request that can be handled by the createInvoice operation.

Sample Request for createInvoice

<createInvoice>
   <arbitraryPassword></arbitraryPassword>
   <apiUrl>https://sansu.freshbooks.com</apiUrl>
   <authenticationToken>c361a63c7456d519412fa80hh1ea605a6d</authenticationToken>
   <clientId>99962</clientId>
   <returnUri></returnUri>
   <date></date>
   <discount></discount>
   <contacts>
		<contact>
			<contact_id>0</contact_id>
		</contact>
   </contacts>
   <estimateId></estimateId>
   <firstName></firstName>
   <lastName></lastName>
   <currencyCode></currencyCode>
   <status></status>
   <gateways></gateways>
   <poNumber></poNumber>
   <number></number>
   <organization></organization>
   <pStreet1></pStreet1>
   <pStreet2></pStreet2>
   <pState></pState>
   <terms></terms>
   <pCity></pCity>
   <pCountry></pCountry>
   <pCode></pCode>
   <vatName></vatName>
   <vatNumber></vatNumber>
   <lines>
   	<line>
		<name>firstLine</name>
		<description>description of first Line</description>
		<unit_cost>2000</unit_cost>
		<quantity>2</quantity>
		<tax1_name>VAT</tax1_name>
		<tax2_name>VATD</tax2_name>
		<tax1_percent>10</tax1_percent>
		<tax2_percent>15</tax2_percent>
	</line>
   </lines>
   <language>en</language>
   <notes></notes>
</createInvoice>

For more information on the "lines" properties, go to the FreshBooks document link below.