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.

Access Requirements

Access	Requires Authorization
Scopes	`user:invoices:read` `user:invoices:write`

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	profileid	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	city for address on invoice
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/<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": 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/<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 &lta token&gt"
-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/<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": 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/<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: &lta token&gt"
-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[clientid]=23482

Search example with currency code

https://api.freshbooks.com/accounting/account/<accountid>/invoice_profiles/invoice_profiles?search[currency_code]=USD

Including the next issue date

https://api.freshbooks.com/accounting/account/<accountid>/invoice_profiles/invoice_profiles?include[]=next_issue_date