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.
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 |
| direct_links | direct link to invoice |
| 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
| Computed Fields (read only) | ||
|---|---|---|
| Field | Type | Description |
| invoiceid | string | 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 |
| 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 | decimal-string amount |
| discount _description | string | public note about discount |
| po_number | string | Post Office box 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 | string | 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 |
| lines | array | Lines of the invoice |
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.
| 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/td> |
| taxAmount1 | string | first tax amount, in percentage, up to 3 decimal places |
| taxName2 | string | name for the second tax on the invoice line/td> |
| taxAmount2 | string | second tax amount, in percentage, up to 3 decimal places |
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": 0,
"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": 0,
"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"
}
}
}
}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": 0,
"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
}
}
}