×
Freshbooks
Official App
Free – Google Play
Get it

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

CodeStatusDescription
0DisputedAn Invoice with the Dispute option enabled, which has been disputed by a Client. This is a feature of FreshBooks Classic only.
1DraftAn Invoice that has been created, but not yet sent.
2SentAn Invoice that has been sent to a Client or marked as sent by the Admin.
3ViewedAn Invoice that has been viewed by a Client.
4PaidA fully paid Invoice.
5Auto PaidAn Invoice paid automatically with a saved credit card.
6RetryAn 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.
7FailedAn Invoice that was in Retry status which again encountered a processing issue when being retried.
8PartialAn 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.

ValueDescription
createdobject is created and in no other state
draftobject is saved in draft status
sentobject has been sent
viewedobject has been viewed by receipient
failedan autobill related to the object has been tried more than once and failed
retryan autobill related to the object has been tried once and failed, and will be retried
successan autobill related to the object has succeeded
autopaida payment has been tied to the object automatically via autobill
paidpayments related to the object have succeeded and the object is fully paid
partialsome payment related to the object has succeeded but the invoice is not yet paid off
disputedthe object is disputed
resolvedthe object was disputed and the dispute has been marked as resolved
overduethe object required an action at an earlier date that was not met
deposit-partialthe object has a related deposit which has been partially paid
deposit-paidthe object has a related deposit which has been fully paid
declinedthe object has a related order which has been declined
pendingthe object has a related order which is pending

Includes

Include NameDescription
audit_logsshow invoice view/send/payment history
client_auditsshow the client-visible invoice history
commentscomments made on invoice
contactslist of client contacts
direct_linksdirect link to invoice
linesinvoice lines
ownerowner info
latest_journal_entryjournal entry info
allowed_gatewayslist of allowed gateways
late_feelate fee info
presentationpresentation type
late_reminderslate reminders
systeminvoice-owner's system

Filters

Filter TypeNameFieldDescription
Equalsinvoiceidinvoiceidmatches exact invoiceid
Ininvoiceidsinvoiceidmatches list of invoiceids, one per query argument specified
Likeinvoice _number _likeinvoice _numberinvoice number containing parameter
Equalsinvoice _numberinvoice _numbermatches exact invoice number
Likenotesnotesnotes containing parameter
StatusEq Filterstatusidspecialmatches exact invoice status
StatusIn Filterstatusidsspecialmatches list of invoice statuses, one per query argument specified
V3StatusEq Filterv3_statusspecialmatches exact v3_status
Equalscurrency _codecurrency _codematches exact currency code
Equalscurrencycurrency _codealternative to currency_code filter
Betweendate_mincreate_datedate greater than or equal to parameter, YYYY-MM-DD format
Betweendate_maxcreate_datedate less than parameter, YYYY-MM-DD format
Betweentotal_minamountamount greater than or equal to parameter
Betweentotal_maxamountamount less than parameter
Likepo_numberpo_numberpo_number containing parameter
Equalscustomeridcustomeridmatches exact customerid
Incustomeridscustomeridmatches list of customerids, one per query argument specified
Equalsparentidparentmatches exact parentid
PaidFilterpaidspecialtrue/false return paid invoices or unpaid invoices
Outstanding Filteroutstandingspecialtrue/false return outstanding or not outstanding invoices
Betweenupdated_minupdatedupdated date greater than or equal to parameter, YYYY-MM-DD format
Betweenupdated_maxupdatedupdated date less than parameter, YYYY-MM-DD format
ItemName Filteritem_namenameitem name containing the parameter
ItemDescriptionFilteritem _descriptiondescriptionitem description containing the parameter
Equalsprojectidprojectidmatches exact projectid
Outstanding AmountFilteroutstanding _minspecialmatches invoices with an outstanding amount greater than input

Field Descriptions

