If you’re using FreshBooks Classic, click here.

Invoices

General Info

Invoices in FreshBooks are what gets sent to Clients, detailing specific goods or services performed or provided by the Administrator of their System, and the amount that Client owes to the Admin.

For online payment options, see Online Payments.

Requires Authorization

Invoice Statuses

Code	Status	Description
0	Disputed	An Invoice with the Dispute option enabled, which has been disputed by a Client. This is a feature of FreshBooks Classic only.
1	Draft	An Invoice that has been created, but not yet sent.
2	Sent	An Invoice that has been sent to a Client or marked as sent by the Admin.
3	Viewed	An Invoice that has been viewed by a Client.
4	Paid	A fully paid Invoice.
5	Auto Paid	An Invoice paid automatically with a saved credit card.
6	Retry	An Invoice that would normally be paid automatically, but encountered a processing issue, either due to a bad card or a service outage. It will be retried 1 day later.
7	Failed	An Invoice that was in Retry status which again encountered a processing issue when being retried.
8	Partial	An Invoice that has been partially paid.

v3 Statuses

v3 status fields give a descriptive name to states which can be used in filters, and apply to many invoices, estimates, and recurring profiles.

Value	Description
created	object is created and in no other state
draft	object is saved in draft status
sent	object has been sent
viewed	object has been viewed by receipient
failed	an autobill related to the object has been tried more than once and failed
retry	an autobill related to the object has been tried once and failed, and will be retried
success	an autobill related to the object has succeeded
autopaid	a payment has been tied to the object automatically via autobill
paid	payments related to the object have succeeded and the object is fully paid
partial	some payment related to the object has succeeded but the invoice is not yet paid off
disputed	the object is disputed
resolved	the object was disputed and the dispute has been marked as resolved
overdue	the object required an action at an earlier date that was not met
deposit-partial	the object has a related deposit which has been partially paid
deposit-paid	the object has a related deposit which has been fully paid
declined	the object has a related order which has been declined
pending	the object has a related order which is pending

Includes

Include Name	Description
audit_logs	show invoice view/send/payment history
client_audits	show the client-visible invoice history
comments	comments made on invoice
contacts	list of client contacts
lines	invoice lines
owner	owner info
latest_journal_entry	journal entry info
allowed_gateways	list of allowed gateways
late_fee	late fee info
presentation	presentation type
late_reminders	late reminders
system	invoice-owner's system

Filters

Filter Type	Name	Field	Description
Equals	invoiceid	invoiceid	matches exact invoiceid
In	invoiceids	invoiceid	matches list of invoiceids, one per query argument specified
Like	invoice _number _like	invoice _number	invoice number containing parameter
Equals	invoice _number	invoice _number	matches exact invoice number
Like	notes	notes	notes containing parameter
StatusEq Filter	statusid	special	matches exact invoice status
StatusIn Filter	statusids	special	matches list of invoice statuses, one per query argument specified
V3StatusEq Filter	v3_status	special	matches exact v3_status
Equals	currency _code	currency _code	matches exact currency code
Equals	currency	currency _code	alternative to currency_code filter
Between	date_min	create_date	date greater than or equal to parameter, YYYY-MM-DD format
Between	date_max	create_date	date less than parameter, YYYY-MM-DD format
Between	total_min	amount	amount greater than or equal to parameter
Between	total_max	amount	amount less than parameter
Like	po_number	po_number	po_number containing parameter
Equals	customerid	customerid	matches exact customerid
In	customerids	customerid	matches list of customerids, one per query argument specified
Equals	parentid	parent	matches exact parentid
PaidFilter	paid	special	true/false return paid invoices or unpaid invoices
Outstanding Filter	outstanding	special	true/false return outstanding or not outstanding invoices
Between	updated_min	updated	updated date greater than or equal to parameter, YYYY-MM-DD format
Between	updated_max	updated	updated date less than parameter, YYYY-MM-DD format
ItemName Filter	item_name	name	item name containing the parameter
ItemDescriptionFilter	item _description	description	item description containing the parameter
Equals	projectid	projectid	matches exact projectid
Outstanding AmountFilter	outstanding _min	special	matches invoices with an outstanding amount greater than input

Field Descriptions

underlined fields are required on creation

