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"
}