Applies to: Invoices API
Use the Invoices API
The Square Invoices
Developers can use the Invoices API to manage invoicing for orders created using the Orders API
The following requirements and limitations apply when using the Invoices API.
OAuth permissions - Applications that use OAuth
OAuth and the Invoices API require the following OAuth permissions:INVOICES_READ
to use the following endpoints:INVOICES_WRITE
andORDERS_WRITE
to use the following endpoints:CUSTOMERS_READ
andPAYMENTS_WRITE
to charge cards on file.
Your application uses these permissions to manage invoices on behalf of a seller. Depending on its functionality, your application might also require other Square permissions.
The location must be active - When creating an invoice, the location
location of the associated order must have anACTIVE
status. If you specify the optionallocation_id
field in aCreateInvoice
request, the value must match thelocation_id
of the order.The invoice recipient must be in the Customer Directory - The customer who receives the invoice must have a customer profile in the seller's Customer Directory. This customer is associated with the invoice using the
primary_recipient.customer_id
field. For more information about creating and managing customer profiles, see Manage Customer ProfilesManage Customer Profiles .The seller account must be able to accept payments - The seller account must be set up to accept payments before Square can accept payments on any invoices. The Invoices API doesn't allow you to publish any invoices configured for automatic payments unless the seller is enabled to accept payments. For invoices scheduled for a future date, the Invoices API also cancels the order and deletes the invoice when the invoice is scheduled to be sent. This requirement also applies to testing with your own Square account in the production environment.
App Marketplace requirements - If you intend to list your application on the Square App Marketplace
Square App Marketplace , see Invoices API RequirementsInvoices API Requirements .Error handling for Invoices Plus features - Your application must be able to handle errors returned when attempting to create or update an invoice with custom fields or installment payments. These premium features are available only with an Invoices Plus subscription
Invoices Plus subscription .
Limitations with the Orders API integration - Invoices are associated with an order through the
order_id
field of the invoice. You should be aware of the following considerations related to Orders API integration:When an invoice is canceled or deleted, Square cancels the associated order by setting the order status to
CANCELED
.Orders that are associated with an invoice cannot be set to the
CANCELED
orCOMPLETED
state using the Orders API.Payment for the order must be made on the invoice. You cannot use Square APIs such as PayOrder
PayOrder or CreatePaymentCreatePayment to process a payment for an order that is associated with an invoice. After the invoice is paid in full, Square sets thestate
field of the order toCOMPLETED
.After an order is associated with an invoice, you cannot update order fields that affect the order amount (or their child fields), such as:
line_items
taxes
discounts
To update these immutable fields, you must cancel the invoice, which also cancels the order. You can then create a new order and a new invoice. However, you can update order fields that don't affect the cart.
Invoices don't contain information about the order. For itemization and other order information, call
RetrieveOrder
using theorder_id
from the invoice.Only orders with locations in Canada or the United States can include a service charge
service charge . However, apportioned service charges aren't supported in any region.
For more information about order-related requirements and limitations, see Create and Publish Invoices
Create and Publish Invoices .
Limitations with the Customers API integration - Invoices are associated with a customer profile through the
primary_recipient.customer_id
field, which represents the invoice recipient. This might not be the same customer associated with the underlying order or with any invoice payments.You should be aware of the following considerations related to Customers API integration:
The
InvoiceRecipient
object represents a snapshot of customer data retrieved from the associated customer profile. Square doesn't update the contact information of the recipient in response to changes in the associated customer profile. To update the customer profile information for a draft invoice, update the profileupdate the profile using the Customers API and then update the invoiceupdate the invoice by first clearing theprimary_recipient
field and then adding it again.Invoice recipient fields cannot be updated after the invoice is published. However, Square does update the
customer_id
field if the associated customer profile is merged.Invoices aren't automatically updated or canceled if the customer profile assigned as the invoice recipient is deleted from the Customer Directory. If the invoice has remaining scheduled payments, Square continues to send the invoice. Any remaining automatic payments fail, but the customer can still enter the payment information on the invoice payment page.
Consider canceling these invoices
canceling these invoices if there isn't a valid reason to keep them. You can subscribe to the customer.deletedcustomer.deleted webhook event to be notified when customers are deleted.
For more information about customer-related requirements and limitations, see Create and Publish Invoices
Create and Publish Invoices .
- Payments and application fees - You should be aware of the following considerations related to payments and application fees:
Developers cannot collect application fees for invoices.
Square APIs cannot be used to pay an invoice. Square manages invoice payment flows. For more information, see Pay an invoice.
Pay an invoice. Although Square APIs cannot be used to pay an invoice, you can call ListPayments
ListPayments or GetPaymentGetPayment using the tender ID from the order to retrieve the correspondingPayment
object after a payment is made. For steps, see Retrieve an invoice payment.Retrieve an invoice payment. Payments also appear on the Transactions page of the Square Dashboard.Installment payments are supported only with an Invoices Plus subscription
Invoices Plus subscription .The
BANK_ON_FILE
automatic payment method cannot be set using the Invoices API. This payment method applies only to invoices that sellers create in Square products.The
BUY_NOW_PAY_LATER
accepted payment method can only be set for invoices that have a single payment request of theBALANCE
type. For additional requirements, see Buy Now Pay Later payments with AfterpayBuy Now Pay Later payments with Afterpay .
Unsupported features - The Invoices API doesn't support some of the features available in the Square Dashboard, Square Point of Sale, and Square Invoices application. For example, you cannot use the Invoices API to create or configure the following features:
Color and logo customization for your email invoices and customer payment page.
Recurring invoices. However, you can use the Subscriptions API
Subscriptions API to create and manage recurring subscriptions.Invoice templates.
Estimates.
Bulk actions.
Automatic payments from a bank account on file.
Attaching a file to an invoice. The Invoices API preserves any existing attachments on an invoice but the API doesn't support accessing and modifying invoice attachments.
Adding or viewing a shipping address. You cannot add a shipping address to an invoice that you create with the Invoices API. In addition, the shipping address isn't included in invoices that you retrieve with the Invoices API.
SMS
(text message) delivery method. Note that when an invoice is configured to use theSMS
delivery method, Square sends invoices and receipts, but not reminders.Although you cannot use the Invoices API to specify
SMS
for the invoicedelivery_method
field, you can use the API to update other invoice fields or changedelivery_method
toEMAIL
orSHARE_MANUALLY
.You should be aware of the following considerations when an invoice is configured for SMS delivery, but the customer opted out of text message updates from Square invoices:
- Square cannot send a text message to notify the customer about a change after the invoice is updated.
- Calling the
PublishInvoice
endpoint for the invoice returns aBad Request
error.
Sandbox attachment file size limit - In the Square Sandbox
Square SandboxAn isolated server environment used for testing. API calls in the Sandbox use the "connect.squareupsandbox.com" domain and require an access token that's valid for Sandbox. , invoices have a total file size limit of 1 KB for all attachments. In production, the total file size limit for all attachments is 25 MB.
Simplify invoice management and reduce your application development costs by integrating the Invoices API into your application flow:
You don't need to collect or process payments. Square collects payments from customers by generating a Square-hosted online payment page or by processing automatic payments. For more information, see Pay an invoice
Pay an invoice .You don't need to send invoices, reminders, or receipts. Square follows up with customers based on the invoice settings you specify, even when invoices are split into multiple payment requests. By default, Square also sends notifications to sellers. For more information, see Configuring how Square processes an invoice
Configuring how Square processes an invoice .You don't need to manage order status. Using the order ID you provide when creating an invoice, Square updates the order when the invoice is paid or canceled. Square also gets customer contact information based on the customer ID you provide.
All invoices can be managed using the Invoices API or Square products (the Square Dashboard, Square Point of Sale, and Square Invoices application). However, note the following considerations:
- Invoices created with the Invoices API must be associated with an order that was created with the Orders API. Orders created from Square products cannot be associated with an invoice because they don't include an order ID, which is required by the
CreateInvoice
endpoint. - The Invoices API doesn't support all invoice features that are available from Square products. For example, you cannot set an
SMS
delivery method orBANK_ON_FILE
automatic payment method.
For additional considerations, see Requirements and limitations
The following high-level steps represent a typical workflow for using Square APIs to create an invoice:
Create an order by calling CreateOrder
CreateOrder in the Orders API. Only orders created with the Orders API can be used to create an invoice with the Invoices API.Get the customer ID of the invoice recipient. You can use the
customer_id
from the order or call SearchCustomersSearchCustomers in the Customers API to search for a customer by phone number, email address, or other supported attribute.Create a draft invoice by calling
CreateInvoice
in the Invoices API. The invoice must contain one or more payment requests that define the payment schedule. For automatic card-on-file payments, provide acard_id
retrieved using ListCardsListCards in the Cards API.Publish the invoice by calling
PublishInvoice
in the Invoices API.After an invoice is published and the
scheduled_at
date (if specified) is reached, Square does the following:Generates the invoice payment page where customers can make a payment.
Adds the public_url
public_urlA temporary link to the Square-hosted payment page where the customer can pay the invoice. If the link expires, customers can provide the email address or phone number associated with the invoice and request a new link directly from the expired payment page. field with the payment page URL to the invoice.Adds the
next_payment_amount_money
field with the next payment amount due to the invoice, unless an automatic payment for the balance is completed immediately.Processes the invoice based on the invoice settings and handles the remaining workflow.
For example, Square can email the invoice, charge a card on file, or let you or the seller send the payment page URL to the customer. Square collects all invoice payments, either directly from customers (from the online payment page) or through automatic payments. Square also updates the invoice payment status and sends reminders and receipts as scheduled.
For more information, see Create and Publish Invoices
Create and Publish Invoices .
Because Square APIs cannot be used to pay invoices or manage payment status, no action is required from you after the invoice is published unless you need to add or remove attachments
Note
If sellers accept payment directly from customers, they can record the payment in the Square Dashboard, Square Point of Sale, or Square Invoices application.
The Invoices API supports the following operations:
- Create and publish an invoice
Create and publish an invoice - Retrieve, list, or search invoices
Retrieve, list, or search invoices - Create or delete invoice attachments
Create or delete invoice attachments - Update an invoice
Update an invoice - Cancel or delete an invoice
Cancel or delete an invoice
Invoice payments are managed by Square. You cannot use Square APIs to pay invoices or associated orders directly. For more information, see Pay or Refund Invoices
You can subscribe to receive webhook notifications for invoice events
The following diagram shows the order of Invoices API requests that you use to manage an invoice and the webhook events
After the invoice is published and the scheduled_at
date (if specified) is reached, Square processes the invoice, generates the invoice payment page, adds the public_url
Note
The diagram doesn't include calls to Square APIs used to obtain required information (such as order_id
and customer_id
) or to the GetInvoice
, ListInvoices
, or SearchInvoices
endpoints used to access invoices.
The Invoice
object is the core component of the Invoices API. Consider the following draft invoice that requests a single payment of $12 by the due date:
{ "invoice": { "id": "inv:0-ChAk0kZZW5IUxO0bgfIux95oEI4I", "version": 1, "location_id": "M8AKAD8160XGR", "order_id": "4AGVyEPgvg3RYVZFYjol6QN7Bg4F", "payment_requests": [ { "uid": "1c6e2c0a-0124-40a8-a90f-51957be40f64", "request_type": "BALANCE", "due_date": "2024-01-13", "tipping_enabled": false, "computed_amount_money": { "amount": 6213, "currency": "USD" }, "total_completed_amount_money": { "amount": 0, "currency": "USD" }, "automatic_payment_source": "NONE" } ], "primary_recipient": { "customer_id": "0K8P8KCSV9NXQV2V5129RASF4W", "given_name": "Sara", "family_name": "Vera", "email_address": "s.vera@example.com" }, "invoice_number": "2408_0920", "title": "Downtown Print Shop", "description": "Canvas photo prints", "status": "DRAFT", "timezone": "America/Los_Angeles", "created_at": "2023-12-14T21:22:16Z", "updated_at": "2023-12-14T21:24:10Z", "accepted_payment_methods": { "card": true, "square_gift_card": true, "bank_account": false, "buy_now_pay_later": true, "cash_app_pay": true }, "custom_fields": [ { "label": "Service Agreement", "value": "The following terms and conditions apply to orders ...", "placement": "ABOVE_LINE_ITEMS" }, { "label": "Refund Policy", "value": "Refunds will be made on the original payment method ...", "placement": "ABOVE_LINE_ITEMS" } ], "delivery_method": "EMAIL", "sale_or_service_date": "2023-12-11", "store_payment_method_enabled": true, "attachments": [ { "id": "inva:0-ChDp54tYJAPaJtfwCyzkAEPO", "filename": "terms_and_agreements.pdf", "description": "Service contract", "filesize": 81839, "hash": "2ec7f007ad6d470668a5855aefcb377f", "mime_type": "application/pdf", "uploaded_at": "2023-12-14T21:24:10Z" } ] } }
The following table describes key invoice settings. For information about all available invoices settings, see Invoice
Field | Description |
---|---|
| The ID of the order that was created using the Orders API and associated with the invoice. You can associate one invoice with each order. The total To view itemization and other order information associated with the invoice, call RetrieveOrder |
| One or more payment requests that define the payment schedule for the invoice. The preceding example invoice contains one payment request for the full order amount due by the specified date. For more information, see Configuring payment requests. After an invoice is published, Square adds the following fields to each payment request in the invoice:
Square collects all invoice payments from customers by generating a Square-hosted payment page or by processing automatic payments. To get information about a payment that was made, use the payment ID from the associated tender on the underlying order to call |
delivery_method | The method Square uses to send invoices, reminders, or receipts to the customer. If set to SHARE_MANUALLY , Square doesn't send the invoice or receipt. For more information, see Automatic communication from Square to customers |
scheduled_at | The date to process the invoice. If not specified, Square processes the invoice immediately after it is published. |
| The customer responsible for the invoice. Square retrieves contact and billing information based on the provided The |
status | The invoice statusDRAFT . A DRAFT invoice must be published for the customer to receive the invoice (either immediately or at the scheduled date). |
invoice_number | A user-friendly string that displays on the invoice. You might use the invoice number for client-side operations. If not specified, Square assigns a value. Don't confuse this field with the Square-assigned invoice id used for requests to the Invoices API. |
version | The invoice version. When an invoice is created, the version is set to 0. Square increments this value each time the invoice changes. You must provide the current version of the invoice for PublishInvoice , UpdateInvoice , and CancelInvoice requests. You cannot perform actions on previous versions of the invoice. |
accepted_payment_methods | The payment methods that customers can use to pay the invoice on the invoice payment page. This setting is independent of any automatic payment requests for the invoice. It is also independent of the default Payment method setting that applies to invoices created in the Square Dashboard. |
custom_fields | Up to two customer-facing seller-defined custom fields |
| A temporary link to the Square-hosted payment page where the customer can pay the invoice. If the link expires, customers can provide the email address or phone number associated with the invoice and request a new link directly from the expired payment page. This field is added after the invoice is published and reaches the scheduled date (if one is defined). |
attachments | Metadata for any image or PDF attachments |
title | The invoice title. If not specified, the business namedescription to display on the invoice. |
sale_or_service_date | The date of the sale or the date of the service. This display field appears on the invoice but doesn't drive any business logic. |
store_payment_method_enabled | Indicates whether to allow customers to save credit card, debit card, or bank transfer payment information when paying an invoice. The default value is false . When set to true , Square displays a Save my card on file or Save my bank on file checkbox on the invoice payment page. If the checkbox is selected, Square creates a card on file or a bank account on file for the customer using the information provided in the payment form. Stored payment information can be used for future automatic payments. Allowing customers to save gift cards on file for invoice payments isn't supported. |
subscription_id | The ID of the subscription |
creator_team_member_id | The ID of the team member |
For more information, including additional requirements, see Create and Publish Invoices
During the lifecycle of an invoice, Square sends automated communications to customers and sellers:
- Automatic communication from Square to customers
Automatic communication from Square to customers - Automatic communication from Square to sellers
Automatic communication from Square to sellers
The following table lists the events and conditions that determine when and how Square sends automated communications to customers. One important factor is the delivery_method
of the invoice:
For
EMAIL
, Square sends emails to customers using the email address in theprimary_recipient
field of the invoice.For
SMS
, Square sends text messages to customers using the phone number in theprimary_recipient
field of the invoice.For
SHARE_MANUALLY
, Square doesn't send invoices or receipts to customers. It is the responsibility of the developer or seller to communicate with the customer regarding invoices and receipts. However, Square does send scheduled reminders to customers using the email address in theprimary_recipient
field of the invoice.
Event | Communication |
---|---|
Invoice published | Square sends an invoice after a successful PublishInvoice
Square also resends the invoice after |
Scheduled reminder date reached | On the scheduled date, Square sends the reminder at 11:00 AM in the invoice's time zone. Note the following considerations:
|
Payment made | Square sends the receipt after one of the following payment events:
If These are the only supported methods of payment. Square APIs cannot be used to pay invoices or set invoice status. For more information, see Pay an invoice |
Automatic payment unsuccessful | Square sends the invoice by email and changes the automatic_payment_source field of the payment request to NONE . |
Invoice updated | Square notifies the customer that the invoice is updated after a successful UpdateInvoice
|
Invoice canceled | Square notifies the customer that the invoice is canceled after a successful CancelInvoice
|
Note
In the preceding table, communications sent in response to Square API requests also apply to corresponding actions that sellers make from the Square Dashboard, Square Point of Sale, or Square Invoices application.
Except for payments that are remitted directly to sellers, Square manages all payment flows and updates the status
, total_completed_amount_money
, and next_payment_amount_money
fields of the invoice as needed. Square APIs cannot be used to pay an invoice
Square notifies sellers about the following invoice-related events using email, unless noted otherwise:
- A customer views the Square-hosted invoice payment page. This push notification is sent only to the Square Invoices mobile application.
- An invoice or reminder is sent to the customer.
- An invoice is updated or canceled.
- A payment is made on the invoice payment page, or an automatic payment is completed.
These events include all invoice-related communications sent to customers. Sellers can manage their notification settings in the Square Dashboard. For more information, see Edit Your Notification Settings in Manage Your Square Invoices Online
Square also emails sellers after the following events:
- Square encounters problems when attempting to communicate with a customer using the email address or phone number recorded in the
primary_recipient
field of the invoice. - The invoice is canceled due to suspicious activity.
- A scheduled automatic invoice payment fails.
Sellers cannot unsubscribe from receiving these emails.