×
FreshBooks
Official App
Free – Google Play
Get it
Hey there - We have updated our privacy policy in accordance with GDPR. Got It
×

Invoice Profiles

General Info

Invoice Profiles are used to create recurring invoices. They have the ability to be saved as a draft invoice or be automatically sent out to the client via email.

*Requires Authorization*

Includes

Include NameDescription
allowed_gatewayslist of allowed gateways
audit_logsa summarization of the invoice for audit purposes
contactscontains contact objects populated with the client's data
late_feelate fee info
late-reminderslate reminders
linesinvoice lines
presentationdata representing the stylings of the invoice. i.e. (Modern vs Classic)
systeminvoice-owner's system
trackinginformation regarding previous invoices
next_issue_datethe date that the next invoice will be issued
project_formatincludes information about how the associated project is formated

Filters

Filter TypeNameFieldDescription
Equalsprofileidprofileidreturn profiles with the unique id
Inprofileidsprofileidsreturn list of profiles with a matching profileid
Equalscurrency_codecurrency_codereturns all invoice profiles matching the currency code.
Equalsclientidcustomeridreturn profiles with the same customerid given
Inclientidscustomeridlist profiles with a matching customerid
Equalsinclude_unbilled_timeinclude_unbilled_timereturns invoice profiles that contained unbilled time.

Field Descriptions

Underlined Fields are Required on Creation

Computed Fields (read only)

FieldTypeDescription
idintthe unique id for the invoice profile
owneridintid of creator of invoice. 1 if business admin, other if created by e.g. a contractor
updateddatethe date the invoice profile was updated
discount_totalobjectsubfields: amount, code
amountstringthe amount of the discount
codestringthree-letter currency code for the discount
occurrences_to_dateintnumber of invoices that have been generated
amountobjectsubfields: amount, code
amountstringthe amount to be paid for invoice
codestringthree-letter currency code
profileidintsame as id

Writable

FieldTypeDescription
frequencystringthe frequency the invoice will be created. In the form of xy where x is an integer and y is either d,w,m,y. (example: Every two weeks would be 2w)
create_datedatethe create day of the invoice profile
send_emailbooleantrue email invoice on creation, false will leave as draft
streetstringstreet for address on invoice
bill_gatewaystringthe gateway that is used for payment
vat_numberstringvalue added tax number if provided
numberRecurringintThe number of invoices that will be generated, 0 for infinite
citystringvalue Added Tax number if provided
send_gmailbooleantrue to send invoice via ground mail
lnamestringthe last name of client on invoice
fnamestringthe first name of client on invoice
ext_archiveint(deprecated) 0 or 1 indicating archived or not
vis_stateint0 for active, 1 for deleted
provincestringProvince for address on invoice.
termsstringterms listed on invoice
descriptionstringthe description of the invocie
vat_namestringvalue added tax name if provided
street2stringsecond street for address on invoice
currency_codestringthree-letter currency code for invoice
disablebooleantrue will disable the auto-generation of invoices
addressstringthe address on the invoice
accounting_systemidstringunique id for the system
organizationstringname of the organization belonging to the client
customeridintthe unique id for the client of the invoice
due_offset_daysintnumber of days from creation that invoice is due
languagestring2 letter code representing the language
po_numberstringpost office box number for address on invoice
countrystringcountry for address on invoice
notesstringnotes listed on invoice
include_unbilled_timebooleantrue if unbilled time is included, false otherwise
payment_detailsstringdetails for payment for the invoice
codestringthree-letter currency code
discount_valuestringdecimal-string amount
auto_billbooleanwhether this invoice has a credit card saved

Get a Single Invoice Profile

curl -X GET \
-H "Authorization: <a token>" \
-H "Api-Version: alpha" \
-H "Content-Type: application/json" \
"https://api.freshbooks.com/accounting/account/<accountid>/invoice_profiles/invoice_profiles"

Response:


{
 "response": {
  "result": {
    "invoice_profile": {
      "code": "", 
      "create_date": "2018-01-01", 
      "send_email": true, 
      "street": "", 
      "ownerid": 1, 
      "bill_gateway": null, 
      "vat_number": "", 
      "numberRecurring": 0, 
      "id": 620, 
      "city": "", 
      "send_gmail": false, 
      "lname": "Smith", 
      "ext_archive": null, 
      "fname": "Rick", 
      "vis_state": 0, 
      "province": "", 
      "updated": "2017-08-22 16:00:41", 
      "terms": null, 
      "description": "", 
      "vat_name": "", 
      "street2": "", 
      "currency_code": "CAD", 
      "disable": false, 
      "discount_total": {
        "amount": "0.00", 
        "code": "CAD"
      }, 
      "address": "", 
      "customerid": 23482, 
      "accounting_systemid": "7RgXv", 
      "organization": "EoS", 
      "occurrences_to_date": 0, 
      "due_offset_days": 0, 
      "language": "en", 
      "po_number": null, 
      "country": "Canada", 
      "notes": "", 
      "include_unbilled_time": false, 
      "profileid": 620, 
      "amount": {
        "amount": "0.00", 
        "code": "CAD"
      }, 
      "frequency": "2w", 
      "payment_details": "", 
      "discount_value": "0", 
      "auto_bill": false
      }
    }
  }
}

Create an Invoice Profile

curl -X POST \
-H "Authorization: <a token>" \
-H "Api-Version: alpha" \
-H "Content-Type: application/json" \
-d '{
  "invoice_profile": {
    "customerid": 23482,
    "create_date": "2018-08-25",
    "frequency": "m",
    "numRecurring": 0
   }
 }' \
 "https://api.freshbooks.com/accounting/account/<accountid>/invoice_profiles/invoice_profiles"
 

Response:


 {
  "response": {
   "result": {
    "invoice_profile": {
     "code": "", 
     "create_date": "2018-01-01", 
     "send_email": true, 
     "street": "", 
     "ownerid": 1, 
     "bill_gateway": null, 
     "vat_number": "", 
     "numberRecurring": 0, 
     "id": 716, 
     "city": "", 
     "send_gmail": false, 
     "lname": "Smith", 
     "ext_archive": null, 
     "fname": "Rick", 
     "vis_state": 0, 
     "province": "", 
     "updated": "2017-08-25 12:51:19", 
     "terms": null, 
     "description": "", 
     "vat_name": "", 
     "street2": "", 
     "currency_code": "CAD", 
     "disable": false, 
     "discount_total": {
       "amount": "0.00", 
       "code": "CAD"
     }, 
     "address": "", 
     "customerid": 23482, 
     "accounting_systemid": "7RgXv", 
     "organization": "EoS", 
     "occurrences_to_date": 0, 
     "due_offset_days": 0, 
     "language": "en", 
     "po_number": null, 
     "country": "Canada", 
     "notes": "", 
     "include_unbilled_time": false, 
     "profileid": 716, 
     "amount": {
       "amount": "0.00", 
       "code": "CAD"
     }, 
     "frequency": "m", 
     "payment_details": "", 
     "discount_value": "0", 
     "auto_bill": false
    }
   }
  }
 }
 

Update an Invoice Profile

curl -X PUT \
-H "Authorization <a token>" \
-H "Api-Version: alpha" \
-H "Content-Type: application/json" \
-d '{
  "invoice_profile": {
    "frequency": "2w"
  }
}' \
"https://api.freshbooks.com/accounting/account/<accountid>/invoice_profiles/invoice_profiles/<accountid>"

Response:


