Invoice PDF email attachments

An invoice PDF is sent as an email attachment when you send an invoice to a customer. The invoice PDF also appears when the customer clicks the invoice payment link to complete the invoice payment.

You can set an invoice PDF as your custom branded invoice PDF file. When you send your invoice or invoice payment links to a customer, they see your custom branded invoice PDF.

❗️
The attachment file type must be PDF
When you are adding an invoice PDF attachment, the attachment file type must be PDF.

Add a new invoice PDF

In your POST /v3/attachments/invoices/{invoiceId} request, set the required query parameter fields.

Field	Description
`name`	File name with extension. For example, to upload a PDF attachment titled `business_details`, set `name` as `business_details.pdf`.
`replaceInvoicePdf`	Set as `true` to add the new invoice PDF attachment as an invoice PDF. The default value is `false`. If the invoice currently has an invoice PDF, set `replaceInvoicePdf` as `true` to replace the existing invoice PDF with the new PDF attachment.

Field

Description

name

File name with extension. For example, to upload a PDF attachment titled business_details, set name as business_details.pdf.

replaceInvoicePdf

Set as true to add the new invoice PDF attachment as an invoice PDF. The default value is false.

If the invoice currently has an invoice PDF, set replaceInvoicePdf as true to replace the existing invoice PDF with the new PDF attachment.

Sample request

In this cURL example, a PDF file named business_details.pdf is uploaded as an invoice PDF. In the request, replaceInvoicePdf is set as true to state that the PDF attachment must be set as the invoice PDF. The file size limit is 6 MB.

curl --request POST \
--url '{baseUrl}/connect/v3/attachments/invoices/{invoiceId}?name=business_details.pdf&replaceInvoicePdf=true' \
--header 'devKey: {developer_key}' \
--header 'sessionId: {session_id}' \
--header 'accept: application/json' \
--header 'content-type: */*' \
--data-binary '@{filepath}'

Response

In the response, a BILL-generated attachment id is available. The value begins with att.

{
    "id": "{attachment_id}",
    "name": "business_details.pdf",
    "createdTime": "2025-12-25T00:17:03.000+00:00",
    "downloadLink": "https://api-stage.bill.com/AttachDownload?id={attachment_id}"
}

See POST /v3/attachments/invoices/{invoiceId} in the API reference for more information.

Get current invoice PDF

Get the BILL-generated ID of the current invoice PDF attachment with GET /v3/invoices/{invoiceId}. In the response, the invoicePdfId value represents the current invoice PDF attachment.

See GET /v3/invoices/{invoiceId} in the API reference for more information.

Ensure that the customer receives the correct email attachment

You can get the list of invoice attachments with GET /v3/attachments/invoices/{invoiceId}. All the attachments in the list (including the invoice PDF) are sent as email attachments when you send the invoice to the customer.

To ensure that the customer receives only the invoice PDF as an email attachment, delete any invoice attachments that the customer is not required to receive. Delete an attachment with DELETE /v3/attachments/{attachmentId}.

See DELETE /v3/attachments/{attachmentId} in the API reference for more information.