Invoices
Invoices
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 the Client owes to the Admin.
Invoices are created in a "Draft" status, and must be marked as sent or sent by email before they are recognized by accounting reports. See "Sending An Invoice" below.
If the invoice_number field is not specified in the request, FreshBooks generates an invoice_number value by incrementing the invoice_number of the previous invoice (for example, “0005” → “0006”, “000D” → “000E”). Otherwise, the user-provided invoice_number value is used.
For online payment options, see Online Payments.
For customizing the invoice appearance and attaching files, see Invoice Presentation and Attachments
Access Requirements
Access | Requires Authorization |
|
Creating Multiple Invoices
When creating multiple invoices concurrently and not specifying invoice_number in the request, there is a possibility of an invoice number collision (when two or more invoices with the same invoice_number are being processed). The FreshBooks API returns a 409 error in this case. Retrying a request with such failure will create an invoice successfully.
It is recommended to create multiple invoices either:
- Concurrently -
invoice_numbermust be specified in every request - Sequentially -
invoice_numbercan be specified or omitted
Sending An Invoice
Invoices are created in a “Draft” status and must be marked as sent or sent by email before accounting reports recognize them. A client cannot view an invoice link in “Draft” status.
Invoices can be marked as sent by a PUT request with the "action_mark_as_sent": true action or sent by email with the "action_email":true action and a list of "email_recipients". See the sidebar for examples.
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 and should only appear in migrated accounts |
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. |
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.
Value | Description |
|---|---|
created | Invoice is created and in no other state |
draft | Invoice is saved in draft status |
sent | Invoice has been sent |
viewed | Invoice has been viewed by receipient |
failed | an autobill related to the invoice has been tried more than once and failed |
retry | an autobill related to the invoice has been tried once and failed, and will be retried |
success | an autobill related to the invoice has succeeded |
autopaid | a payment has been tied to the invoice automatically via autobill |
paid | payments related to the invoice have succeeded and the object is fully paid |
partial | some payment related to the invoice has succeeded but the invoice is not yet paid off |
disputed | the invoice is disputed |
resolved | the invoice was disputed and the dispute has been marked as resolved |
overdue | the invoice required an action at an earlier date that was not met |
deposit-partial | the invoice has a related deposit which has been partially paid |
deposit-paid | the invoice has a related deposit which has been fully paid |
declined | the invoice has a related order which has been declined |
pending | the invoice 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 |
project_total_amounts | Total amounts billed from projects |
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 | Matches on notes containing the 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 returns paid invoices or unpaid invoices |
Outstanding Filter | outstanding | special | true/false returns 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 | special | Deprecated. Matches exact FreshBooks Classic projectid |
Equals | modern_projectid | line.modern_projectid | Matches on modern_projectid in invoice line items |
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 |
invoiceid |
id |
accounting_systemid |
accountid |
amount |
- amount |
- code |
paid |
- amount |
- code |
outstanding |
- amount |
- code |
discount_total |
- amount |
- code |
created_at |
current_organization |
date_paid |
description |
due_date |
updated |
Writable on Create |
Field |
ownerid |
estimateid |
sentid |
status |
parent |
display_status |
autobill_status |
payment_status |
last_order_status |
dispute_status |
deposit_status |
auto_bill |
v3_status |
Data Fields (writable) |
Field |
invoice_number |
customerid |
create_date |
generation_date |
discount_value |
discount _description |
po_number |
template |
currency_code |
language |
terms |
notes |
address |
return_uri |
deposit_amount |
deposit _percentage |
gmail |
show_attachments |
ext_archive |
vis_state |
street |
street2 |
city |
province |
code |
country |
organization |
fname |
lname |
vat_name |
vat_number |
due_offset_days |
lines |
presentation |
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 |
lineid |
amount |
amount |
code |
updated |
Data Fields (writable) |
Field |
type |
expenseid |
qty |
unit_cost |
- amount |
- code |
description |
name |
modern_project_id |
modern_time_entries |
taxName1 |
taxAmount1 |
taxName2 |
taxAmount2 |
List Invoices
curl -L -X GET 'https://api.freshbooks.com/accounting/account/<accountId>/invoices/invoices'
-H 'Authorization: Bearer <insert-bearer-token>'
#Response:
{
"response": {
"result": {
"invoices": [
{
"accountid": "LJArJ4",
"accounting_systemid": "LJArJ4",
"address": "",
"amount": {
"amount": "104.50",
"code": "CAD"
},
"auto_bill": false,
"autobill_status": null,
"basecampid": 0,
"city": "",
"code": "",
"country": "Canada",
"create_date": "2021-07-05",
"created_at": "2021-07-05 08:17:47",
"currency_code": "CAD",
"current_organization": "First1 Last1",
"customerid": 806,
"date_paid": null,
"deposit_amount": null,
"deposit_percentage": null,
"deposit_status": "none",
"description": "",
"discount_description": null,
"discount_total": {
"amount": "-5.00",
"code": "CAD"
},
"discount_value": "5",
"display_status": "draft",
"dispute_status": null,
"due_date": "2021-07-05",
"due_offset_days": 0,
"estimateid": 0,
"ext_archive": 0,
"fname": "First1",
"fulfillment_date": null,
"generation_date": null,
"gmail": false,
"id": 324,
"invoice_number": "0000007",
"invoiceid": 324,
"language": "en",
"last_order_status": null,
"lname": "Last1",
"net_paid_amount": {
"amount": "0.00",
"code": "CAD"
},
"notes": "Added a 5% discount for your continued support",
"organization": "First1 Last1",
"outstanding": {
"amount": "104.50",
"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": false,
"status": 1,
"street": "",
"street2": "",
"template": "clean-grouped",
"terms": "Please pay the invoice within 30 days",
"updated": "2021-07-05 08:17:47",
"uuid": "1a82a641-6683-466c-a522-6384c15c5357",
"v3_status": "draft",
"vat_name": null,
"vat_number": "",
"version": "2021-07-05 08:17:47.399872",
"vis_state": 0
},
{
"accountid": "LJArJ4",
"accounting_systemid": "LJArJ4",
"address": "",
"amount": {
"amount": "104.50",
"code": "CAD"
},
"auto_bill": false,
"autobill_status": null,
"basecampid": 0,
"city": "",
"code": "",
"country": "Canada",
"create_date": "2021-07-05",
"created_at": "2021-07-05 08:13:53",
"currency_code": "CAD",
"current_organization": "First1 Last1",
"customerid": 806,
"date_paid": null,
"deposit_amount": null,
"deposit_percentage": null,
"deposit_status": "none",
"description": "",
"discount_description": null,
"discount_total": {
"amount": "-5.00",
"code": "CAD"
},
"discount_value": "5",
"display_status": "sent",
"dispute_status": null,
"due_date": "2021-07-05",
"due_offset_days": 0,
"estimateid": 0,
"ext_archive": 0,
"fname": "First1",
"fulfillment_date": "2021-07-05",
"generation_date": null,
"gmail": false,
"id": 322,
"invoice_number": "0000006",
"invoiceid": 322,
"language": "en",
"last_order_status": null,
"lname": "Last1",
"net_paid_amount": {
"amount": "0.00",
"code": "CAD"
},
"notes": "Added a 5% discount for your continued support",
"organization": "First1 Last1",
"outstanding": {
"amount": "104.50",
"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": false,
"status": 2,
"street": "",
"street2": "",
"template": "clean-grouped",
"terms": "Please pay the invoice within 30 days",
"updated": "2021-07-05 08:13:55",
"uuid": "e4afb55b-0bca-4783-94be-818a41097138",
"v3_status": "sent",
"vat_name": null,
"vat_number": "",
"version": "2021-07-05 08:13:55.185882",
"vis_state": 0
},
{
"accountid": "LJArJ4",
"accounting_systemid": "LJArJ4",
"address": "",
"amount": {
"amount": "310.00",
"code": "CAD"
},
"auto_bill": false,
"autobill_status": null,
"basecampid": 0,
"city": "",
"code": "",
"country": "Canada",
"create_date": "2021-07-05",
"created_at": "2021-07-05 08:10:53",
"currency_code": "CAD",
"current_organization": "First1 Last1",
"customerid": 806,
"date_paid": null,
"deposit_amount": null,
"deposit_percentage": null,
"deposit_status": "none",
"description": "Jul 5, 2021 - Paid social media campaign",
"discount_description": null,
"discount_total": {
"amount": "0.00",
"code": "CAD"
},
"discount_value": "0",
"display_status": "draft",
"dispute_status": null,
"due_date": "2021-07-05",
"due_offset_days": 0,
"estimateid": 0,
"ext_archive": 0,
"fname": "First1",
"fulfillment_date": null,
"generation_date": null,
"gmail": false,
"id": 321,
"invoice_number": "0000005",
"invoiceid": 321,
"language": "en",
"last_order_status": null,
"lname": "Last1",
"net_paid_amount": {
"amount": "0.00",
"code": "CAD"
},
"notes": "Unbilled Expenses added",
"organization": "First1 Last1",
"outstanding": {
"amount": "310.00",
"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": false,
"status": 1,
"street": "",
"street2": "",
"template": "clean-grouped",
"terms": "Please pay the invoice within 30 days",
"updated": "2021-07-05 08:10:53",
"uuid": "c5122940-f746-45eb-a75d-d18fb031f884",
"v3_status": "draft",
"vat_name": null,
"vat_number": "",
"version": "2021-07-05 08:10:53.604805",
"vis_state": 0
},
{
"accountid": "LJArJ4",
"accounting_systemid": "LJArJ4",
"address": "",
"amount": {
"amount": "110.00",
"code": "CAD"
},
"auto_bill": false,
"autobill_status": null,
"basecampid": 0,
"city": "",
"code": "",
"country": "Canada",
"create_date": "2021-07-05",
"created_at": "2021-07-05 08:06:38",
"currency_code": "CAD",
"current_organization": "First1 Last1",
"customerid": 806,
"date_paid": null,
"deposit_amount": null,
"deposit_percentage": null,
"deposit_status": "none",
"description": "",
"discount_description": null,
"discount_total": {
"amount": "0.00",
"code": "CAD"
},
"discount_value": "0",
"display_status": "sent",
"dispute_status": null,
"due_date": "2021-07-05",
"due_offset_days": 0,
"estimateid": 0,
"ext_archive": 0,
"fname": "First1",
"fulfillment_date": "2021-07-05",
"generation_date": null,
"gmail": false,
"id": 319,
"invoice_number": "0000004",
"invoiceid": 319,
"language": "en",
"last_order_status": null,
"lname": "Last1",
"net_paid_amount": {
"amount": "0.00",
"code": "CAD"
},
"notes": "Unbilled Expenses added",
"organization": "First1 Last1",
"outstanding": {
"amount": "110.00",
"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": false,
"status": 2,
"street": "",
"street2": "",
"template": "clean-grouped",
"terms": "Please pay the invoice within 30 days",
"updated": "2021-07-05 08:09:20",
"uuid": "8e13f65b-0380-4d6a-a951-76ed037b8246",
"v3_status": "sent",
"vat_name": null,
"vat_number": "",
"version": "2021-07-05 08:09:20.332731",
"vis_state": 0
},
{
"accountid": "LJArJ4",
"accounting_systemid": "LJArJ4",
"address": "",
"amount": {
"amount": "110.00",
"code": "CAD"
},
"auto_bill": false,
"autobill_status": null,
"basecampid": 0,
"city": "",
"code": "",
"country": "Canada",
"create_date": "2021-07-05",
"created_at": "2021-07-05 07:59:58",
"currency_code": "CAD",
"current_organization": "First1 Last1",
"customerid": 806,
"date_paid": null,
"deposit_amount": null,
"deposit_percentage": null,
"deposit_status": "none",
"description": "",
"discount_description": null,
"discount_total": {
"amount": "0.00",
"code": "CAD"
},
"discount_value": "0",
"display_status": "draft",
"dispute_status": null,
"due_date": "2021-07-05",
"due_offset_days": 0,
"estimateid": 0,
"ext_archive": 0,
"fname": "First1",
"fulfillment_date": null,
"generation_date": null,
"gmail": false,
"id": 317,
"invoice_number": "0000003",
"invoiceid": 317,
"language": "en",
"last_order_status": null,
"lname": "Last1",
"net_paid_amount": {
"amount": "0.00",
"code": "CAD"
},
"notes": "These are Invoice notes",
"organization": "First1 Last1",
"outstanding": {
"amount": "110.00",
"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": false,
"status": 1,
"street": "",
"street2": "",
"template": "clean-grouped",
"terms": "Please pay the invoice within 30 days",
"updated": "2021-07-05 07:59:58",
"uuid": "5a1a3e97-082a-4954-80bf-82c8ab38925c",
"v3_status": "draft",
"vat_name": null,
"vat_number": "",
"version": "2021-07-05 07:59:58.717874",
"vis_state": 0
},
{
"accountid": "LJArJ4",
"accounting_systemid": "LJArJ4",
"address": "",
"amount": {
"amount": "110.00",
"code": "CAD"
},
"auto_bill": false,
"autobill_status": null,
"basecampid": 0,
"city": "",
"code": "",
"country": "Canada",
"create_date": "2021-07-05",
"created_at": "2021-07-05 07:58:08",
"currency_code": "CAD",
"current_organization": "First1 Last1",
"customerid": 806,
"date_paid": null,
"deposit_amount": null,
"deposit_percentage": null,
"deposit_status": "none",
"description": "",
"discount_description": null,
"discount_total": {
"amount": "0.00",
"code": "CAD"
},
"discount_value": "0",
"display_status": "draft",
"dispute_status": null,
"due_date": "2021-07-05",
"due_offset_days": 0,
"estimateid": 0,
"ext_archive": 0,
"fname": "First1",
"fulfillment_date": null,
"generation_date": null,
"gmail": false,
"id": 316,
"invoice_number": "0000002",
"invoiceid": 316,
"language": "en",
"last_order_status": null,
"lname": "Last1",
"net_paid_amount": {
"amount": "0.00",
"code": "CAD"
},
"notes": "These are Invoice notes",
"organization": "First1 Last1",
"outstanding": {
"amount": "110.00",
"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": false,
"status": 1,
"street": "",
"street2": "",
"template": "clean-grouped",
"terms": "Please pay the invoice within 30 days",
"updated": "2021-07-05 07:58:08",
"uuid": "36e917f4-38f8-4c74-b9b9-404fe0e0bdec",
"v3_status": "draft",
"vat_name": null,
"vat_number": "",
"version": "2021-07-05 07:58:08.297868",
"vis_state": 0
},
{
"accountid": "LJArJ4",
"accounting_systemid": "LJArJ4",
"address": "",
"amount": {
"amount": "5000.00",
"code": "USD"
},
"auto_bill": false,
"autobill_status": null,
"basecampid": 0,
"city": "",
"code": "",
"country": "Canada",
"create_date": "2021-07-05",
"created_at": "2021-07-05 07:46:40",
"currency_code": "USD",
"current_organization": "First1 Last1",
"customerid": 806,
"date_paid": null,
"deposit_amount": null,
"deposit_percentage": null,
"deposit_status": "none",
"description": "",
"discount_description": null,
"discount_total": {
"amount": "0.00",
"code": "USD"
},
"discount_value": "0",
"display_status": "draft",
"dispute_status": null,
"due_date": "2021-07-05",
"due_offset_days": 0,
"estimateid": 0,
"ext_archive": 0,
"fname": "First1",
"fulfillment_date": null,
"generation_date": null,
"gmail": false,
"id": 306,
"invoice_number": "0000001",
"invoiceid": 306,
"language": "en",
"last_order_status": null,
"lname": "Last1",
"net_paid_amount": {
"amount": "0.00",
"code": "USD"
},
"notes": "",
"organization": "First1 Last1",
"outstanding": {
"amount": "5000.00",
"code": "USD"
},
"ownerid": 1,
"paid": {
"amount": "0.00",
"code": "USD"
},
"parent": 0,
"payment_details": "",
"payment_status": "unpaid",
"po_number": null,
"province": "",
"return_uri": null,
"sentid": 1,
"show_attachments": true,
"status": 1,
"street": "",
"street2": "",
"template": "clean-grouped",
"terms": "",
"updated": "2021-07-05 07:46:40",
"uuid": "1aaee764-05fc-41c8-bfbb-6e58eaaf6352",
"v3_status": "draft",
"vat_name": "",
"vat_number": "",
"version": "2021-07-05 07:46:40.676008",
"vis_state": 0
}
],
"page": 1,
"pages": 1,
"per_page": 15,
"total": 7
}
}
}
Get Single Invoice
curl -L -X GET 'https://api.freshbooks.com/accounting/account/<accountId>/invoices/invoices/<invoiceId>'
-H 'Authorization: Bearer <insert-bearer-token>'
#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 Invoice
curl -L -X POST 'https://api.freshbooks.com/accounting/account/<accountId>/invoices/invoices'
-H 'Content-Type: application/json'
-H 'Authorization: Bearer <insert-bearer-token>'
--data-raw '{
"invoice": {
"allowed_gateway_name": null,
"deposit_percentage": null,
"due_offset_days": 30,
"estimateid": null,
"highlight_string": null,
"sender_name": null,
"invoiceid": null,
"invoice_client_id": null,
"language": "en",
"last_order_status": null,
"city": "",
"country": "United States",
"create_date": "2021-08-17",
"currency_code": "USD",
"discount_value": 0,
"fname": "F_Name",
"lname": "L_Name",
"notes": "Enter notes or Bank transfer details",
"invoice_number": "0000003",
"status": 2,
"organization": "Test Client company",
"code": "",
"po_number": null,
"province": "",
"street": "",
"street2": "",
"template": "clean-grouped",
"terms": "Enter your terms and conditions here, for example, pay within 30 days to avoid late fees.",
"payment_details": null,
"vat_name": null,
"vat_number": "",
"allowed_gateway_info": null,
"attachments": [],
"contacts": [
{
"contactid": "-1"
}
],
"direct_links": [],
"async_invoice_profile": null,
"late_fee": {
"compounded_taxes": false,
"days": 30,
"enabled": true,
"first_tax_name": null,
"first_tax_percent": 0,
"repeat": false,
"second_tax_name": null,
"second_tax_percent": 0,
"type": "percent",
"calculation_type": "total",
"value": 10
},
"late_reminders": [
{
"body": "Kindly pay within 27 days to avoid late payment fees",
"enabled": true,
"delay": 3,
"position": 1
},
{
"body": "Kindly pay within 15 days to avoid late payment fees",
"enabled": true,
"delay": 15,
"position": 2
}
],
"lines": [
{
"modern_project_id": null,
"retainer_id": null,
"retainer_period_id": null,
"amount": {
"amount": "240",
"code": "USD"
},
"description": "",
"expenseid": null,
"taxName1": "GST",
"taxAmount1": 10,
"name": "Photography Services",
"qty": 1,
"taxName2": null,
"taxAmount2": null,
"compounded_tax": false,
"type": null,
"unit_cost": {
"amount": "240",
"code": "USD"
},
"invoiceid": null
}
],
"owner": null,
"presentation": {
"id": "last",
"theme_font_name": "modern",
"theme_primary_color": "#4F697A",
"theme_layout": "simple",
"date_format": "mm/dd/yyyy",
"image_banner_position_y": 0,
"image_logo_src": null,
"image_banner_src": null
},
"transactioninvoiceid": null,
"payment_schedule": [],
"customerid": "2280"
}
}'
#Response:
{
"response": {
"result": {
"invoice": {
"accountid": "pJ1705",
"accounting_systemid": "pJ1705",
"address": "",
"amount": {
"amount": "264.00",
"code": "USD"
},
"auto_bill": false,
"autobill_status": null,
"basecampid": 0,
"city": "",
"code": "",
"country": "United States",
"create_date": "2021-08-17",
"created_at": "2021-08-17 08:20:11",
"currency_code": "USD",
"current_organization": "Test Client company",
"customerid": 2280,
"date_paid": null,
"deposit_amount": null,
"deposit_percentage": null,
"deposit_status": "none",
"description": "",
"discount_description": null,
"discount_total": {
"amount": "0.00",
"code": "USD"
},
"discount_value": "0",
"display_status": "sent",
"dispute_status": null,
"due_date": "2021-09-16",
"due_offset_days": 30,
"estimateid": 0,
"ext_archive": 0,
"fname": "F_Name",
"fulfillment_date": "2021-08-17",
"generation_date": null,
"gmail": false,
"id": 1627,
"invoice_number": "0000003",
"invoiceid": 1627,
"language": "en",
"last_order_status": null,
"lname": "L_Name",
"net_paid_amount": {
"amount": "0.00",
"code": "USD"
},
"notes": "Enter notes or Bank transfer details",
"organization": "Test Client company",
"outstanding": {
"amount": "264.00",
"code": "USD"
},
"ownerid": 1,
"paid": {
"amount": "0.00",
"code": "USD"
},
"parent": 0,
"payment_details": "",
"payment_status": "unpaid",
"po_number": null,
"province": "",
"return_uri": null,
"sentid": 1,
"show_attachments": false,
"status": 2,
"street": "",
"street2": "",
"template": "clean-grouped",
"terms": "Enter your terms and conditions here, for example, pay within 30 days to avoid late fees.",
"updated": "2021-08-17 08:20:12",
"uuid": "3664b9d4-31b8-4cad-8a1a-e8449e8e401b",
"v3_status": "sent",
"vat_name": null,
"vat_number": "",
"version": "2021-08-17 08:20:12.082129",
"vis_state": 0
}
}
}
}
Create Invoice With An Unbilled Expense
curl -L -X POST 'https://api.freshbooks.com/accounting/account/<accountId>/invoices/invoices'
-H 'Content-Type: application/json'
-H 'Authorization: Bearer <insert-bearer-token>'
--data-raw '{
"invoice": {
"allowed_gateway_name": null,
"deposit_percentage": null,
"due_offset_days": 0,
"estimateid": null,
"highlight_string": null,
"sender_name": null,
"invoiceid": null,
"invoice_client_id": null,
"language": "en",
"last_order_status": null,
"city": "",
"country": "Canada",
"create_date": "2021-07-05",
"currency_code": "CAD",
"discount_value": 0,
"fname": "First1",
"lname": "Last1",
"notes": "Unbilled Expenses added",
"organization": "First1 Last1",
"code": "",
"po_number": null,
"province": "",
"street": "",
"street2": "",
"template": "clean-grouped",
"terms": "Please pay the invoice within 30 days",
"payment_details": null,
"vat_name": null,
"vat_number": "",
"allowed_gateway_info": null,
"attachments": [],
"contacts": [
{
"contactid": "-1"
}
],
"direct_links": [],
"async_invoice_profile": null,
"late_fee": {
"compounded_taxes": false,
"days": 30,
"enabled": false,
"first_tax_name": null,
"first_tax_percent": 0,
"repeat": false,
"second_tax_name": null,
"second_tax_percent": 0,
"type": "percent",
"calculation_type": "total",
"value": 10
},
"late_reminders": [],
"lines": [
{
"modern_project_id": null,
"retainer_id": null,
"retainer_period_id": null,
"amount": {
"amount": "100",
"code": "CAD"
},
"description": "",
"expenseid": null,
"taxName1": "GST",
"taxAmount1": 10,
"name": "Item1",
"qty": 1,
"taxName2": null,
"taxAmount2": null,
"compounded_tax": false,
"type": null,
"unit_cost": {
"amount": "100",
"code": "CAD"
},
"invoiceid": null
},
{
"modern_project_id": null,
"retainer_id": null,
"retainer_period_id": null,
"amount": {
"amount": "200",
"code": "CAD"
},
"description": "Jul 5, 2021 - Paid social media campaign",
"expenseid": 567,
"taxName1": "",
"taxAmount1": 0,
"name": "ABZ Creatives",
"qty": 1,
"taxName2": "",
"taxAmount2": 0,
"compounded_tax": false,
"type": 1,
"unit_cost": {
"amount": "200",
"code": "CAD"
},
"invoiceid": null
}
],
"owner": null,
"transactioninvoiceid": null,
"customerid": "806"
}
}'
#Response:
{
"response": {
"result": {
"invoice": {
"accountid": "LJArJ4",
"accounting_systemid": "LJArJ4",
"address": "",
"amount": {
"amount": "310.00",
"code": "CAD"
},
"auto_bill": false,
"autobill_status": null,
"basecampid": 0,
"city": "",
"code": "",
"country": "Canada",
"create_date": "2021-07-05",
"created_at": "2021-07-05 08:10:53",
"currency_code": "CAD",
"current_organization": "First1 Last1",
"customerid": 806,
"date_paid": null,
"deposit_amount": null,
"deposit_percentage": null,
"deposit_status": "none",
"description": "Jul 5, 2021 - Paid social media campaign",
"discount_description": null,
"discount_total": {
"amount": "0.00",
"code": "CAD"
},
"discount_value": "0",
"display_status": "draft",
"dispute_status": null,
"due_date": "2021-07-05",
"due_offset_days": 0,
"estimateid": 0,
"ext_archive": 0,
"fname": "First1",
"fulfillment_date": null,
"generation_date": null,
"gmail": false,
"id": 321,
"invoice_number": "0000005",
"invoiceid": 321,
"language": "en",
"last_order_status": null,
"lname": "Last1",
"net_paid_amount": {
"amount": "0.00",
"code": "CAD"
},
"notes": "Unbilled Expenses added",
"organization": "First1 Last1",
"outstanding": {
"amount": "310.00",
"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": false,
"status": 1,
"street": "",
"street2": "",
"template": "clean-grouped",
"terms": "Please pay the invoice within 30 days",
"updated": "2021-07-05 08:10:53",
"uuid": "c5122940-f746-45eb-a75d-d18fb031f884",
"v3_status": "draft",
"vat_name": null,
"vat_number": "",
"version": "2021-07-05 08:10:53.604805",
"vis_state": 0
}
}
}
}
Create Invoice With Discount Value
curl -L -X POST 'https://api.freshbooks.com/accounting/account/<accountId>/invoices/invoices'
-H 'Content-Type: application/json'
-H 'Authorization: Bearer <insert-bearer-token>'
--data-raw '{
"invoice": {
"allowed_gateway_name": null,
"deposit_percentage": null,
"due_offset_days": 0,
"estimateid": null,
"highlight_string": null,
"sender_name": null,
"invoiceid": null,
"invoice_client_id": null,
"language": "en",
"last_order_status": null,
"city": "",
"country": "Canada",
"create_date": "2021-07-05",
"currency_code": "CAD",
"discount_value": 5,
"fname": "First1",
"lname": "Last1",
"notes": "Added a 5% discount for your continued support",
"organization": "First1 Last1",
"code": "",
"po_number": null,
"province": "",
"street": "",
"street2": "",
"template": "clean-grouped",
"terms": "Please pay the invoice within 30 days",
"payment_details": null,
"vat_name": null,
"vat_number": "",
"allowed_gateway_info": null,
"attachments": [],
"contacts": [
{
"contactid": "-1"
}
],
"direct_links": [],
"async_invoice_profile": null,
"late_fee": {
"compounded_taxes": false,
"days": 30,
"enabled": false,
"first_tax_name": null,
"first_tax_percent": 0,
"repeat": false,
"second_tax_name": null,
"second_tax_percent": 0,
"type": "percent",
"calculation_type": "total",
"value": 10
},
"late_reminders": [],
"lines": [
{
"modern_project_id": null,
"retainer_id": null,
"retainer_period_id": null,
"amount": {
"amount": "100",
"code": "CAD"
},
"description": "",
"expenseid": null,
"taxName1": "GST",
"taxAmount1": 10,
"name": "Item1",
"qty": 1,
"taxName2": null,
"taxAmount2": null,
"compounded_tax": false,
"type": null,
"unit_cost": {
"amount": "100",
"code": "CAD"
},
"invoiceid": null
},
{
"modern_project_id": null,
"retainer_id": null,
"retainer_period_id": null,
"amount": {
"amount": "0",
"code": "CAD"
},
"description": "",
"expenseid": null,
"taxName1": "",
"taxAmount1": 0,
"name": "",
"qty": 1,
"taxName2": "",
"taxAmount2": 0,
"compounded_tax": false,
"type": null,
"unit_cost": {
"amount": "0",
"code": "CAD"
},
"invoiceid": null
}
],
"customerid": "806"
}
}'
#Response:
{
"response": {
"result": {
"invoice": {
"accountid": "LJArJ4",
"accounting_systemid": "LJArJ4",
"address": "",
"amount": {
"amount": "104.50",
"code": "CAD"
},
"auto_bill": false,
"autobill_status": null,
"basecampid": 0,
"city": "",
"code": "",
"country": "Canada",
"create_date": "2021-07-05",
"created_at": "2021-07-05 08:18:37",
"currency_code": "CAD",
"current_organization": "First1 Last1",
"customerid": 806,
"date_paid": null,
"deposit_amount": null,
"deposit_percentage": null,
"deposit_status": "none",
"description": "",
"discount_description": null,
"discount_total": {
"amount": "-5.00",
"code": "CAD"
},
"discount_value": "5",
"display_status": "draft",
"dispute_status": null,
"due_date": "2021-07-05",
"due_offset_days": 0,
"estimateid": 0,
"ext_archive": 0,
"fname": "First1",
"fulfillment_date": null,
"generation_date": null,
"gmail": false,
"id": 325,
"invoice_number": "0000008",
"invoiceid": 325,
"language": "en",
"last_order_status": null,
"lname": "Last1",
"net_paid_amount": {
"amount": "0.00",
"code": "CAD"
},
"notes": "Added a 5% discount for your continued support",
"organization": "First1 Last1",
"outstanding": {
"amount": "104.50",
"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": false,
"status": 1,
"street": "",
"street2": "",
"template": "clean-grouped",
"terms": "Please pay the invoice within 30 days",
"updated": "2021-07-05 08:18:37",
"uuid": "cef2ca31-1139-4495-855e-e3c7f500c970",
"v3_status": "draft",
"vat_name": null,
"vat_number": "",
"version": "2021-07-05 08:18:37.418744",
"vis_state": 0
}
}
}
}
Update Invoice
curl -L -X PUT 'https://api.freshbooks.com/accounting/account/<accountId>/invoices/invoices/<invoiceId>'
-H 'Content-Type: application/json'
-H 'Authorization: Bearer <insert-bearer-token>'
--data-raw '{
"invoice": {
"due_offset_days": 20
}
}'
#Response:
{
"response": {
"result": {
"invoice": {
"accountid": "LJArJ4",
"accounting_systemid": "LJArJ4",
"address": "",
"amount": {
"amount": "104.50",
"code": "CAD"
},
"auto_bill": false,
"autobill_status": null,
"basecampid": 0,
"city": "",
"code": "",
"country": "Canada",
"create_date": "2021-07-05",
"created_at": "2021-07-05 08:18:37",
"currency_code": "CAD",
"current_organization": "First1 Last1",
"customerid": 806,
"date_paid": null,
"deposit_amount": null,
"deposit_percentage": null,
"deposit_status": "none",
"description": "",
"discount_description": null,
"discount_total": {
"amount": "-5.00",
"code": "CAD"
},
"discount_value": "5",
"display_status": "sent",
"dispute_status": null,
"due_date": "2021-07-25",
"due_offset_days": 20,
"estimateid": 0,
"ext_archive": 0,
"fname": "First1",
"fulfillment_date": "2021-07-05",
"generation_date": null,
"gmail": false,
"id": 325,
"invoice_number": "0000008",
"invoiceid": 325,
"language": "en",
"last_order_status": null,
"lname": "Last1",
"net_paid_amount": {
"amount": "0.00",
"code": "CAD"
},
"notes": "Added a 5% discount for your continued support",
"organization": "First1 Last1",
"outstanding": {
"amount": "104.50",
"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": false,
"status": 2,
"street": "",
"street2": "",
"template": "clean-grouped",
"terms": "Please pay the invoice within 30 days",
"updated": "2021-07-05 08:22:13",
"uuid": "cef2ca31-1139-4495-855e-e3c7f500c970",
"v3_status": "sent",
"vat_name": null,
"vat_number": "",
"version": "2021-07-05 08:22:13.174445",
"vis_state": 0
}
}
}
}
Mark Invoice As Sent
curl -L -X PUT 'https://api.freshbooks.com/accounting/account/<accountId>/invoices/invoices/<invoiceId>'
-H 'Content-Type: application/json'
-H 'Authorization: Bearer <insert-bearer-token>'
--data-raw '{
"invoice": {
"action_mark_as_sent": true
}
}'
#Response:
{
"response": {
"result": {
"invoice": {
"accountid": "LJArJ4",
"accounting_systemid": "LJArJ4",
"address": "",
"amount": {
"amount": "104.50",
"code": "CAD"
},
"auto_bill": false,
"autobill_status": null,
"basecampid": 0,
"city": "",
"code": "",
"country": "Canada",
"create_date": "2021-07-05",
"created_at": "2021-07-05 08:18:37",
"currency_code": "CAD",
"current_organization": "First1 Last1",
"customerid": 806,
"date_paid": null,
"deposit_amount": null,
"deposit_percentage": null,
"deposit_status": "none",
"description": "",
"discount_description": null,
"discount_total": {
"amount": "-5.00",
"code": "CAD"
},
"discount_value": "5",
"display_status": "sent",
"dispute_status": null,
"due_date": "2021-07-25",
"due_offset_days": 20,
"estimateid": 0,
"ext_archive": 0,
"fname": "First1",
"fulfillment_date": "2021-07-05",
"generation_date": null,
"gmail": false,
"id": 325,
"invoice_number": "0000008",
"invoiceid": 325,
"language": "en",
"last_order_status": null,
"lname": "Last1",
"net_paid_amount": {
"amount": "0.00",
"code": "CAD"
},
"notes": "Added a 5% discount for your continued support",
"organization": "First1 Last1",
"outstanding": {
"amount": "104.50",
"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": false,
"status": 2,
"street": "",
"street2": "",
"template": "clean-grouped",
"terms": "Please pay the invoice within 30 days",
"updated": "2021-07-05 08:22:13",
"uuid": "cef2ca31-1139-4495-855e-e3c7f500c970",
"v3_status": "sent",
"vat_name": null,
"vat_number": "",
"version": "2021-07-05 08:22:13.174445",
"vis_state": 2
}
}
}
}
Send Invoice By Email
curl -L -X PUT 'https://api.freshbooks.com/accounting/account/<accountId>/invoices/invoices/<invoiceId>'
-H 'Content-Type: application/json'
-H 'Authorization: Bearer <insert-bearer-token>'
--data-raw '{
"invoice": {
"action_email": true
"email_recipients": ["dtherockjohnson@freshbooks.com", "beilish@freshbooks.com"],
"email_include_pdf": false,
"invoice_customized_email": {
"subject": "Thanks for being a customer",
"body": "This can be any personal message",
}
}
}'
#Response:
{
"response": {
"result": {
"invoice": {
"accountid": "LJArJ4",
"accounting_systemid": "LJArJ4",
"address": "",
"amount": {
"amount": "104.50",
"code": "CAD"
},
"auto_bill": false,
"autobill_status": null,
"basecampid": 0,
"city": "",
"code": "",
"country": "Canada",
"create_date": "2021-07-05",
"created_at": "2021-07-05 08:18:37",
"currency_code": "CAD",
"current_organization": "First1 Last1",
"customerid": 806,
"date_paid": null,
"deposit_amount": null,
"deposit_percentage": null,
"deposit_status": "none",
"description": "",
"discount_description": null,
"discount_total": {
"amount": "-5.00",
"code": "CAD"
},
"discount_value": "5",
"display_status": "sent",
"dispute_status": null,
"due_date": "2021-07-25",
"due_offset_days": 20,
"estimateid": 0,
"ext_archive": 0,
"fname": "First1",
"fulfillment_date": "2021-07-05",
"generation_date": null,
"gmail": false,
"id": 325,
"invoice_number": "0000008",
"invoiceid": 325,
"language": "en",
"last_order_status": null,
"lname": "Last1",
"net_paid_amount": {
"amount": "0.00",
"code": "CAD"
},
"notes": "Added a 5% discount for your continued support",
"organization": "First1 Last1",
"outstanding": {
"amount": "104.50",
"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": false,
"status": 2,
"street": "",
"street2": "",
"template": "clean-grouped",
"terms": "Please pay the invoice within 30 days",
"updated": "2021-07-05 08:22:13",
"uuid": "cef2ca31-1139-4495-855e-e3c7f500c970",
"v3_status": "sent",
"vat_name": null,
"vat_number": "",
"version": "2021-07-05 08:22:13.174445",
"vis_state": 2
}
}
}
}
Delete Invoice
curl -L -X DELETE 'https://api.freshbooks.com/accounting/account/<accountId>/invoices/invoices/<invoiceId>'
-H 'Content-Type: application/json'
-H 'Authorization: Bearer <insert-bearer-token>'
--data-raw '{
"invoice": {
"vis_state": 1
}
}'
#Response:
{
"response": {
"result": {
"invoice": {
"accountid": "LJArJ4",
"accounting_systemid": "LJArJ4",
"address": "",
"amount": {
"amount": "104.50",
"code": "CAD"
},
"auto_bill": false,
"autobill_status": null,
"basecampid": 0,
"city": "",
"code": "",
"country": "Canada",
"create_date": "2021-07-05",
"created_at": "2021-07-05 08:18:37",
"currency_code": "CAD",
"current_organization": "First1 Last1",
"customerid": 806,
"date_paid": null,
"deposit_amount": null,
"deposit_percentage": null,
"deposit_status": "none",
"description": "",
"discount_description": null,
"discount_total": {
"amount": "-5.00",
"code": "CAD"
},
"discount_value": "5",
"display_status": "sent",
"dispute_status": null,
"due_date": "2021-07-25",
"due_offset_days": 20,
"estimateid": 0,
"ext_archive": 0,
"fname": "First1",
"fulfillment_date": "2021-07-05",
"generation_date": null,
"gmail": false,
"id": 325,
"invoice_number": "0000008",
"invoiceid": 325,
"language": "en",
"last_order_status": null,
"lname": "Last1",
"net_paid_amount": {
"amount": "0.00",
"code": "CAD"
},
"notes": "Added a 5% discount for your continued support",
"organization": "First1 Last1",
"outstanding": {
"amount": "104.50",
"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": false,
"status": 2,
"street": "",
"street2": "",
"template": "clean-grouped",
"terms": "Please pay the invoice within 30 days",
"updated": "2021-07-05 08:25:16",
"uuid": "cef2ca31-1139-4495-855e-e3c7f500c970",
"v3_status": "sent",
"vat_name": null,
"vat_number": "",
"version": "2021-07-05 08:25:16.973795",
"vis_state": 1
}
}
}
}