Computed Fields (read only)
Field	Type	Description
invoiceid	int	unique-to-this-system invoice id
id	int	unique-to-this-system invoice id, duplicate of invoiceid
accounting _systemid	string	unique id for system
accountid	string	unique id for system, repeat of accounting _systemid
amount	string	total amount of invoice, to two decimal places
paid	object	subfields: amount and code
amount	string	amount paid on invoice, to two decimal places
code	string	three-letter currency code
outstanding	object	subfields: amount, code
amount	string	amount outstanding on invoice, to two decimal places
code	string	three-letter currency code
discount_total	object	subfields: amount and code
amount	string	amount of discount, to two decimal places
code	string	three-letter currency code
description	string	description of first line of invoice
current _organization	string	Name of organization being invoiced -- denormalized from client
due_date	date	date invoice is marked as due by, YYYY-MM-DD format, calculated from due_offset_days. If due_offset_days is not set, it will default to the date of issue.
date_paid	date	date invoice was fully paid, YYYY-MM-DD format
Writable on Create
Field	Type	Description
ownerid	int	id of creator of invoice. 1 if business admin, other if created by e.g. a contractor
estimateid	int	id of associated estimate, 0 if none
basecampid	int	id of connected basecamp account, 0 if none
sentid	int	userid of user who sent the invoice, typically 1 for admin
status	string	See Invoice Status table.
parent	int	id of object this invoice was generated from, 0 if none
created_at	datetime	Time the invoice was created, YYYY-MM-DD HH:MM:SS format
updated	datetime	time invoice last updated at, YYYY-MM-DD HH:MM:SS format
display_status	string	Description of status shown in FreshBooks UI, one of 'draft', 'created', 'sent', 'viewed', or 'outstanding'.
autobill_status	string	one of retry, failed, or success
payment_status	string	description of payment status. One of 'unpaid', 'partial', 'paid', and 'auto-paid'. See the v3_status table on this page for descriptions of each.
last_order_status	string	describes status of last attempted payment
dispute_status	string	description of whether invoice has been disputed.
deposit_status	string	description of deposits applied to invoice. One of 'paid', 'unpaid', 'partial', 'none', and 'converted'.
auto_bill	boolean	whether this invoice has a credit card saved
v3_status	string	description of Invoice Status, see V3 Status Table.
Data Fields (writable)
Field	Type	Description
invoice_number	string	user-specified and visible invoice id
customerid	int	unique-to-this-system client-id
create_date	date	date invoice was created, YYYY-MM-DD format
generation_date	date	date invoice generated from object, null if it wasn't, YYYY-MM-DD if it was
discount_value	string	percent amount being discounted from the subtotal, decimal-string amount ranging from 0 to 100
discount _description	string	public note about discount
po_number	string	Reference number for address on invoice.
template	string	(internal, deprecated) choice of rendering style
currency_code	string	three-letter currency code for invoice
language	string	two-letter language code, e.g. "en"
terms	string	terms listed on invoice
notes	string	Notes listed on invoice
address	string	First line of address on invoice
return_uri	string	(deprecated)
deposit_amount	object	amount required as deposit, null if none
deposit _percentage	string	percent of the invoice's value required as a deposit
gmail	boolean	whether to send via ground mail
show_attachments	boolean	whether attachments on invoice are rendered
ext_archive	int	(deprecated) 0 or 1 indicating archived or not
vis_state	int	0 for active, 1 for deleted
street	string	street for address on invoice
street2	string	second line of street for address on invoice.
city	string	city for address on invoice
province	string	Province for address on invoice.
code	string	zip code for address on invoice
country	string	Country for address on invoice
organization	string	Name of organization being invoiced.
fname	string	First name of Client on invoice
lname	string	Last name of client being invoiced
vat_name	string	Value Added Tax name if provided
vat_number	string	Value Added Tax number if provided
due_offset_days	int	Number of days from creation that invoice is due. If not set, the due date will default to the date of issue.
lines	array	Lines of the invoice
presentation	object	where invoice logo and styles are defined. See our postman collection for details.

Invoice Lines

Invoice lines are used to determine the amount of an invoice, in addition to being able to tie the invoice to rebilled expenses. The invoice line type determines whether a line is an amount or whether it refers to an unbilled expense. Note:When updating lines with a PUT request, the request payload must contain all the lines of the invoice that you wish to remain.

Computed Fields (read only)
Field	Type	Description
lineid	int	unique-to-this-invoice line id
amount	object	amount total of an invoice line, calculated with unit cost, quantity and tax. subfields: amount and code
amount	string	amount of invoice line item account, to two decimal places
code	string	three-letter currency code
updated	datetime	time invoice line last updated at, YYYY-MM-DD HH:MM:SS format
Data Fields (writable)
Field	Type	Description
type	int	invoice line type, 0 for normal invoice line, 1 for rebilling expense line
expenseid	(optional) int	id of unbilled expense, required when invoice line type is 1, otherwise should be excluded
qty	int	quantity of the invoice line unit, multiplied against unit_cost
unit_cost	object	unit cost of the line item. subfields: amount and code
amount	string	unit cost amount, to two decimal places
code	string	three-letter currency code
description	string	description for the invoice line item
name	string	name for the invoice line item
taxName1	string	name for the first tax on the invoice line
taxAmount1	string	first tax amount, in percentage, up to 3 decimal places
taxName2	string	name for the second tax on the invoice line
taxAmount2	string	second tax amount, in percentage, up to 3 decimal places

curl Python

Get Single Invoice

Request: GET https://api.freshbooks.com/accounting/account/<accountid>/invoices/invoices/<invoiceid>

Response:

