× FreshBooks App Logo
FreshBooks
Official App
Free - Google Play
Get it
You're currently on our US site. Select your regional site here:

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

AccessRequires Authorization
Scopesuser:invoices:read
user:invoices:write

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
Inprofileidsprofileidreturn 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
auto_bill*booleanWhether 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

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
citystringcity for address on invoice
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

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