Development
  • Guides
  • API Reference
  • API Explorer
  • SDKs
  • Sample apps
  • System status
Support
  • Developer forums
  • Developer blog
  • YouTube
  • X
More
  • Square Home
  • Square Developer
  • App Marketplace
  • Partner with Square
  • Solutions Partner Program
  • Pricing
  • Sales

© 2026 Square, Inc.

  • Developer terms of service
  • Developer Integration and Marketing Agreement
  • Privacy policy
  • Partnerships
  • Sign In
  • Sign In

    Invoices

  • List invoices

  • Create invoice

  • Search invoices

  • Delete invoice

  • Get invoice

  • Update invoice

  • Create invoice attachment

  • Delete invoice attachment

  • Cancel invoice

  • Publish invoice

  • Webhooks

  • invoice.canceled

  • invoice.created

  • invoice.deleted

  • invoice.payment_made

  • invoice.published

  • invoice.refunded

  • invoice.scheduled_charge_failed

  • invoice.updated

<- Invoices API

Invoices API

All versions ->

Create invoice attachment

POST

 /v2/invoices/{invoice_id}/attachments

Uploads a file and attaches it to an invoice.

This endpoint accepts HTTP multipart/form-data file uploads with a JSON request part and a file part. The file part must be a readable stream that contains a file in a supported format: GIF, JPEG, PNG, TIFF, BMP, or PDF.

Invoices can have up to 10 attachments with a total file size of 25 MB. Attachments can be added only to invoices in the DRAFT, SCHEDULED, UNPAID, or PARTIALLY_PAID state.

NOTE: When testing in the Sandbox environment, the total file size is limited to 1 KB.

Permissions:INVOICES_WRITE, ORDERS_WRITE

Guide

Create invoice attachments

Try in API Explorer
Link to section

Path parameters

Example code

Link to section

invoice_id

string

Required

The ID of the invoice to attach the file to.

Link to section

Request body

Link to section

idempotency_key

string

A unique string that identifies the CreateInvoiceAttachment request. For more information, see Idempotency.

Max Length
128
Link to section

description

string

The description of the attachment to display on the invoice.

Max Length
128
Link to section

Response fields

Link to section

attachment

Metadata about the attachment that was added to the invoice.

Link to section

errors

Information about errors encountered during the request.

Link to section

Examples

All versions ->

POST /v2/invoices/{invoice_id}/attachments
curl https://connect.squareup.com/v2/invoices/invoice_id0/attachments \ -X POST \ -H 'Square-Version: 2026-11-18' \ -H 'Authorization: Bearer ACCESS_TOKEN' \ -H 'Accept: application/json' \ -F 'file=@/local/path/to/file.jpg' \ -F 'request={ "idempotency_key": "ae5e84f9-4742-4fc1-ba12-a3ce3748f1c3", "description": "Service contract" }'

Response JSON

{ "attachment": { "id": "inva:0-3bB9ZuDHiziThQhuC4fwWt", "filename": "file.jpg", "description": "Service contract", "filesize": 102705, "hash": "273ee02cb6f5f8a3a8ca23604930dd53", "mime_type": "image/jpeg", "uploaded_at": "2023-02-03T20:28:14Z" } }