{
  "response": {
    "result": {
      "invoice": {
        "status": 2,
        "deposit_percentage": null,
        "create_date": "2016-09-09",
        "outstanding": {
          "amount": "800.00",
          "code": "USD"
        },
        "payment_status": "unpaid",
        "code": "",
        "ownerid": 1,
        "vat_number": "",
        "id": 2201278,
        "gmail": false,
        "vat_name": "",
        "v3_status": "sent",
        "parent": 0,
        "country": "United States",
        "dispute_status": null,
        "lname": "Client",
        "deposit_status": "none",
        "estimateid": 0,
        "ext_archive": 0,
        "template": "clean-grouped",
        "basecampid": 0,
        "generation_date": null,
        "show_attachments": true,
        "vis_state": 0,
        "current_organization": "Test Client",
        "province": "",
        "due_date": "2016-10-09",
        "updated": "2016-09-09 16:04:42",
        "terms": null,
        "description": "",
        "discount_description": null,
        "last_order_status": null,
        "street2": "",
        "deposit_amount": null,
        "paid": {
          "amount": "0.00",
          "code": "USD"
        },
        "invoiceid": 2201278,
        "discount_total": {
          "amount": "0.00",
          "code": "USD"
        },
        "address": "",
        "invoice_number": "0000003",
        "customerid": 2185379,
        "discount_value": "0",
        "accounting_systemid": "KAG77",
        "organization": "Test Client",
        "due_offset_days": 30,
        "language": "en",
        "po_number": null,
        "display_status": "sent",
        "notes": "",
        "date_paid": null,
        "amount": {
          "amount": "800.00",
          "code": "USD"
        },
        "street": "",
        "city": "",
        "currency_code": "USD",
        "sentid": 1,
        "autobill_status": null,
        "return_uri": null,
        "fname": "Test",
        "created_at": "2016-09-09 14:37:59",
        "auto_bill": false,
        "accountid": "KAG77"
      }
    }
  }
}

Create Single Invoice

Request: POST https://api.freshbooks.com/accounting/account/<accountid>/invoices/invoices

{
  "invoice": {
     "email": "test@example.com",
     "customerid": 1831231,
     "create_date": "2016-04-04"
  }
}

Response:

{
  "response": {
    "result": {
      "invoice": {
        "status": 1,
        "deposit_percentage": null,
        "create_date": "2016-04-04",
        "outstanding": {
          "amount": "0.00",
          "code": "USD"
        },
        "payment_status": "unpaid",
        "code": "2011",
        "ownerid": 1,
        "vat_number": "",
        "id": 2168250,
        "gmail": false,
        "vat_name": "",
        "v3_status": "draft",
        "parent": 0,
        "country": "Australia",
        "dispute_status": null,
        "lname": "Gates",
        "deposit_status": "none",
        "estimateid": 0,
        "ext_archive": 0,
        "template": "clean-grouped",
        "basecampid": 0,
        "generation_date": null,
        "show_attachments": true,
        "vis_state": 0,
        "current_organization": "Microsoft",
        "province": "NSW",
        "due_date": "2016-04-04",
        "updated": "2016-09-01 16:16:15",
        "terms": "",
        "description": "",
        "discount_description": null,
        "last_order_status": null,
        "street2": "",
        "deposit_amount": null,
        "paid": {
          "amount": "0.00",
          "code": "USD"
        },
        "invoiceid": 2168250,
        "discount_total": {
          "amount": "0.00",
          "code": "USD"
        },
        "address": "",
        "invoice_number": "0000007",
        "customerid": 1831231,
        "discount_value": "0",
        "accounting_systemid": "zDmNq",
        "organization": "Microsoft",
        "due_offset_days": 30,
        "language": "en",
        "po_number": null,
        "display_status": "draft",
        "notes": "",
        "date_paid": null,
        "amount": {
          "amount": "0.00",
          "code": "USD"
        },
        "street": "12 Pacific Highway",
        "city": "North Sydney",
        "currency_code": "USD",
        "sentid": 1,
        "autobill_status": null,
        "return_uri": null,
        "fname": "Wyatt",
        "created_at": "2016-09-01 16:16:14",
        "auto_bill": false,
        "accountid": "zDmNq"
      }
    }
  }
}

Create Single Invoice With Invoice Lines (and an unbilled expense)

Request: POST https://api.freshbooks.com/accounting/account/<accountid>/invoices/invoices

{
  "invoice": {
    "email": "test@example.com",
    "customerid": 338441,
    "create_date": "2016-04-04",
    "lines": [
      {
        "type": 0,
        "description": "",
        "taxName1": "",
        "taxAmount1": 0,
        "name": "Paperwork",
        "qty": 1,
        "taxName2": "",
        "taxAmount2": 0,
        "unit_cost": {
            "amount": "5000.00",
            "code": "USD"
        }
      },
      {
        "type": 1,
        "description": "",
        "expenseid": 1918390,
        "taxName1": "",
        "taxAmount1": 0,
        "name": "TV Ads",
        "qty": 1,
        "taxName2": "",
        "taxAmount2": 0,
        "unit_cost": {
            "amount": "3000.00",
            "code": "USD"
        }
      }
    ]
  }
}

Response:

