CUSTOMERS_READ and PAYMENTS_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 of the associated order must have an ACTIVE status. If you specify the optional location_id field in a CreateInvoice request, the value must match the location_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 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.
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.
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 or COMPLETED state using the Orders API.
Payment for the order must be made on the invoice. You cannot use Square APIs such as PayOrder or CreatePayment to process a payment for an order that is associated with an invoice. After the invoice is paid in full, Square sets the state field of the order to COMPLETED.
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 created using the Square Dashboard, Square Point of Sale, or Square Invoices application might not include the order_id field. Invoices that allow ACH bank transfer, Buy Now Pay Later, or Cash App Pay as an accepted payment method always include an order_id. For invoices that don't allow one of these payment methods, the order_id is added only after a payment has been made on the invoice.
Invoices created using the Invoices API require the order ID and therefore always include the order ID.
Invoices don't contain information about the order. For itemization and other order information, call RetrieveOrder using the order_id from the invoice.
Only orders with locations in Canada or the United States can include a service charge. However, apportioned service charges aren't supported in any region.
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 profile using the Customers API and then update the invoice by first clearing the primary_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 if there isn't a valid reason to keep them. You can subscribe to the customer.deleted webhook event to be notified when customers are deleted.
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.
Although Square APIs cannot be used to pay an invoice, you can call ListPayments or GetPayment using the tender ID from the order to retrieve the corresponding Payment object after a payment is made. For steps, see Retrieve an invoice payment. Payments also appear on the Transactions page of the Square Dashboard.
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 the BALANCE type. For additional requirements, see Buy 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 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 the SMS delivery method, Square sends invoices and receipts, but not reminders.
Although you cannot use the Invoices API to specify SMS for the invoice delivery_method field, you can use the API to update other invoice fields or change delivery_method to EMAIL or SHARE_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 a Bad Request error.
Link to section
Benefits of using the Invoices API
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.
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.
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.
Invoices created from Square products don't include an order_id field unless a payment has been made on the invoice.
The Invoices API doesn't support all invoice features that are available from Square products. For example, you cannot set an SMS delivery method or BANK_ON_FILE automatic payment method.
The following high-level steps represent a typical workflow for using Square APIs to create an invoice:
Create an order by calling 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 SearchCustomers 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 a card_id retrieved using ListCards 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 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.
If sellers accept payment directly from customers, they can record the payment in the Square Dashboard, Square Point of Sale, or Square Invoices application.
Link to section
Supported operations
The Invoices API supports the following operations:
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.
Link to section
Common Invoices API workflow
The following diagram shows the order of Invoices API requests that you use to manage an invoice and the webhook events invoked by each request:
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 field to the invoice, and manages payments and status. For more information, see Configuring how Square processes an invoice.
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.
Link to section
Invoice object
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:
The following table describes key invoice settings. For information about all available invoices settings, see Invoice.
Field
Description
order_id
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 computed_amount_money amounts of all invoice payment requests equal the total_money of the order.
To view itemization and other order information associated with the invoice, call RetrieveOrder using the order ID. For more information about orders integration, see Requirements and limitations.
payment_requests
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:
computed_amount_money with the amount due for the payment request.
total_completed_amount_money with the amount the customer has paid for the payment request.
Square collects all invoice payments from customers by generating a Square-hosted online 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 GetPayment. For more information, see Retrieve an invoice payment.
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.
primary_recipient
The customer responsible for the invoice. Square retrieves contact and billing information based on the provided customer_id. For more information about customers integration, see Requirements and limitations.
The customer_id of the invoice recipient might not be the same as the customer_id on the underlying order or any invoice payments.
status
The invoice status, which is managed by Square. When an invoice is created, the status is set to DRAFT. 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. Custom fields require an Invoices Plus subscription.
public_url
The URL of the invoice payment page. This field is added after the invoice is published and the scheduled_at date (if specified) is reached.
attachments
Metadata for any image or PDF attachments on the invoice. An invoice can have up to 10 attachments.
title
The invoice title. If not specified, the business name is used as the title. You can also provide an optional description 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.
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 the primary_recipient field of the invoice.
For SMS, Square sends text messages to customers using the phone number in the primary_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 the primary_recipient field of the invoice.
Event
Communication
Invoice published
Square sends an invoice after a successful PublishInvoice request. Invoices are sent on the scheduled_at date if one is specified; otherwise, they're sent immediately after the invoice is published.
For EMAIL, Square sends a copy of the invoice.
For SMS, Square sends a link to the invoice payment page.
For SHARE_MANUALLY, Square doesn't send invoices or receipts to the customer.
Square also resends the invoice after PublishInvoice is called for an invoice that is already published.
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:
For SMS, Square doesn't send reminders.
For SHARE_MANUALLY, Square emails scheduled reminders. The SHARE_MANUALLY delivery method doesn't apply to reminders.
An invoice can have multiple reminders scheduled for both before and after the payment due_date. If the payment is made before the scheduled reminder date, Square doesn't send the reminder.
Payment made
Square sends the receipt after one of the following payment events:
A customer makes a payment on the invoice payment page.
An automatic payment is completed. For bank transfer payments (which cannot be configured through the API), Square also notifies the customer when a payment is initiated and when a payment fails after it is initiated.
A seller records a payment in the Square Dashboard, Square Point of Sale, or Square Invoices application and selects the Send receipt checkbox.
If delivery method is set to SHARE_MANUALLY, Square doesn't automatically send invoices or receipts to the customer.
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 request.
For EMAIL, Square sends the updated invoice.
For SMS, Square notifies the customer that the invoice is updated and includes a link to the invoice payment page.
For SHARE_MANUALLY, Square doesn't notify the customer.
Invoice canceled
Square notifies the customer that the invoice is canceled after a successful CancelInvoice request.
For EMAIL, Square sends an invoice marked as canceled.
For SMS, Square notifies the customer that the invoice is canceled and includes a link to the invoice payment page, which is marked as canceled.
For SHARE_MANUALLY, Square doesn't notify the customer.|
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 or the associated order.
Link to section
Automatic communication from Square to sellers
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.
Link to section
Premium features available with Invoices Plus
Square Invoices Plus is a monthly subscription plan that enables Square sellers to use premium invoice features. The following Invoices Plus features are supported by the Invoices API:
Custom fields
Installment payments (used for milestone-based payment schedules)
Note
All other invoice features currently supported by the Invoices API are available without a subscription. However, the Invoices API doesn't support all Square Invoices features.
When using premium features, you should be aware of the following considerations:
To create invoices with premium features, the seller for whom you create the invoice must have an active (or trial) Invoices Plus subscription. Support for premium features spans the lifetime of the invoice. Therefore, you can add premium features to invoices that were created while the subscription is active, even after the subscription expires.
Square APIs cannot be used to check for subscription status or whether an invoice supports premium features before sending the request.
Instead, you must implement error handling logic for CreateInvoice or UpdateInvoice requests to catch the error returned if the invoice contains an unsupported feature. Then, you must remove any premium features from the invoice and retry the request. Specifically:
custom_fields must be empty or omitted.
payment_requests cannot contain a payment request of the INSTALLMENT type. The Invoices API returns 403 MERCHANT_SUBSCRIPTION_NOT_FOUND for Square version 2021-08-18 or later and 400 BAD_REQUEST for earlier Square versions. For more information, see Migration notes.
Regardless of the subscription status, the Invoices API returns the complete invoice in applicable responses and webhook notifications, including fields related to premium features.
You can use the Invoices API to add up to two custom fields to an invoice, each of which can be placed above or below the line items on the invoice. This enables sellers to customize their invoices by adding information such as their terms of service or refund policy. Custom fields are visible to sellers and buyers on the Square-hosted invoice payment page and in emailed or PDF copies of invoices. They also display in the details pane of the invoice in the Square Dashboard.
For example, this invoice includes a Special Offer custom field above the invoice line items and an Arrival instructions field below the invoice line items:
The following CreateInvoice request creates an invoice similar to the preceding example:
Create invoice
The following considerations apply to custom fields:
If two custom fields use the same placement above or below line items, the custom fields are rendered in the order that they're specified.
In the text field, you can use \n to render a new line. No other formatting characters are supported.
You cannot use the Invoices API to store custom fields for an account. If you want to enable sellers to reuse custom fields for their invoices, you must define your own storage mechanism.
The Invoices API doesn't support sparse updates for custom fields. To update a custom field, you must provide the complete custom_fields list in the update request.
Installment payments are used to configure a payment schedule for up to 12 installment payments, either with or without an initial deposit. Configuring an invoice for multiple payments is useful for scenarios such as billing customers based on specific milestones or phases of the job. For information about creating installment payment requests, see Configuring payment requests.
For sellers who accept Afterpay (or Clearpay) payments, you can create invoices that allow customers to make Buy Now Pay Later payments. For more information, see Buy Now Pay Later payments with Afterpay.
To test premium features and error handling in the Square Sandbox, you can subscribe to Invoices Plus in the Sandbox Square Dashboard.
The following procedure describes how you can subscribe your default test account to Invoices Plus using a test credit card that is never charged. You must repeat these steps for each test account that you want to subscribe to Invoices Plus.
On the Sandbox test accounts page, choose Square Dashboard next to Default Test Account. This opens the Sandbox Square Dashboard associated with the default test account.
To ensure that the subscription doesn't expire after 30 days, provide test credit card information:
Open the Pricing & Subscriptions page for the account. From the main menu, choose Account & Settings, expand Business information, and then choose Pricing & Subscriptions.
For the Invoices Plus subscription, choose Subscribe.
Enter the following credit card information, and then choose Subscribe:
For the name on the card, enter any name.
For the card number, enter 4111 1111 1111 1111.
For the CVV, enter 111.
For the expiration date, enter 12/40.
For the postal code, enter 22222 or a similar value for your locale.
If you already have a test credit card on file for the account, you can just choose Subscribe.
Note
In the production environment, each seller using your application must also have an active or trial Invoices Plus subscription to create invoices with premium features.
Afterpay enables customers to pay invoices using Buy Now Pay Later (BNPL) payments. When customers choose this payment method, Afterpay splits the invoice amount into installments. When the first installment is paid, sellers receive the full invoice amount minus a fee. Afterpay collects the remaining payments.
Note
Afterpay is known as Clearpay in some regions. In this topic, references to Afterpay also apply to Clearpay unless otherwise noted.
To allow customers to make BNPL payments using the Invoices API, set buy_now_pay_later to true in the invoice.accepted_payment_methods field.
Link to section
Requirements and processing limits
The following requirements apply to BNPL invoice payments:
Seller account requirements:
The seller account must be activated in a country where Afterpay invoice payments are supported. This setting is found in the country field of the corresponding Merchant object.
The seller account must be configured to accept Afterpay as a payment method for the Online channel. Sellers can set up payment methods on the Payment methods page in the Square Dashboard.
Square APIs cannot be used to determine whether sellers accept Afterpay payments. If the seller account doesn't accept Afterpay payments, the Pay by Afterpay payment option isn't shown on the invoice payment page.
Invoice requirements:
The invoice must contain a single BALANCE payment request. Recurring invoices and invoices configured with deposit or installment payment requests aren't supported.
The total invoice amount (including tip) must be within the minimum and maximum processing limits for the country.
Customer requirements:
Customers must have an Afterpay account. Customers who don't already have an account can sign up for one from the invoice payment page.
The invoice amount is split into installments that are interest free if paid on time.
Square API version 2021-04-21 or later is required to enable BNPL invoice payments using the Invoices API. However, to access the buy_now_pay_later field using a Square SDK, you must use a version of the SDK that supports Square API version 2022-10-19 or later.
Link to section
Supported countries
Currently supported countries and corresponding processing limits are shown in following table:
Country
Minimum invoice amount
Maximum invoice amount
Australia (AU)
$1.00
$2,000
Canada (CA)
$1.00
$2,000
United Kingdom (UK)
£1.00
£1,000
United States (US)
$1.00
$4,000
Link to section
How it works
If BNPL payments are enabled for the invoice, the Pay by Afterpay option is shown on the invoice payment page. The customer can choose this option, sign in to their Afterpay account, and make the first installment payment. Note that the Pay by Afterpay option is shown only if the seller accepts Afterpay payments.
After the initial payment, the invoice status is set to PAID and the seller receives the full invoice amount minus the Afterpay fee. Afterpay assumes the responsibility for collecting the remaining payments from the customer.
When creating an invoice, you can enable BNPL payments by setting buy_now_pay_later to true in the accepted_payment_methods field. The following request body excerpt enables the card, square_gift_card, and buy_now_pay_later payment methods:
Square APIs cannot be used to discover whether sellers accept Afterpay payments. Unless you know through other methods that the seller accepts Afterpay payments, you should enable at least one other payment method. If the seller doesn't accept Afterpay payments, the Pay by Afterpay option isn't shown and customers cannot make a payment. Also keep in mind that sellers can disable Afterpay payments after an invoice is created or become ineligible to accept Afterpay payments. In addition, making a BNPL payment requires that customers have (or create) an Afterpay account.
If the country of the seller account isn't a supported country, Square returns the following 400 BAD_REQUEST error:
{
"code": "BAD_REQUEST",
"detail": "Buy now pay later payments are not supported for this location's country",
"field": "invoice.accepted_payment_methods",
"category": "INVALID_REQUEST_ERROR"
}
If the invoice is configured with multiple payment requests, Square returns the following 400 BAD_REQUEST error:
{
"code": "BAD_REQUEST",
"detail": "Buy now pay later payments cannot be enabled for invoices with multiple payment requests",
"field": "invoice.accepted_payment_methods",
"category": "INVALID_REQUEST_ERROR"
}
Note that this error is also returned if an invoice that allows buy_now_pay_later payments is updated to include another payment request.
After the customer successfully pays the initial installment from the invoice payment page, Square does the following:
Sets the invoice status to PAID.
Sets the order state to COMPLETED and adds payment information to the tenders field, as shown in the following excerpt. Afterpay payments have type set to BUY_NOW_PAY_LATER. You can use the tender's id or payment_id field to retrieve the corresponding payment for additional information.
You can test the end-to-end buyer experience for making Afterpay invoice payments in the Square Sandbox. The following steps describe how you can create a test Afterpay customer account directly from the invoice payment page.
Create an invoice that enables buy_now_pay_later as an accepted payment method (example request) and then publish the invoice.
Open the invoice payment page. You can find the URL in the public_url field that is added to the invoice after it is published (and reaches the scheduled_at date, if specified).
Choose Pay by Afterpay, and then follow the prompts to create an Afterpay customer account. You can provide fake contact information, but the phone number format and address must be valid.
Enter 111111 for the verification code. No SMS messages are sent in the Sandbox.
To link a test credit card with Afterpay, enter 4111 1111 1111 1111 for the card number and 111 for the CVV code.
After the payment is processed, it is shown at the bottom of the invoice payment page.
Note
Sandbox test seller accounts are automatically enabled to accept Afterpay payments. The Sandbox ignores Afterpay eligibility checks, such as whether the seller's business category is eligible to accept Afterpay payments.
Link to section
Cash App Pay
Cash App is a mobile payment application available in the United States. Sellers with locations in the United States can enable Cash App Pay as an accepted invoice payment method.
Link to section
Requirements
The following requirements apply to Cash App Pay for invoices:
To enable Cash App Pay as a payment method, the seller account must be activated in the United States. For information about processing rates, see Invoice payments.
Square returns the following error for CreateInvoice or UpdateInvoice requests that set cash_app_pay in non-US locations:
{
"errors": [
{
"code": "BAD_REQUEST",
"detail": "Cash App payments are not supported for this location's country",
"field": "invoice.accepted_payment_methods",
"category": "INVALID_REQUEST_ERROR"
}
]
}
If needed, you can check whether the country of the corresponding Merchant object or the country of the order location is set to US before sending the request.
To use Cash App to pay an invoice, the customer must have a Cash App account and install Cash App on a mobile device. Cash App is available only in the United States.
Square API version 2021-04-21 or later is required to configure Cash App Pay using the Invoices API. However, to access the cash_app_pay field using a Square SDK, you must use a version of the SDK that supports Square API version 2023-07-20 or later.
Link to section
How it works
When creating an invoice, you can enable Cash App Pay by setting cash_app_pay to true in the accepted_payment_methods field. The following CreateInvoice request enables the card and cash_app_pay payment methods:
Create invoice
If Cash App Pay is enabled for the invoice, the Cash App Pay option appears on the invoice payment page.
When the payment page is opened in a Desktop web browser, choosing Cash App Pay generates a QR code that the customer scans with their mobile device.
When the payment page is opened on a mobile device, choosing Cash App Pay deep links to Cash App on the device.
After the customer successfully makes a Cash App payment from the invoice payment page, Square does the following:
Updates the invoice status to PAID.
Sets total_completed_amount_money for the invoice payment request to the amount paid.
Adds payment information to the tenders field of the order, as shown in the following excerpt. Cash App payments have type set to WALLET.
If the Cash App balance doesn't have enough funds to complete the payment, Square attempts to deduct the entire payment from the linked payment source (debit card or bank account) in the customer's Cash App profile. If there is no linked payment source, the payment is declined. For refunds, payments originating from the Cash App balance are refunded to the Cash App balance. Payments originating from a linked debit card or bank account are refunded to the linked debit card or bank account.
You can test the end-to-end customer experience for making Cash App Pay invoice payments in the Square Sandbox. The following steps describe how to enable Cash App Pay for an invoice and then make a Cash App payment from a Desktop browser.
Create an invoice with cash_app_pay as an accepted payment method (example request) and then publish the invoice.
Pay the invoice:
Open the invoice payment page. You can find the URL in the public_url field of the published invoice.
Choose Cash App Pay, and then choose Continue to Cash App Pay.
Scan the QR code with the camera of your mobile device, which directs you to Cash App's Sandbox test application.
Approve the payment.
After the payment is processed, the invoice payment page displays payment information.
Link to section
International availability and considerations
The Invoices API is supported in the following countries: Australia, Canada, France, Ireland, Japan, Spain, the United Kingdom, and the United States. To use the Invoices API to create and manage invoices, the seller account must be activated in one of these countries.
You should be aware of the following location-specific considerations:
Invoice recipient tax IDs - For sellers in EU countries and the United Kingdom, customer data for the invoice recipient can include a tax_ids field that contains the EU VAT identification number of the customer. This tax ID is displayed on the invoice.
The following excerpt shows an example invoice recipient that includes the tax_ids field:
Similar to other InvoiceRecipient fields, the tax ID is retrieved from the associated customer profile and cannot be changed after the invoice is published.
Pricing - Per-transaction pricing for invoice payments varies by location and payment method. For more information, see Invoice payments.
Buy Now Pay Later payments - Afterpay (also known as Clearpay) payments enable customers to pay an invoice using interest-free installments. Afterpay payments for Square invoices are supported in the following countries:
Cash App Pay - Sellers can allow customers to pay invoices using Cash App, a mobile payment application. This payment method is available only for locations and customers in the United States. For more information, see Cash App Pay.
Order service charge - Only orders with locations in Canada or the United States can include a service charge, provided that the service charge isn't apportioned. Specifically, the following must be true:
The location referenced by the location_id of the order or invoice must have country set to CA or US.
The order cannot contain a service charge that has treatment_type set to APPORTIONED_TREATMENT.
This behavior aligns with the seller experience in the Square Dashboard, Square Point of Sale application, and Square Invoices application.
Payment conditions field - The payment_conditions field is available only for sellers in France. This text field contains payment terms and conditions that are displayed on the invoice, such as late payment penalties and early payment discounts. This field is provided so that sellers in France can comply with requirements for documenting this information.
The following excerpt shows an example invoice that includes the payment_conditions field. The field can contain up to 2000 characters and use \n to render a new line. No other formatting characters are supported.
{
"invoice": {
"id": "inv:0-sNXFnYEYEBhBWDRO9Z_Cexample",
"version": 0,
"location_id": "S8GWD5example",
"order_id": "f1XiKTrBzwMBetRz8Yfo9Lexample",
...
"payment_conditions": "Cette facture a été envoyée le 7 avril. Celle-ci doit être réglée sous 15 jour(s) à compter de cette date.\nPassé ce délai, une pénalité de retard de 10 % sera appliquée, ainsi qu'une indemnité forfaitaire de 40 EUR due au titre des frais de recouvrement. Pas d'escompte pour paiement anticipé."
}
}
}
If this field is included in CreateInvoice or UpdateInvoice requests for other locations, Square returns the following error:
{
"errors": [
{
"category": "INVALID_REQUEST_ERROR",
"code": "BAD_REQUEST",
"detail": "Payment conditions are not supported for this location's country",
"field": "invoice.payment_conditions"
}
]
}
Before attempting to set the payment_conditions field, you can call RetrieveMerchant and check the country of the seller account.
Link to section
Webhooks
You can subscribe to webhook notifications for the following invoice events.
For more information about subscribing to events and validating notifications, see Square Webhooks.
The following migration notes apply to the Invoices API.
Square Invoices Plus is a paid subscription plan that provides access to premium invoice features. The subscription includes access to the following features that are supported by the Invoices API and that were previously available without a subscription:
Custom fields
Installment payments
Effective date: September 8, 2021
To create invoices with premium features after the effective date, the seller for whom you are creating the invoice must have an active (or trial) Invoices Plus subscription. For more information, see Premium features available with Invoices Plus.
Note
This change applies across all Square versions for new invoices only. Invoices that were created before the effective date and have premium features can continue to use the features without a subscription. This support includes updating the invoice to add or change premium features.
Your application must implement error handling logic for CreateInvoice or UpdateInvoice requests that catches the error returned if the invoice contains an unsupported feature. You must then remove any premium features from the invoice and retry the request. Specifically:
custom_fields must be empty or omitted.
payment_requests cannot contain a payment request of the INSTALLMENT type.
The Invoices API returns one of the following error codes if the invoice contains an unsupported premium feature. The detail message indicates whether the unsupported feature is custom fields or installment payments. For example, the following errors are returned for a request that contains unsupported installment payments:
Square version 2021-08-18 and later:403 MERCHANT_SUBSCRIPTION_NOT_FOUND
{
"errors": [
{
"category": "MERCHANT_SUBSCRIPTION_ERROR",
"code": "MERCHANT_SUBSCRIPTION_NOT_FOUND",
"detail": "Payment request type INSTALLMENT requires an Invoices Plus subscription."
}
]
}
Square version 2021-07-21 and earlier:400 BAD REQUEST
{
"errors": [
{
"category": "INVALID_REQUEST_ERROR",
"code": "BAD_REQUEST",
"detail": "Payment request type INSTALLMENT requires an Invoices Plus subscription."
}
]
}
The Invoice.accepted_payment_method field represents the payment methods that customers can use to make a payment on the Square-hosted invoice payment page.
In Square version 2021-04-21 and later, this field is required to create an invoice and is included in returned invoices. At least one payment method must be set to true. For valid values, see InvoiceAcceptedPaymentMethods.
This setting is independent of any automatic payment requests for the invoice. It is also independent of the default Payment method setting that sellers can configure for invoices created from Square products. The default Payment method setting cannot be accessed by the Invoices API.
The InvoicePaymentRequest.request_method field and corresponding InvoiceRequestMethod enum are deprecated. Request method options are now represented by the following fields:
Invoice.delivery_method specifies how Square should send invoices, reminders, and receipts to the customer. For valid values, see InvoiceDeliveryMethod.
InvoicePaymentRequest.automatic_payment_source specifies the payment method for an automatic payment. For valid values, see InvoiceAutomaticPaymentSource.
Deprecated in version: 2021-01-21 Retired in version: TBD
The Invoices API continues to accept request_method in create and update requests until the field is retired, but you should use delivery_method and automatic_payment_source when possible. However, starting in version 2021-01-21, request_method isn't included in returned Invoice objects. The API migrates request_method options in responses as follows:
request_method
delivery_method
automatic_payment_source
EMAIL
EMAIL
NONE
CHARGE_CARD_ON_FILE
EMAIL
CARD_ON_FILE
CHARGE_BANK_ON_FILE
EMAIL
BANK_ON_FILE
SHARE_MANUALLY
SHARE_MANUALLY
NONE
SMS
SMS
NONE
SMS_CHARGE_CARD_ON_FILE
SMS
CARD_ON_FILE
SMS_CHARGE_BANK_ON_FILE
SMS
BANK_ON_FILE
Note
The following read-only fields were added for backward compatibility:
CHARGE_BANK_ON_FILE, added in version 2021-01-21.
SMS, SMS_CHARGE_CARD_ON_FILE, and SMS_CHARGE_BANK_ON_FILE, added in version 2021-03-17.