Computed Fields (read only)
FieldTypeDescription
invoiceidstringunique-to-this-system invoice id
idintunique-to-this-system invoice id, duplicate of invoiceid
accounting _systemidstringunique id for system
accountidstringunique id for system, repeat of accounting _systemid
amountstringtotal amount of invoice, to two decimal places
paidobjectsubfields: amount and code
amountstringamount paid on invoice, to two decimal places
codestringthree-letter currency code
outstandingobjectsubfields: amount, code
amountstringamount outstanding on invoice, to two decimal places
codestringthree-letter currency code
discount_totalobjectsubfields: amount and code
amountstringamount of discount, to two decimal places
codestringthree-letter currency code
descriptionstringdescription of first line of invoice
current _organizationstringName of organization being invoiced -- denormalized from client
due_datedatedate invoice is marked as due by, YYYY-MM-DD format, calculated from due_offset_days
date_paiddatedate invoice was fully paid, YYYY-MM-DD format
Writable on Create
FieldTypeDescription
owneridintid of creator of invoice. 1 if business admin, other if created by e.g. a contractor
estimateidintid of associated estimate, 0 if none
basecampidintid of connected basecamp account, 0 if none
sentidintuserid of user who sent the invoice, typically 1 for admin
statusstringSee Invoice Status table.
parentintid of object this invoice was generated from, 0 if none
created_atdatetimeTime the invoice was created, YYYY-MM-DD HH:MM:SS format
updateddatetimetime invoice last updated at, YYYY-MM-DD HH:MM:SS format
display_statusstringDescription of status shown in FreshBooks UI, one of 'draft', 'created', 'sent', 'viewed', or 'outstanding'.
autobill_statusstringone of retry, failed, or success
payment_statusstringdescription 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_statusstringdescribes status of last attempted payment
dispute_statusstringdescription of whether invoice has been disputed.
deposit_statusstringdescription of deposits applied to invoice. One of 'paid', 'unpaid', 'partial', 'none', and 'converted'.
auto_billbooleanwhether this invoice has a credit card saved
v3_statusstringdescription of Invoice Status, see V3 Status Table.
Data Fields (writable)
FieldTypeDescription
invoice_numberstringuser-specified and visible invoice id
customeridintunique-to-this-system client-id
create_datedatedate invoice was created, YYYY-MM-DD format
generation_datedatedate invoice generated from object, null if it wasn't, YYYY-MM-DD if it was
discount_valuestringdecimal-string amount
discount _descriptionstringpublic note about discount
po_numberstringPost Office box number for address on invoice.
templatestring(internal, deprecated) choice of rendering style
currency_codestringthree-letter currency code for invoice
languagestringtwo-letter language code, e.g. "en"
termsstringterms listed on invoice
notesstringNotes listed on invoice
addressstringFirst line of address on invoice
return_uristring(deprecated)
deposit_amountstringamount required as deposit, null if none
deposit _percentagestringpercent of the invoice's value required as a deposit
gmailbooleanwhether to send via ground mail
show_attachmentsbooleanwhether attachments on invoice are rendered
ext_archiveint(deprecated) 0 or 1 indicating archived or not
vis_stateint0 for active, 1 for deleted
streetstringstreet for address on invoice
street2stringsecond line of street for address on invoice.
citystringcity for address on invoice
provincestringProvince for address on invoice.
codestringzip code for address on invoice
countrystringCountry for address on invoice
organizationstringName of organization being invoiced.
fnamestringFirst name of Client on invoice
lnamestringLast name of client being invoiced
vat_namestringValue Added Tax name if provided
vat_numberstringValue Added Tax number if provided
due_offset_daysintNumber of days from creation that invoice is due

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"
      }
    }
  }
}

Update Single Invoice

Request: PUT api.freshbooks.com/accounting/account/<accountid>/invoices/invoices/<id>
{
  "invoice": {
     "email": "test@example.com",
     "customerid": 1831231,
     "create_date": "2016-04-04"
  }
}

Response:

{
  "response": {}
}

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
    }
  }
}