{
  "response": {
    "result": {
      "invoice": {
        "status": 1,
        "deposit_percentage": null,
        "create_date": "2016-04-04",
        "outstanding": {
            "amount": "8000.00",
            "code": "USD"
        },
        "payment_status": "unpaid",
        "code": "2011",
        "ownerid": 1,
        "vat_number": "",
        "id": 2168250,
        "gmail": false,
        "vat_name": "",
        "v3_status": "draft",
        "parent": 0,
        "country": "Australia",
        "dispute_status": null,
        "lname": "Gates",
        "deposit_status": "none",
        "estimateid": 0,
        "ext_archive": 0,
        "template": "clean-grouped",
        "basecampid": 0,
        "generation_date": null,
        "show_attachments": true,
        "vis_state": 0,
        "current_organization": "Microsoft",
        "province": "NSW",
        "due_date": "2016-04-04",
        "updated": "2016-09-01 16:16:15",
        "terms": "",
        "description": "",
        "discount_description": null,
        "last_order_status": null,
        "street2": "",
        "deposit_amount": null,
        "paid": {
          "amount": "0.00",
          "code": "USD"
        },
        "invoiceid": 2168250,
        "discount_total": {
          "amount": "0.00",
          "code": "USD"
        },
        "address": "",
        "invoice_number": "0000007",
        "customerid": 338441,
        "discount_value": "0",
        "accounting_systemid": "zDmNq",
        "organization": "Microsoft",
        "due_offset_days": 30,
        "language": "en",
        "po_number": null,
        "display_status": "draft",
        "notes": "",
        "date_paid": null,
        "amount": {
          "amount": "8000.00",
          "code": "USD"
        },
        "street": "12 Pacific Highway",
        "city": "North Sydney",
        "currency_code": "USD",
        "sentid": 1,
        "autobill_status": null,
        "return_uri": null,
        "fname": "Wyatt",
        "created_at": "2016-09-01 16:16:14",
        "auto_bill": false,
        "accountid": "zDmNq"
      }
    }
  }
}

Create Single Invoice With Discount Value

Request: POST https://api.freshbooks.com/accounting/account/<accountid>/invoices/invoices

{
   "invoice": {
      "status": "2",
      "invoice_number": "IV-1160",
      "customerid": "167034",
      "create_date": "2019-01-01",
      "due_offset_days": "30",
      "discount_value": 10,
      "lines": [
         {
            "type": "0",
            "name": "Consulting",
            "description": "K. Graves - IT Support",
            "qty": "3",
            "taxName1": "CGST",
            "taxAmount1": "7.5",
            "taxName2": "SGST",
            "taxAmount2": "7.5",
            "unit_cost": {
               "amount": "140"
            }
         }
      ]
   }
}

Response:

{
   "response": {
      "result": {
         "invoice": {
            "accountid": "85Zwnk",
            "accounting_systemid": "85Zwnk",
            "address": "",
            "amount": {
               "amount": "434.70",
               "code": "CAD"
            },
            "auto_bill": false,
            "autobill_status": null,
            "basecampid": 0,
            "city": "",
            "code": "",
            "country": "",
            "create_date": "2019-01-01",
            "created_at": "2019-09-20 11:17:13",
            "currency_code": "CAD",
            "current_organization": "K A",
            "customerid": 167034,
            "date_paid": null,
            "deposit_amount": null,
            "deposit_percentage": null,
            "deposit_status": "none",
            "description": "K. Graves - IT Support",
            "discount_description": null,
            "discount_total": {
               "amount": "-42.00",
               "code": "CAD"
            },
            "discount_value": "10",
            "display_status": "sent",
            "dispute_status": null,
            "due_date": "2019-01-31",
            "due_offset_days": 30,
            "estimateid": 0,
            "ext_archive": 0,
            "fname": "K",
            "fulfillment_date": "2019-01-01",
            "generation_date": null,
            "gmail": false,
            "id": 101126,
            "invoice_number": "IV-1160",
            "invoiceid": 101126,
            "language": "en",
            "last_order_status": null,
            "lname": "A",
            "notes": "",
            "organization": "K A",
            "outstanding": {
               "amount": "434.70",
               "code": "CAD"
            },
            "ownerid": 1,
            "paid": {
               "amount": "0.00",
               "code": "CAD"
            },
            "parent": 0,
            "payment_details": "",
            "payment_status": "unpaid",
            "po_number": null,
            "province": "",
            "return_uri": null,
            "sentid": 1,
            "show_attachments": true,
            "status": 2,
            "street": "",
            "street2": "",
            "template": "clean-grouped",
            "terms": "",
            "updated": "2019-09-20 11:17:13",
            "v3_status": "overdue",
            "vat_name": "",
            "vat_number": "",
            "vis_state": 0
         }
      }
   }
}

Update Single Invoice

Request: PUT api.freshbooks.com/accounting/account/<accountid>/invoices/invoices/<id>

{
  "invoice": {
     "customerid": 1831231,
     "create_date": "2016-04-04"
  }
}

Response:

{
  "response": {
    "result": {
      "invoice": {
        "status": 1,
        "deposit_percentage": null,
        "create_date": "2016-04-04",
        "outstanding": {
            "amount": "8000.00",
            "code": "USD"
        },
        "payment_status": "unpaid",
        "code": "2011",
        "ownerid": 1,
        "vat_number": "",
        "id": 2168250,
        "gmail": false,
        "vat_name": "",
        "v3_status": "draft",
        "parent": 0,
        "country": "Australia",
        "dispute_status": null,
        "lname": "Gates",
        "deposit_status": "none",
        "estimateid": 0,
        "ext_archive": 0,
        "template": "clean-grouped",
        "basecampid": 0,
        "generation_date": null,
        "show_attachments": true,
        "vis_state": 0,
        "current_organization": "Microsoft",
        "province": "NSW",
        "due_date": "2016-04-04",
        "updated": "2016-09-01 16:16:15",
        "terms": "",
        "description": "",
        "discount_description": null,
        "last_order_status": null,
        "street2": "",
        "deposit_amount": null,
        "paid": {
          "amount": "0.00",
          "code": "USD"
        },
        "invoiceid": 2168250,
        "discount_total": {
          "amount": "0.00",
          "code": "USD"
        },
        "address": "",
        "invoice_number": "0000007",
        "customerid": 1831231,
        "discount_value": "0",
        "accounting_systemid": "zDmNq",
        "organization": "Microsoft",
        "due_offset_days": 30,
        "language": "en",
        "po_number": null,
        "display_status": "draft",
        "notes": "",
        "date_paid": null,
        "amount": {
          "amount": "8000.00",
          "code": "USD"
        },
        "street": "12 Pacific Highway",
        "city": "North Sydney",
        "currency_code": "USD",
        "sentid": 1,
        "autobill_status": null,
        "return_uri": null,
        "fname": "Wyatt",
        "created_at": "2016-09-01 16:16:14",
        "auto_bill": false,
        "accountid": "zDmNq"
      }
    }
  }
}

Delete Single Invoice

Request: PUT api.freshbooks.com/accounting/account/<accountid>/invoices/invoices/<id>

{
  "invoice": {
    "vis_state": 1
  }
}

Response:

{
  "response": {}
}

List Invoices

Request: GET api.freshbooks.com/accounting/account/<accountid>/invoices/invoices

Response:

{
  "response": {
    "result": {
      "invoices": [
          {
            // same format as single invoice
          },
          {
            // same format as single invoice
          },
          {
            // same format as single invoice
          }
        }
      ],
      "per_page": 15,
      "total": 2,
      "page": 1,
      "pages": 1
    }
  }
}

Get Single Invoice

Request: GET

https://api.freshbooks.com/accounting/account/<accountid> /invoices/invoices/<invoiceid>”


url = "https://api.freshbooks.com/accounting/account/<accountid>
/invoices/invoices/<invoiceid>"
headers = {'Authorization': 'Bearer <bearer token>', 'Api-Version': 'alpha', 'Content-Type': 'application/json'}
res = requests.get(url, data=None, headers=headers)
jsonData = res.json()

jsonData Response should be:


{
  "response": {
    "result": {
      "invoice": {
        "status": 2,
        "deposit_percentage": null,
        "create_date": "2016-09-09",
        "outstanding": {
          "amount": "800.00",
          "code": "USD"
        },
        "payment_status": "unpaid",
        "code": "",
        "ownerid": 1,
        "vat_number": "",
        "id": 2201278,
        "gmail": false,
        "vat_name": "",
        "v3_status": "sent",
        "parent": 0,
        "country": "United States",
        "dispute_status": null,
        "lname": "Client",
        "deposit_status": "none",
        "estimateid": 0,
        "ext_archive": 0,
        "template": "clean-grouped",
        "basecampid": 0,
        "generation_date": null,
        "show_attachments": true,
        "vis_state": 0,
        "current_organization": "Test Client",
        "province": "",
        "due_date": "2016-10-09",
        "updated": "2016-09-09 16:04:42",
        "terms": null,
        "description": "",
        "discount_description": null,
        "last_order_status": null,
        "street2": "",
        "deposit_amount": null,
        "paid": {
          "amount": "0.00",
          "code": "USD"
        },
        "invoiceid": 2201278,
        "discount_total": {
          "amount": "0.00",
          "code": "USD"
        },
        "address": "",
        "invoice_number": "0000003",
        "customerid": 2185379,
        "discount_value": "0",
        "accounting_systemid": "KAG77",
        "organization": "Test Client",
        "due_offset_days": 30,
        "language": "en",
        "po_number": null,
        "display_status": "sent",
        "notes": "",
        "date_paid": null,
        "amount": {
          "amount": "800.00",
          "code": "USD"
        },
        "street": "",
        "city": "",
        "currency_code": "USD",
        "sentid": 1,
        "autobill_status": null,
        "return_uri": null,
        "fname": "Test",
        "created_at": "2016-09-09 14:37:59",
        "auto_bill": false,
        "accountid": "KAG77"
      }
    }
  }
}

Create Single Invoice

Request: POST

https://api.freshbooks.com/accounting/account/<accountid> /invoices/invoices”


url = "https://api.freshbooks.com/accounting/account/<accountid>
/invoices/invoices"
headers = {'Authorization': 'Bearer <bearer token>', 'Api-Version': 'alpha', 'Content-Type': 'application/json'}
payload = {'invoice': {'email': "test@example.com", 'customerid': 1831231, 'create_date': "2017-06-06"}}
res = requests.post(url, data=json.dumps(payload), headers=headers)

