Create or Delete Invoice Attachments

Applies to: Invoices API

Learn how to use the Invoices API to manage invoice attachments.

Use the CreateInvoiceAttachment endpoint in the Invoices API to attach a file to an invoice or the DeleteInvoiceAttachment endpoint to delete an attachment. Attachment metadata is stored in the attachments field of an invoice.

An invoice attachment is an uploaded file that's associated with a specific invoice. Invoices can have up to 10 attachments in GIF, JPEG, PNG, TIFF, BMP, and PDF formats. Attachments can provide supplemental information for an invoice or the associated order, such as service contracts, scanned documents, transaction history for monthly billing, and photographic records.

Invoice attachments can be accessed in the following ways:

• Invoice recipients can open attachments from an emailed invoice and the invoice payment page.
• Sellers can add, view, and manage attachments from the Square Dashboard, Square Point of Sale, and Square Invoices application.
• Developers can use the Invoices API to add or delete invoice attachments and access attachment metadata. The Invoices API cannot be used to download files.

To upload an invoice attachment, call CreateInvoiceAttachment and provide the following information:

• invoice_id with the ID of the target invoice. If needed, you can get the invoice ID by calling ListInvoices. The invoice must be in one of the following states:

  • DRAFT
  • SCHEDULED
  • UNPAID
  • PARTIALLY_PAID

  Attachments cannot be added while the invoice is in the PAYMENT_PENDING or PARTIALLY_REFUNDED state or after it reaches the PAID, REFUNDED, CANCELED, or FAILED terminal state.

• The file part with the local file path to upload as a readable stream. Only one file can be uploaded in a CreateInvoiceAttachment request. The following file types are supported:

  • image/gif
  • image/jpeg
  • image/png
  • image/tiff
  • image/bmp
  • application/pdf

  The maximum file size for a CreateInvoiceAttachment request is 25 MB. An invoice can have up to 10 attachments with a maximum total file size of 25 MB.

• The request part with an idempotency key used to ensure idempotency and an optional description. The file name and description are displayed on the invoice.

The following example request attaches a PDF file to an invoice:

If successful, Square returns a 201 Created response with the new InvoiceAttachment object, as shown in the following example:

{
  "attachment": {
    "id": "inva:0-ChBIMZJ99MugJFCUBjUVfdwY",
    "filename": "terms_and_agreements.pdf",
    "description": "Service contract",
    "filesize": 81839,
    "hash": "273ee02cb6f5f8a3a8ca23604930dd53",
    "mime_type": "application/pdf",
    "uploaded_at": "2023-03-03T00:07:52Z"
  }
}

Square populates the filename, filesize, and mime_type fields of the attachment using information obtained from the request. For the hash field, Square generates an MD5 hash from the file content.

After the attachment is created, Square does the following:

• Adds the attachment to the attachments field of the invoice. This field is present only if the invoice has attachments. A file can be uploaded only when attached to a specified invoice.

• Notifies the seller that the invoice was updated, if the Updated notification is enabled in the seller's notification settings.

• Notifies the customer that the invoice was updated, as determined by the delivery_method setting for the invoice:

  • EMAIL - Square sends an email to the customer.
  • SMS - Square sends a text message to the customer unless the customer has opted out of text message updates from Square invoices.
  • SHARE_MANUALLY - Square doesn't notify the customer.

  Opting out of EMAIL or SMS notifications isn't possible when creating an attachment with the Invoices API.

• Increments the invoice version.

• Invokes an invoice.updated webhook event.

After a file is attached to an invoice, the Invoices API can be used to retrieve attachment metadata, but it cannot be used to access uploaded files or track version history. Make sure to store a copy of the file if you might need to access it later.

Invoice attachments cannot be updated. Note the following:

• To upload a new version of a file or change the description, first delete the attachment and then create a new attachment.
• Square doesn't provide any versioning support for attachments. A new attachment ID is generated for each CreateInvoiceAttachment request.
• Square creates a separate attachment if you upload a file that has the same name as an existing attachment. Square doesn't replace same-named files or disambiguate file names.

To permanently delete an invoice attachment, call DeleteInvoiceAttachment and provide the following information:

• invoice_id with the ID of the target invoice. If needed, you can get the invoice ID by calling ListInvoices. The invoice must be in one of the following states:

  • DRAFT
  • SCHEDULED
  • UNPAID
  • PARTIALLY_PAID

  Attachments cannot be removed while the invoice is in the PAYMENT_PENDING or PARTIALLY_REFUNDED state or after it reaches the PAID, REFUNDED, CANCELED, or FAILED terminal state.

• attachment_id with the ID of the attachment to delete. If needed, you can retrieve attachment metadata to get the attachment ID.

The following example request deletes an attachment:

If successful, Square returns a 200 OK response with an empty object:

{}

After the attachment is deleted, Square does the following:

• Permanently deletes the file from the seller account.

• Removes the attachment from the attachments field of the invoice. This field is present only if the invoice has attachments.

• Notifies the seller, if the Updated notification is enabled in the seller's notification settings.

• Notifies the customer, as determined by the delivery_method setting for the invoice:

  • EMAIL - Square sends an email to the customer.
  • SMS - Square sends a text message to the customer unless the customer has opted out of text message updates from Square invoices.
  • SHARE_MANUALLY - Square doesn't notify the customer.

  Opting out of EMAIL or SMS notifications isn't possible when deleting an attachment with the Invoices API.

• Increments the invoice version.

• Invokes an invoice.updated webhook event.

To retrieve metadata for an invoice attachment, call GetInvoice, ListInvoices, or SearchInvoices. If an invoice has attachments, it includes an attachments field that contains up to 10 InvoiceAttachment objects.

For example, you can call GetInvoice to retrieve an invoice and get the metadata for all its attachments.

The following excerpt of an example response includes the attachments field with two attachments:

{
  "invoice": {
    "id": "inv:0-ChD_YNSHr4E6FJDariEoAe20lrz",
    "version": 2,
    "location_id": "S8GWD52VMQ64Y",
    "order_id": "IVbTFOMBAGigR3fQYXlREdN4OZY",
    ...
    "attachments": [
      {
        "id": "inva:0-ChBIMZJ99MugJFCUBjUVfdwY",
        "filename": "terms_and_agreements.pdf",
        "description": "Service contract",
        "filesize": 81839,
        "hash": "273ee02cb6f5f8a3a8ca23604930dd53",
        "mime_type": "application/pdf",
        "uploaded_at": "2023-03-03T00:07:52Z"
      },
      {
        "id": "inva:0-ChDorZooQrC5Tz8QIfGWCk2j",
        "filename": "damage.jpg",
        "description": "Repair site - floorboards",
        "filesize": 115175,
        "hash": "90c3c5d195df3a0e2492583829a6c89a",
        "mime_type": "image/jpeg",
        "uploaded_at": "2023-03-03T00:09:46Z"
      }
    ]
  }
}

Attachment metadata is included in all Invoices API responses and webhook notifications that return an invoice.

The hash field in the attachment metadata contains an MD5 hash of the file content. If needed, you can use this field to compare file content between a stored file or stored hash and a current attachment. For example, you can use md5sum to generate a hash for comparison (on macOS or Linux):

cat /path/to/file/terms_and_agreements.pdf | md5sum
273ee02cb6f5f8a3a8ca23604930dd53  -

Keep in mind that updating attachments isn't supported with the Invoices API, Square Dashboard, Square Point of Sale, or Square Invoices application. Instead, the attachment is deleted and then recreated, at which time Square assigns a new attachment ID.

• Invoices API
• API Reference: Invoices