{
 "response": {
  "result": {
    "invoice_profile": {
      "code": "", 
      "create_date": "2018-01-01", 
      "send_email": true, 
      "street": "", 
      "ownerid": 1, 
      "bill_gateway": null, 
      "vat_number": "", 
      "numberRecurring": 0, 
      "id": 620, 
      "city": "", 
      "send_gmail": false, 
      "lname": "Smith", 
      "ext_archive": null, 
      "fname": "Rick", 
      "vis_state": 0, 
      "province": "", 
      "updated": "2017-08-22 16:00:41", 
      "terms": null, 
      "description": "", 
      "vat_name": "", 
      "street2": "", 
      "currency_code": "CAD", 
      "disable": false, 
      "discount_total": {
        "amount": "0.00", 
        "code": "CAD"
      }, 
      "address": "", 
      "customerid": 23482, 
      "accounting_systemid": "7RgXv", 
      "organization": "EoS", 
      "occurrences_to_date": 0, 
      "due_offset_days": 0, 
      "language": "en", 
      "po_number": null, 
      "country": "Canada", 
      "notes": "", 
      "include_unbilled_time": false, 
      "profileid": 620, 
      "amount": {
        "amount": "0.00", 
        "code": "CAD"
      }, 
      "frequency": "2w", 
      "payment_details": "", 
      "discount_value": "0", 
      "auto_bill": false
      }
    }
  }
}

Delete an Invoice Profile

 curl -X PUT \
-H "Authorization: <a token>" \
-H "Api-Version: alpha" \
-H "Content-Type: application/json" \
-d '{
 "invoice_profile": {
    "vis_state": 1
   }
}' \
"https://api.freshbooks.com/accounting/account/<accountid>/invoice_profiles/invoice_profiles/<profileid>"

Response:


{
 "response": {
  "result": {
    "invoice_profile": {
      "code": "", 
      "create_date": "2018-01-01", 
      "send_email": true, 
      "street": "", 
      "ownerid": 1, 
      "bill_gateway": null, 
      "vat_number": "", 
      "numberRecurring": 0, 
      "id": 620, 
      "city": "", 
      "send_gmail": false, 
      "lname": "Smith", 
      "ext_archive": null, 
      "fname": "Rick", 
      "vis_state": 1, 
      "province": "", 
      "updated": "2017-08-22 16:00:41", 
      "terms": null, 
      "description": "", 
      "vat_name": "", 
      "street2": "", 
      "currency_code": "CAD", 
      "disable": false, 
      "discount_total": {
        "amount": "0.00", 
        "code": "CAD"
      }, 
      "address": "", 
      "customerid": 23482, 
      "accounting_systemid": "7RgXv", 
      "organization": "EoS", 
      "occurrences_to_date": 0, 
      "due_offset_days": 0, 
      "language": "en", 
      "po_number": null, 
      "country": "Canada", 
      "notes": "", 
      "include_unbilled_time": false, 
      "profileid": 620, 
      "amount": {
        "amount": "0.00", 
        "code": "CAD"
      }, 
      "frequency": "2w", 
      "payment_details": "", 
      "discount_value": "0", 
      "auto_bill": false
      }
    }
  }
}

Listing Invoice Profiles

curl -X GET \
-H "Authorization: <a token>" \
-H "Api-Version: alpha" \
-H "Content-Type: application/json" \
"https://api.freshbooks.com/accounting/account/<accountid>/invoice_profiles/invoice_profiles"

Response:


{
  "response": {
    "result": {
      "total": 3, 
      "per_page": 15, 
      "invoice_profiles": [
        {
           //same as single invoice profile
        }, 
        {
           //same as single invoice profile
        }, 
        {
           //same as single invoice_profile
        }
      ], 
      "page": 1, 
      "pages": 1
      }
    }
  }

Search example with clientid

https://api.freshbooks.com/accounting/account/<accountid>/invoice_profiles/invoice_profiles?search%5Bclientid%5D=23482

Search example with currency code

https://api.freshbooks.com/accounting/account/<accountid>/invoice_profiles/invoice_profiles?search%5Bcurrency_code%5D=USD

Including the next issue date

https://api.freshbooks.com/accounting/account/<accountid>/invoice_profiles/invoice_profiles?include%5B%5D=next_issue_date