Response:


{
  "response": {
    "result": {
      "invoice": {
        "status": 2,
        "deposit_percentage": null,
        "create_date": "2016-09-09",
        "outstanding": {
          "amount": "800.00",
          "code": "USD"
        },
        "payment_status": "unpaid",
        "code": "",
        "ownerid": 1,
        "vat_number": "",
        "id": 2201278,
        "gmail": false,
        "vat_name": "",
        "v3_status": "sent",
        "parent": 0,
        "country": "United States",
        "dispute_status": null,
        "lname": "Client",
        "deposit_status": "none",
        "estimateid": 0,
        "ext_archive": 0,
        "template": "clean-grouped",
        "basecampid": 0,
        "generation_date": null,
        "show_attachments": true,
        "vis_state": 0,
        "current_organization": "Test Client",
        "province": "",
        "due_date": "2016-10-09",
        "updated": "2016-09-09 16:04:42",
        "terms": null,
        "description": "",
        "discount_description": null,
        "last_order_status": null,
        "street2": "",
        "deposit_amount": null,
        "paid": {
          "amount": "0.00",
          "code": "USD"
        },
        "invoiceid": 2201278,
        "discount_total": {
          "amount": "0.00",
          "code": "USD"
        },
        "address": "",
        "invoice_number": "0000003",
        "customerid": 2185379,
        "discount_value": "0",
        "accounting_systemid": "KAG77",
        "organization": "Test Client",
        "due_offset_days": 30,
        "language": "en",
        "po_number": null,
        "display_status": "sent",
        "notes": "",
        "date_paid": null,
        "amount": {
          "amount": "800.00",
          "code": "USD"
        },
        "street": "",
        "city": "",
        "currency_code": "USD",
        "sentid": 1,
        "autobill_status": null,
        "return_uri": null,
        "fname": "Test",
        "created_at": "2016-09-09 14:37:59",
        "auto_bill": false,
        "accountid": "KAG77"
      }
    }
  }
}

Create Single Invoice With Invoice Lines (and an unbilled expense)

Request: POST

https://api.freshbooks.com/accounting/account/<accountid>/invoices/invoices


url = "https://api.freshbooks.com/accounting/account/<accountid>/
invoices/invoices"

payload = {'invoice': {
  'email': "test@example.com",
  'customerid': 338441,
  'create_date': "2016-04-04",
  'lines': [
  {
    'type': 0,
    'description': "",
    'taxName1': "",
    'taxAmount1': 0,
    'name': "paperwork",
    'qty': 1,
    'taxName2': "",
    'taxAmount2': 0,
    'unit_cost':{
      'amount': "5000.00",
      'code': "USD"
    }

  },
  {
    'type': 1,
    'description': "",
    'expenseid': 1918390
    'taxName1': "",
    'taxAmount1': 0,
    'name': "TV Ads",
    'qty': 1,
    'taxName2': "",
    'taxAmount2': 0,
    'unit_cost':{
      'amount': "3000.00",
      'code': "USD"
      }
    }
  ]
}
}
headers = {'Authorization': 'Bearer <bearer token>', 'Api-Version': 'alpha', 'Content-Type': 'application/json'}

res.requests.post(url, data=json.dumps(payload), headers=headers)

Response:


{
"response": {
"result": {
  "invoice": {
    "status": 1,
    "deposit_percentage": null,
    "create_date": "2016-04-04",
    "outstanding": {
      "amount": "8000.00",
      "code": "USD"
  },
  "payment_status": "unpaid",
  "code": "2011",
  "ownerid": 1,
  "vat_number": "",
  "id": 2168250,
  "gmail": false,
  "vat_name": "",
  "v3_status": "draft",
  "parent": 0,
  "country": "Australia",
  "dispute_status": null,
  "lname": "Gates",
  "deposit_status": "none",
  "estimateid": 0,
  "ext_archive": 0,
  "template": "clean-grouped",
  "basecampid": 0,
  "generation_date": null,
  "show_attachments": true,
  "vis_state": 0,
  "current_organization": "Microsoft",
  "province": "NSW",
  "due_date": "2016-04-04",
  "updated": "2016-09-01 16:16:15",
  "terms": "",
  "description": "",
  "discount_description": null,
  "last_order_status": null,
  "street2": "",
  "deposit_amount": null,
  "paid": {
    "amount": "0.00",
    "code": "USD"
  },
  "invoiceid": 2168250,
  "discount_total": {
    "amount": "0.00",
    "code": "USD"
  },
  "address": "",
  "invoice_number": "0000007",
  "customerid": 338441,
  "discount_value": "0",
  "accounting_systemid": "zDmNq",
  "organization": "Microsoft",
  "due_offset_days": 30,
  "language": "en",
  "po_number": null,
  "display_status": "draft",
  "notes": "",
  "date_paid": null,
  "amount": {
    "amount": "8000.00",
    "code": "USD"
  },
  "street": "12 Pacific Highway",
  "city": "North Sydney",
  "currency_code": "USD",
  "sentid": 1,
  "autobill_status": null,
  "return_uri": null,
  "fname": "Wyatt",
  "created_at": "2016-09-01 16:16:14",
  "auto_bill": false,
  "accountid": "zDmNq"
        }
      }
    }
  }

