Invoice attachments

Overview

Many businesses, especially those in constructions and trade, need to include additional documents when sending invoices and quotes to their customers. These additional documents can be contracts, schedules, timesheets, project files, photos, diagrams, reports of work, and similar.

With Monite API, you can add attachments to invoices, quotes, and credit notes and control which attachments will be included in emails or just stored for reference.

Considerations

• You can attach files to the following types of documents in any status:
  • invoices
  • quotes
  • credit notes
• Maximum file size is 15 MB.
• There is no limit on the number of attachments, but the total email size is limited to 25 MB. This limit includes all attachments plus the email’s HTML content and the Monite-generated PDF version of the document.
• Monite does not limit the file types and MIME types that can be uploaded or attached to receivables. Partners can choose to restrict the allowed attachment file types on their side, if required.

How to attach files to invoices

Step 1. Upload files to Monite

Call POST /files with a multipart/form-data body containing the file and with the file_type parameter set to attachments:

1
  curl -X POST https://api.sandbox.monite.com/v1/files \
2
       -H "X-Monite-Version: 2024-05-25" \
3
       -H "X-Monite-Entity-Id: ENTITY_ID" \
4
       -H "Authorization: Bearer ACCESS_TOKEN" \
5
       -F file=@timesheet.pdf \
6
       -F file_type="attachments"

The response contains a unique ID assigned to this file. Note down this ID as you will need it later. The response also contains a public url link to download the uploaded file from Monite servers.

1
{
2
  "id": "8f5bd660-bac9-4ce0-bd0d-5d9016d711b3",
3
  "file_type": "attachments",
4
  "name": "timesheet.pdf",
5
  "size": 120101,
6
  "url": "https://bucketname.s3.amazonaws.com/path/to/timesheet.pdf",
7
  ...
8
}

Step 2. Add files to invoice attachments

When creating or updating invoices, use the attachments field to specify a list of file IDs to attach to the invoice. Each file in the attachments list also has the include_in_email attribute that controls whether this file will be sent as part of invoice emails and reminders.

The same file can be attached to different invoices.

1
{
2
  "type": "invoice",
3
  ...
4
  "attachments": [
5
    {
6
      "id": "8f5bd660-bac9-4ce0-bd0d-5d9016d711b3",
7
      "include_in_email": true
8
    },
9
    {
10
      "id": "4b6ff01b-f660-4195-bba5-07a283019db1",
11
      "include_in_email": false
12
    }
13
  ]
14
}

1
{
2
  "invoice": {
3
    "attachments": [
4
      {
5
        "id": "8f5bd660-bac9-4ce0-bd0d-5d9016d711b3",
6
        "include_in_email": true
7
      },
8
      {
9
        "id": "4b6ff01b-f660-4195-bba5-07a283019db1",
10
        "include_in_email": false
11
      }
12
    ]
13
  }
14
}

1
{
2
  "issued_invoice": {
3
    "attachments": [
4
      {
5
        "id": "8f5bd660-bac9-4ce0-bd0d-5d9016d711b3",
6
        "include_in_email": true
7
      },
8
      {
9
        "id": "4b6ff01b-f660-4195-bba5-07a283019db1",
10
        "include_in_email": false
11
      }
12
    ]
13
  }
14
}

In API responses, the attachments list is expanded to include full file details, including the file names, file sizes, and download URLs. Client applications can use this information, for example, to display previews of attachments.

1
{
2
  "type": "invoice",
3
  ...
4
  "attachments": [
5
    {
6
      "id": "8f5bd660-bac9-4ce0-bd0d-5d9016d711b3",
7
      "include_in_email": true,
8
      "mimetype": "application/pdf",
9
      "name": "timesheet.pdf",
10
      "size": 120101,
11
      "url": "https://bucketname.s3.amazonaws.com/path/to/timesheet.pdf"
12
    },
13
    ...
14
  ]
15
}

Documents without attachments have the attachments value of null.

Attachment inheritance

Invoices created from quotes, credit notes created from invoices, and cloned documents do not inherit attachments from the original document.

Recurring invoices inherit only attachments with include_in_email=true from the base invoice template.

Update or remove attachments

When updating the attachments list for an invoice, the new list fully replaces the previous list. In other words:

• To add new attachments, include both the old and new attachments in the attachments list.
• To remove some attachments, send the attachments list containing just the attachments you want to keep.
• To remove all attachments, send "attachments": null.

List available files for attaching

To get a list of all files that were uploaded for use as attachments, call GET /files with the query parameter file_type=attachments.

The response contains the file IDs, file names, and URLs that can be used to preview the files:

1
{
2
  "data": [
3
    {
4
      "id": "8f5bd660-bac9-4ce0-bd0d-5d9016d711b3",
5
      "file_type": "attachments",
6
      "name": "timesheet.pdf",
7
      "size": 120101,
8
      "url": "https://bucketname.s3.amazonaws.com/path/to/timesheet.pdf",
9
      ...
10
    },
11
    ...
12
  ]
13
}

Attachments and emails

Custom attachments that have include_in_email set to true are included in emails sent by POST /receivables/{receivable_id}/send.

Attachments are currently not included in invoice payment reminders and overdue reminders.

Exclude auto-generated PDF invoice from emails

By default, emails sent by Monite include the PDF invoice that was automatically generated by Monite. To exclude the auto-generated PDF invoice from emails, partners can set the partner-level setting mail.attach_documents_as_pdf to false:

1
  curl -X PATCH https://api.sandbox.monite.com/v1/settings \
2
       -H "X-Monite-Version: 2024-05-25" \
3
       -H "Authorization: Bearer YOUR_PARTNER_TOKEN" \
4
       -H 'Content-Type: application/json' \
5
       -d '{
6
         "mail": {
7
           "attach_documents_as_pdf": false
8
         }
9
       }'

Limitations

• E-invoices are currently sent without attachments.