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

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

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

Field Descriptions

FieldTypeDescription
idintthe unique id for the invoice presentation, generated on creation
date_formatstringstring format of: “mm/dd/yyyy”, “dd/mm/yyyy”, or “yyyy-mm-dd”
image_banner_srcstring“/uploads/images/<JWT_TOKEN_FROM_IMAGE_UPLOAD>”
image_logo_srcstring“/uploads/images/<JWT_TOKEN_FROM_IMAGE_UPLOAD>”
theme_layoutstring“simple, “modern”, or “classic”
theme_font_namestring“modern” or “classic”
theme_primary_colorstringeg. “#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

FieldTypeDescription
expenseidintIf the attachment if from an expense receipt upload, include the expense id can be included
jwtstringJWT token from the /attachments upload response.
media_typestringMedia 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"
}