Create Single Invoice With Discount Value

Request: POST

https://api.freshbooks.com/accounting/account/<accountid> /invoices/invoices”


url = "https://api.freshbooks.com/accounting/account/<accountid>
/invoices/invoices"
headers = {'Authorization': 'Bearer <bearer token>', 'Api-Version': 'alpha', 'Content-Type': 'application/json'}
payload = {
   "invoice": {
      "status": "2",
      "invoice_number": "IV-1160",
      "customerid": "167034",
      "create_date": "2019-01-01",
      "due_offset_days": "30",
      "discount_value": 10,
      "lines": [
         {
            "type": "0",
            "name": "Consulting",
            "description": "K. Graves - IT Support",
            "qty": "3",
            "taxName1": "CGST",
            "taxAmount1": "7.5",
            "taxName2": "SGST",
            "taxAmount2": "7.5",
            "unit_cost": {
               "amount": "140"
            }
         }
      ]
   }
}
res = requests.post(url, data=json.dumps(payload), headers=headers)

Response:


{
  "response": {
    "result": {
      "invoice": {
        "accountid": "85Zwnk",
        "accounting_systemid": "85Zwnk",
        "address": "",
        "amount": {
          "amount": "434.70",
          "code": "CAD"
        },
        "auto_bill": false,
        "autobill_status": null,
        "basecampid": 0,
        "city": "",
        "code": "",
        "country": "",
        "create_date": "2019-01-01",
        "created_at": "2019-09-20 11:17:13",
        "currency_code": "CAD",
        "current_organization": "K A",
        "customerid": 167034,
        "date_paid": null,
        "deposit_amount": null,
        "deposit_percentage": null,
        "deposit_status": "none",
        "description": "K. Graves - IT Support",
        "discount_description": null,
        "discount_total": {
          "amount": "-42.00",
          "code": "CAD"
        },
        "discount_value": "10",
        "display_status": "sent",
        "dispute_status": null,
        "due_date": "2019-01-31",
        "due_offset_days": 30,
        "estimateid": 0,
        "ext_archive": 0,
        "fname": "K",
        "fulfillment_date": "2019-01-01",
        "generation_date": null,
        "gmail": false,
        "id": 101126,
        "invoice_number": "IV-1160",
        "invoiceid": 101126,
        "language": "en",
        "last_order_status": null,
        "lname": "A",
        "notes": "",
        "organization": "K A",
        "outstanding": {
          "amount": "434.70",
          "code": "CAD"
        },
        "ownerid": 1,
        "paid": {
          "amount": "0.00",
          "code": "CAD"
        },
        "parent": 0,
        "payment_details": "",
        "payment_status": "unpaid",
        "po_number": null,
        "province": "",
        "return_uri": null,
        "sentid": 1,
        "show_attachments": true,
        "status": 2,
        "street": "",
        "street2": "",
        "template": "clean-grouped",
        "terms": "",
        "updated": "2019-09-20 11:17:13",
        "v3_status": "overdue",
        "vat_name": "",
        "vat_number": "",
        "vis_state": 0
      }
    }
  }
}

Send Invoice via Email

Request: PUT

https://api.freshbooks.com/accounting/account/<accountid> /invoices/invoices/<invoiceid>”

url = "https://api.freshbooks.com/accounting/account/<accountid>
/invoices/invoices/<invoiceid>"
headers = {'Authorization': 'Bearer <bearer token>', 'Api-Version': 'alpha', 'Content-Type': 'application/json'}
payload = {
   "invoice": {
      "email_subject": "Thanks for being a customer",
      "email_recipients": ["dtherockjohnson@freshbooks.com", "beilish@freshbooks.com"],
      "email_body": "This can be any personal message",
      "action_email": true,
      }
   }
}
res = requests.post(url, data=json.dumps(payload), headers=headers)

Response:


{
  "response": {
    "result": {
      "invoice": {
        "accountid": "85Zwnk",
        "accounting_systemid": "85Zwnk",
        "address": "",
        "amount": {
          "amount": "434.70",
          "code": "CAD"
        },
        "auto_bill": false,
        "autobill_status": null,
        "basecampid": 0,
        "city": "",
        "code": "",
        "country": "",
        "create_date": "2019-01-01",
        "created_at": "2019-09-20 11:17:13",
        "currency_code": "CAD",
        "current_organization": "K A",
        "customerid": 167034,
        "date_paid": null,
        "deposit_amount": null,
        "deposit_percentage": null,
        "deposit_status": "none",
        "description": "K. Graves - IT Support",
        "discount_description": null,
        "discount_total": {
          "amount": "-42.00",
          "code": "CAD"
        },
        "discount_value": "10",
        "display_status": "sent",
        "dispute_status": null,
        "due_date": "2019-01-31",
        "due_offset_days": 30,
        "estimateid": 0,
        "ext_archive": 0,
        "fname": "Dwayne",
        "fulfillment_date": "2019-01-01",
        "generation_date": null,
        "gmail": false,
        "id": 101126,
        "invoice_number": "IV-1160",
        "invoiceid": 101126,
        "language": "en",
        "last_order_status": null,
        "lname": "Johnson",
        "notes": "",
        "organization": "WWE",
        "outstanding": {
          "amount": "434.70",
          "code": "CAD"
        },
        "ownerid": 1,
        "paid": {
          "amount": "0.00",
          "code": "CAD"
        },
        "parent": 0,
        "payment_details": "",
        "payment_status": "unpaid",
        "po_number": null,
        "province": "",
        "return_uri": null,
        "sentid": 1,
        "show_attachments": true,
        "status": 2,
        "street": "",
        "street2": "",
        "template": "clean-grouped",
        "terms": "",
        "updated": "2019-09-20 11:17:13",
        "v3_status": "overdue",
        "vat_name": "",
        "vat_number": "",
        "vis_state": 0
      }
    }
  }
}

Update Single Invoice

Request: PUT api.freshbooks.com/accounting/account/<accountid>/invoices/invoices/<id>


url = "api.freshbooks.com/accounting/account/<accountid>/invoices/invoices/<id>"
headers = {'Authorization': 'Bearer <bearer token>', 'Api-Version': 'alpha', 'Content-Type': 'application/json'}
payload = {'invoice': {
       'customerid': 1831231,
       'create_date': "2017-06-06"
   }
}
res = requests.put(url, data=json.dumps(payload), headers=headers)

Response:


{
 "response": {
 "result": {
   "invoice": {
     "status": 1,
     "deposit_percentage": null,
     "create_date": "2016-04-04",
     "outstanding": {
       "amount": "8000.00",
       "code": "USD"
       },
     "payment_status": "unpaid",
     "code": "2011",
     "ownerid": 1,
     "vat_number": "",
     "id": 2168250,
     "gmail": false,
     "vat_name": "",
     "v3_status": "draft",
     "parent": 0,
     "country": "Australia",
     "dispute_status": null,
     "lname": "Gates",
     "deposit_status": "none",
     "estimateid": 0,
     "ext_archive": 0,
     "template": "clean-grouped",
     "basecampid": 0,
     "generation_date": null,
     "show_attachments": true,
     "vis_state": 0,
     "current_organization": "Microsoft",
     "province": "NSW",
     "due_date": "2016-04-04",
     "updated": "2016-09-01 16:16:15",
     "terms": "",
     "description": "",
     "discount_description": null,
     "last_order_status": null,
     "street2": "",
     "deposit_amount": null,
     "paid": {
       "amount": "0.00",
       "code": "USD"
     },
     "invoiceid": 2168250,
     "discount_total": {
       "amount": "0.00",
       "code": "USD"
     },
     "address": "",
     "invoice_number": "0000007",
     "customerid": 1831231,
     "discount_value": "0",
     "accounting_systemid": "zDmNq",
     "organization": "Microsoft",
     "due_offset_days": 30,
     "language": "en",
     "po_number": null,
     "display_status": "draft",
     "notes": "",
     "date_paid": null,
     "amount": {
       "amount": "8000.00",
       "code": "USD"
     },
     "street": "12 Pacific Highway",
     "city": "North Sydney",
     "currency_code": "USD",
     "sentid": 1,
     "autobill_status": null,
     "return_uri": null,
     "fname": "Wyatt",
     "created_at": "2016-09-01 16:16:14",
     "auto_bill": false,
     "accountid": "zDmNq"
       }
     }
   }
 }

Delete Single Invoice

Request: PUT

api.freshbooks.com/accounting/account/<accountid>/invoices/invoices/<id>


url = "api.freshbooks.com/accounting/account/<accountid>/invoices/invoices/<id&gt"
headers = {'Authorization': 'Bearer <bearer token>', 'Api-Version': 'alpha', 'Content-Type': 'application/json'}
payload = {'invoice': {
  'vis_state': 1
  }
}
res = reqests.put(url, data=json.dumps(payload), headers=headers)

Response:


{
  "response": {}
}

List Invoices

Request: GET

api.freshbooks.com/accounting/account/<accountid>/invoices/invoices


url = "api.freshbooks.com/accounting/account/<accountid>/invoices/invoices"
headers = {'Authorization': 'Bearer <bearer token>', 'Api-Version': 'alpha', 'Content-Type': 'application/json'}
res = requests.get(url, data=None, headers=headers)
jsonData = res.json()

Response:


{
  "response": {
     "result": {
        "invoices": [
          {
            // same format as single invoice
          },
          {
            // same format as single invoice
          },
          {
            // same format as single invoice
          }
        }
      ],
      "per_page": 15,
      "total": 2,
      "page": 1,
      "pages": 1
    }
  }
}

Invoices

General Info

*Requires Authorization*

Invoice Statuses

v3 Statuses

Includes

Filters

Field Descriptions

Invoice Lines

Optional cookies and other technologies

Requires Authorization