× Freshbooks App Logo
FreshBooks
Official App
Free - Google Play
Get 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 Name Description
allowed_gateways list of allowed gateways
audit_logs a summarization of the invoice for audit purposes
contacts contains contact objects populated with the client's data
late_fee late fee info
late-reminders late reminders
lines invoice lines
presentation data representing the stylings of the invoice. i.e. (Modern vs Classic)
system invoice-owner's system
tracking information regarding previous invoices
next_issue_date the date that the next invoice will be issued
project_format includes information about how the associated project is formated

Filters

Filter Type Name Field Description
Equals profileid profileid return profiles with the unique id
In profileids profileids return list of profiles with a matching profileid
Equals currency_code currency_code returns all invoice profiles matching the currency code.
Equals clientid customerid return profiles with the same customerid given
In clientids customerid list profiles with a matching customerid
Equals include_unbilled_time include_unbilled_time returns invoice profiles that contained unbilled time.

Field Descriptions

Underlined Fields are Required on Creation

Computed Fields (read only)

Field Type Description
id int the unique id for the invoice profile
ownerid int id of creator of invoice. 1 if business admin, other if created by e.g. a contractor
updated date the date the invoice profile was updated
discount_total object subfields: amount, code
amount string the amount of the discount
code string three-letter currency code for the discount
occurrences_to_date int number of invoices that have been generated
amount object subfields: amount, code
amount string the amount to be paid for invoice
code string three-letter currency code
profileid int same as id
auto_bill* boolean Whether this invoice has a credit card saved

*A bit of an explanation: This field will mark an invoice as automatically billing, but does not actually enable an auto_bill (which is currently unavailable in our API). Thus while you can write to this field, it will not do anything. Further, as we do not email clients upon creation of auto bill invoices (to avoid confusion in double payment), the end effect of writing to this field is to disable emails.

Writable

Field Type Description
frequency string the 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_date date the create day of the invoice profile
send_email boolean true email invoice on creation, false will leave as draft
street string street for address on invoice
bill_gateway string the gateway that is used for payment
vat_number string value added tax number if provided
numberRecurring int The number of invoices that will be generated, 0 for infinite
city string value Added Tax number if provided
send_gmail boolean true to send invoice via ground mail
lname string the last name of client on invoice
fname string the first name of client on invoice
ext_archive int (deprecated) 0 or 1 indicating archived or not
vis_state int 0 for active, 1 for deleted
province string Province for address on invoice.
terms string terms listed on invoice
description string the description of the invocie
vat_name string value added tax name if provided
street2 string second street for address on invoice
currency_code string three-letter currency code for invoice
disable boolean true will disable the auto-generation of invoices
address string the address on the invoice
accounting_systemid string unique id for the system
organization string name of the organization belonging to the client
customerid int the unique id for the client of the invoice
due_offset_days int number of days from creation that invoice is due
language string 2 letter code representing the language
po_number string post office box number for address on invoice
country string country for address on invoice
notes string notes listed on invoice
include_unbilled_time boolean true if unbilled time is included, false otherwise
payment_details string details for payment for the invoice
code string three-letter currency code
discount_value string decimal-string amount

 

Get a Single Invoice Profile

curl -X GET 
-H "Authorization: &lta token&gt" 
-H "Api-Version: alpha" 
-H "Content-Type: application/json" 
"https://api.freshbooks.com/accounting/account/&ltaccountid&gt/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: &lta token&gt" 
-H "Api-Version: alpha" 
-H "Content-Type: application/json" 
-d '{
  "invoice_profile": {
    "customerid": 23482,
    "create_date": "2018-08-25",
    "frequency": "m",
    "numberRecurring": 0,
    "lines": [
      {
        "name": "Test Item",
        "qty": "1",
        "unit_cost": {
          "amount": "27.00"
        }
      }
     ]
   }
 }' 
 "https://api.freshbooks.com/accounting/account/&ltaccountid&gt/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 &lta token&gt" 
-H "Api-Version: alpha" 
-H "Content-Type: application/json" 
-d '{
  "invoice_profile": {
    "frequency": "2w"
  }
}' 
"https://api.freshbooks.com/accounting/account/&ltaccountid&gt/invoice_profiles/invoice_profiles/&ltaccountid&gt"

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: &lta token&gt" 
-H "Api-Version: alpha" 
-H "Content-Type: application/json" 
-d '{
 "invoice_profile": {
    "vis_state": 1
   }
}' 
"https://api.freshbooks.com/accounting/account/&ltaccountid&gt/invoice_profiles/invoice_profiles/&ltprofileid&gt"

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: &lta token&gt" 
-H "Api-Version: alpha" 
-H "Content-Type: application/json" 
"https://api.freshbooks.com/accounting/account/&ltaccountid&gt/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/&ltaccountid&gt/invoice_profiles/invoice_profiles?search%5Bclientid%5D=23482

Search example with currency code

https://api.freshbooks.com/accounting/account/&ltaccountid&gt/invoice_profiles/invoice_profiles?search%5Bcurrency_code%5D=USD

Including the next issue date

https://api.freshbooks.com/accounting/account/&ltaccountid&gt/invoice_profiles/invoice_profiles?include%5B%5D=next_issue_date