FreshBooks API Guide for Invoices
Staff have access to the API calls listed below if the Invoices tab is enabled for staff. Staff users can only access invoices that belong to clients they are assigned to.
Create a new invoice complete with line items. If successful, returns the invoice_id of the newly created invoice.
- If you don’t specify an invoice
, 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’s details.
- You may optionally specify a
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 blog.
13 0 14 FB00004 draft 2007-06-23 2314 10 Due upon receipt. CAD en Payment due in 30 days. http://example.com/account John Smith ABC Corp Yard Work Mowed the lawn. 10 4 GST PST 5 8 Item
Update an existing invoice with the given invoice_id. Any invoice fields left out of the request will remain unchanged.
- If you do not specify a
element, the existing lines will remain unchanged. If you do specify elements the original ones will be replaced by the new ones.
Return the complete invoice details associated with the given invoice_id.
- You can use the
value to provide your customers with a direct link to their invoice.
- You can use the
element to provide your customers with direct links to the invoice for editing, viewing by the client and viewing by an administrator.
344 3 0 FB00004 45.6 0 paid 2007-06-23 0 Due upon receipt. Payment due in 30 days. CAD active en https://2ndsite.freshbooks.com/view/St2gThi6rA2t7RQ https://2ndsite.freshbooks.com/invoices/344 https://2ndsite.freshbooks.com/view/St2gThi6rA2t7RQ https://2ndsite.freshbooks.com/invoices/344 https://2ndsite.freshbooks.com/invoices/344/edit http://www.example.com/callback 2009-08-12 00:00:00 15 ABC Corp John Doe 123 Fake St. Unit 555 New York New York United States 553132 1 1 40 Yard work Mowed the lawn 10 4 GST PST 5 8 Item
Delete an existing invoice.
Returns a list of invoice summaries. Results are ordered by descending invoice_id.
Note: This method uses pagination.
- The value used for ‘status’ can be ‘disputed’, ‘draft’, ‘sent’, ‘viewed’, ‘paid’, ‘auto-paid’, ‘retry’, ‘failed’ or the special status ‘unpaid’ which will retrieve all invoices with a status of ‘disputed’, ‘sent’, ‘viewed’, ‘retry’ or ‘failed’.
3 10 draft FB00004 2007-01-01 2007-04-01 2007-01-01 00:00:00 2007-01-02 00:00:00 1 10 active
344 3 0 FB00004 45.6 CAD en 0 paid 2007-06-23 active 0 Due upon receipt. Payment due in 30 days. https://2ndsite.freshbooks.com/view/St2gThi6rA2t7RQ https://2ndsite.freshbooks.com/invoices/344 https://2ndsite.freshbooks.com/view/St2gThi6rA2t7RQ https://2ndsite.freshbooks.com/invoices/344 https://2ndsite.freshbooks.com/invoices/344/edit http://www.example.com/callback 2009-08-12 09:00:00 15 ABC Corp John Doe 123 Fake St. Unit 555 New York New York United States 553132 1 1 40 Yard work Mowed the lawn 10 4 GST PST 5 8 Item ......
Returns the specified invoice in PDF format.
Raw binary data. Save with a .pdf file extension.
Send an existing invoice to your client via e-mail. The invoice status will be changed to sent.
If you would like to send a custom email, include a message and subject element. Note that both of these elements are required (one or the other will not work).
344 This is a custom subject! You have a new invoice. Get it here: ::invoice link::
Send an existing invoice to your client via snail mail. If you do not have enough stamps, the request will fail. If successful, the invoice status will be changed to sent.
Be careful with this method. This operation cannot be undone.
Adds (a) new line(s) to an existing invoice.
- One or more lines may be added.
- Do not specify line_id for any lines. (Ids will be assigned automatically). Use invoice.lines.update to change existing lines.
111 40 Yak Shaving Shaved the yak 10 4 Item... 23 Telephone Sanitizing Sanitized the telephone 10 2.30 Item...
111 45 46
Note: In most cases, the returned line_ids will correspond to the new lines in the order that they were sent, however, this behavior is not guaranteed and should not be relied on. If you absolutely require the ability to match the created line_ids with the data you sent, you should create each line in its own request, or use some unique value for each line to eliminate any ambiguity.
Deletes a single line from an existing invoice.
- Only a single line can be deleted per request.
Updates (an) existing line(s) on an existing invoice.
- One or more lines may be updated.
- Only the provided fields will be updated. All others will be left unchanged.
- line_id is mandatory for each line to be updated. Use invoice.lines.add to create new lines.
99 1 50 Premium Yak Shaving 12.50... 2 30 Advanced Telephone Sanitizing 3.00...