Invoice Presentation and Attachments
Invoice Presentation
Invoice Presentations are used to style an invoice including font, colors, and logos.
By default, when a new invoice is created, it automatically uses the presentation style of the most recently created invoice (including logos, colors, and fonts). If you wish to change the style of an invoice via the API, or if the user has not styled their invoices (such as in a brand new account), then you can pass a presentation
object as part of the invoice call. Subsequent invoices will use this style until an invoice is created with a new style. If you do not wish for an invoice to use any styles, you can include use_default_presentation: false
in the invoice call.
Access Requirements
Access | Requires Authorization |
Scopes | user:invoices:write user:uploads:read user:uploads:write |
Field Descriptions
Field | Type | Description |
---|---|---|
id | int | the unique id for the invoice presentation, generated on creation |
date_format | string | string format of: “mm/dd/yyyy”, “dd/mm/yyyy”, or “yyyy-mm-dd” |
image_banner_src | string | “/uploads/images/<JWT_TOKEN_FROM_IMAGE_UPLOAD>” |
image_logo_src | string | “/uploads/images/<JWT_TOKEN_FROM_IMAGE_UPLOAD>” |
theme_layout | string | “simple, “modern”, or “classic” |
theme_font_name | string | “modern” or “classic” |
theme_primary_color | string | eg. “#345beb” |
For simple
and classic
invoices, the image_logo_src
is used to display the logo, for modern
invoices, the image_banner_src
is used.
Invoice Images and Attachments
Invoice presentations can have a company logo or banner image. Invoices can also have images or pdfs attached to them. All images and attachments first need to be uploaded to the system via the /images
or /attachments
endpoints first (see side examples). The endpoints will then return a path to your file with a JWT. This path will can then be passed in the body of your invoice request for your file to be included.
To include an uploaded attachment on an invoice, the invoice request must include an attachments
object.
Field Descriptions
Field | Type | Description |
---|---|---|
expenseid | int | If the attachment if from an expense receipt upload, include the expense id can be included |
jwt | string | JWT token from the /attachments upload response. |
media_type | string | Media type from /attachments upload response. Eg. "image/jpeg" |
Create Invoice with Presentation
curl -L -X POST 'https://api.freshbooks.com/accounting/account/<accountId>/invoices/invoices' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer ' \
--data-raw '{
"invoice": {
... ,
"presentation": {
"date_format": "mm/dd/yyyy",
"image_logo_src": /uploads/images/eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJhY2NvdW50Ijo0MjM2NDEwLCJvcmlnaW5hbF9maWxlbmFtZSI6ImNyYXBwcy5wbmciLCJidWNrZXQiOiJ1cGxvYWRzIiwiZmlsZW5hbWUiOiJ1cGxvYWQtOWM4NGZjMjIxZmY2OGYxZDhmYzM3ZDhhMGU2NzdmY2M3YmQ3MWM3MyIsImxlbmd0aCI6MjIzNTA2LCJrZXkiOiInZG9jcy0nLTQyMzY0MTAvdXBsb2FkLTljODRmYzIyMWZmNjhmMWQ4ZmMzN2Q4YTBlNjc3ZmNjN2JkNzFjNzMifQ.JKJhOAD4xudhv8uPpyVw6yFhvJC5ypYzYGRWvq0UTDA,
"theme_layout": "simple",
"theme_font_name": "modern",
"theme_primary_color": "#345BEB"
}
}
}'
#Response:
{
"response": {
"result": {
"invoice": {
"id": 1627,
"invoice_number": "0000003",
"invoiceid": 1627,
... ,
"presentation": {
"date_format": "mm/dd/yyyy",
"id": 544566,
"image_logo_src": "/uploads/images/eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJhY2NvdW50Ijo0MjM2NDEwLCJvcmlnaW5hbF9maWxlbmFtZSI6InRvcm9udG8tc2t5bGluZS5qcGciLCJidWNrZXQiOiJ1cGxvYWRzIiwiZmlsZW5hbWUiOiJ1cGxvYWQtOTE5ODE2MGY5NGNhMjk3ZTE3NGE2MDJmNDA4OTlhM2M5Zjc2MDk5ZCIsImxlbmd0aCI6MzA3MDY4LCJrZXkiOiInZG9jcy0nLTQyMzY0MTAvdXBsb2FkLTkxOTgxNjBmOTRjYTI5N2UxNzRhNjAyZjQwODk5YTNjOWY3NjA5OWQifQ.yAfSd2cIAf2GONitgBmimMCHxvH9OYij7g0WMsiLsa",
"theme_layout": "simple",
"theme_font_name": "modern",
"theme_primary_color": "#345BEB"
}
}
}
}
}
Create Invoice with no Presentation
curl -L -X POST 'https://api.freshbooks.com/accounting/account/<accountId>/invoices/invoices' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer ' \
--data-raw '{
"invoice": {
... ,
"use_default_presentation": false
}
}'
#Response:
{
"response": {
"result": {
"invoice": {
"id": 1627,
"invoice_number": "0000003",
"invoiceid": 1627,
... ,
}
}
}
}
Create Invoice with Attachment
curl -L -X POST 'https://api.freshbooks.com/accounting/account/<accountId>/invoices/invoices' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer ' \
--data-raw '{
"invoice": {
... ,
"attachments": [
{
"expenseid": null,
"jwt": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJhY2NvdW50Ijo0MjM2NDEwLCJvcmlnaW5hbF9maWxlbmFtZSI6InRvcm9udG8tc2t5bGluZS5qcGciLCJidWNrZXQiOiJ1cGxvYWRzIiwiZmlsZW5hbWUiOiJ1cGxvYWQtOTE5ODE2MGY5NGNhMjk3ZTE3NGE2MDJmNDA4OTlhM2M5Zjc2MDk5ZCIsImxlbmd0aCI6MzA3MDY4LCJrZXkiOiInZG9jcy0nLTQyMzY0MTAvdXBsb2FkLTkxOTgxNjBmOTRjYTI5N2UxNzRhNjAyZjQwODk5YTNjOWY3NjA5OWQifQ.yAfSd2cIAf2GONitgBmimMCHxvH9OYij7g0WMsiLsaE",
"media_type": "application/pdf"
}
]
}
}'
#Response:
{
"response": {
"result": {
"invoice": {
"id": 1627,
"invoice_number": "0000003",
"invoiceid": 1627,
... ,
}
}
}
}
Upload Logo / Banner
Request: POST
curl --location -g --request POST 'https://api.freshbooks.com/uploads/account/<account_id>/images' \
--header 'Authorization: Bearer ' \
--form 'content=@"/path/to/file"'
Response:
{
"image": {
"filename": "upload-9198160f94ca297e174a602f40899a3c9f76099d",
"public_id": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJhY2NvdW50Ijo0MjM2NDEwLCJvcmlnaW5hbF9maWxlbmFtZSI6InRvcm9udG8tc2t5bGluZS5qcGciLCJidWNrZXQiOiJ1cGxvYWRzIiwiZmlsZW5hbWUiOiJ1cGxvYWQtOTE5ODE2MGY5NGNhMjk3ZTE3NGE2MDJmNDA4OTlhM2M5Zjc2MDk5ZCIsImxlbmd0aCI6MzA3MDY4LCJrZXkiOiInZG9jcy0nLTQyMzY0MTAvdXBsb2FkLTkxOTgxNjBmOTRjYTI5N2UxNzRhNjAyZjQwODk5YTNjOWY3NjA5OWQifQ.yAfSd2cIAf2GONitgBmimMCHxvH9OYij7g0WMsiLsaE",
"jwt": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJhY2NvdW50Ijo0MjM2NDEwLCJvcmlnaW5hbF9maWxlbmFtZSI6InRvcm9udG8tc2t5bGluZS5qcGciLCJidWNrZXQiOiJ1cGxvYWRzIiwiZmlsZW5hbWUiOiJ1cGxvYWQtOTE5ODE2MGY5NGNhMjk3ZTE3NGE2MDJmNDA4OTlhM2M5Zjc2MDk5ZCIsImxlbmd0aCI6MzA3MDY4LCJrZXkiOiInZG9jcy0nLTQyMzY0MTAvdXBsb2FkLTkxOTgxNjBmOTRjYTI5N2UxNzRhNjAyZjQwODk5YTNjOWY3NjA5OWQifQ.yAfSd2cIAf2GONitgBmimMCHxvH9OYij7g0WMsiLsaE",
"media_type": "image/jpeg",
"uuid": "47356675-5gh5-4a1e-9de6-761cg66fgf43"
},
"link": "https://my.freshbooks.com/service/uploads/images/eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJhY2NvdW50Ijo0MjM2NDEwLCJvcmlnaW5hbF9maWxlbmFtZSI6InRvcm9udG8tc2t5bGluZS5qcGciLCJidWNrZXQiOiJ1cGxvYWRzIiwiZmlsZW5hbWUiOiJ1cGxvYWQtOTE5ODE2MGY5NGNhMjk3ZTE3NGE2MDJmNDA4OTlhM2M5Zjc2MDk5ZCIsImxlbmd0aCI6MzA3MDY4LCJrZXkiOiInZG9jcy0nLTQyMzY0MTAvdXBsb2FkLTkxOTgxNjBmOTRjYTI5N2UxNzRhNjAyZjQwODk5YTNjOWY3NjA5OWQifQ.yAfSd2cIAf2GONitgBmimMCHxvH9OYij7g0WMsiLsaE"
}
Upload Invoice Attachment
Request: POST
curl --location -g --request POST 'https://api.freshbooks.com/uploads/account/<account_id>/attachments' \
--header 'Authorization: Bearer ' \
--form 'content=@"/path/to/file"'
Response:
{
"attachment": {
"filename": "upload-9198160f94ca297e174a602f40899a3c9f76099d",
"public_id": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJhY2NvdW50Ijo0MjM2NDEwLCJvcmlnaW5hbF9maWxlbmFtZSI6InRvcm9udG8tc2t5bGluZS5qcGciLCJidWNrZXQiOiJ1cGxvYWRzIiwiZmlsZW5hbWUiOiJ1cGxvYWQtOTE5ODE2MGY5NGNhMjk3ZTE3NGE2MDJmNDA4OTlhM2M5Zjc2MDk5ZCIsImxlbmd0aCI6MzA3MDY4LCJrZXkiOiInZG9jcy0nLTQyMzY0MTAvdXBsb2FkLTkxOTgxNjBmOTRjYTI5N2UxNzRhNjAyZjQwODk5YTNjOWY3NjA5OWQifQ.yAfSd2cIAf2GONitgBmimMCHxvH9OYij7g0WMsiLsaE",
"jwt": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJhY2NvdW50Ijo0MjM2NDEwLCJvcmlnaW5hbF9maWxlbmFtZSI6InRvcm9udG8tc2t5bGluZS5qcGciLCJidWNrZXQiOiJ1cGxvYWRzIiwiZmlsZW5hbWUiOiJ1cGxvYWQtOTE5ODE2MGY5NGNhMjk3ZTE3NGE2MDJmNDA4OTlhM2M5Zjc2MDk5ZCIsImxlbmd0aCI6MzA3MDY4LCJrZXkiOiInZG9jcy0nLTQyMzY0MTAvdXBsb2FkLTkxOTgxNjBmOTRjYTI5N2UxNzRhNjAyZjQwODk5YTNjOWY3NjA5OWQifQ.yAfSd2cIAf2GONitgBmimMCHxvH9OYij7g0WMsiLsaE",
"media_type": "image/png",
"uuid": "47356675-5gh5-4a1e-9de6-761cg66fgf43"
},
"link": "https://my.freshbooks.com/service/uploads/images/eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJhY2NvdW50Ijo0MjM2NDEwLCJvcmlnaW5hbF9maWxlbmFtZSI6InRvcm9udG8tc2t5bGluZS5qcGciLCJidWNrZXQiOiJ1cGxvYWRzIiwiZmlsZW5hbWUiOiJ1cGxvYWQtOTE5ODE2MGY5NGNhMjk3ZTE3NGE2MDJmNDA4OTlhM2M5Zjc2MDk5ZCIsImxlbmd0aCI6MzA3MDY4LCJrZXkiOiInZG9jcy0nLTQyMzY0MTAvdXBsb2FkLTkxOTgxNjBmOTRjYTI5N2UxNzRhNjAyZjQwODk5YTNjOWY3NjA5OWQifQ.yAfSd2cIAf2GONitgBmimMCHxvH9OYij7g0WMsiLsaE"
}