Learn about using the Square Invoices API to request or automatically collect a payment from a customer for an order.
Invoices API

Invoices API Overview

The Square Invoices platform enables sellers to request or automatically collect payments from their customers. Sellers can use the Seller Dashboard, Square Point of Sale, and Square Invoices application to create and manage invoices. In addition to these Square products, developers can use the Invoices API to create and manage invoicing for orders created using the Orders API.

Integrating the Invoices API into your application flow can help simplify the invoice management process and reduce your application development costs in the following ways:

  • Square follows up with customers based on the invoice settings you specify. You do not need to send invoices, reminders, and receipts, even when invoices are split into multiple payment requests. For more information, see Configuring how Square processes an invoice.

  • Square generates a web page where customers can pay the invoice and manages automatic payments. You do not need to collect or process payments. After each payment, Square sends a receipt to the customer and updates the invoice and associated order. By default, Square also emails invoice status and payment notifications to sellers. For more information, see Pay an invoice.

  • Invoices have built-in integration with the Orders API and Customers API through the order and customer IDs you provide when you create the invoice. For example, Square updates the status of the associated order when the invoice is paid or canceled and gets contact information from the customer profile.

All invoices can be managed using the Invoices API or Square products (the Seller 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 do not include an order ID, which is required by the CreateInvoice endpoint.

  • Invoices created from Square products do not include an order_id field unless a payment has been made on the invoice.

  • The Invoices API does not 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.

For additional considerations, see Requirements and limitations.

The following high-level steps represent a typical workflow for using Square APIs to create an invoice:

  1. 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.

  2. Get the customer ID of the invoice recipient. You can use the customer_id from the order or specify a different one. If needed, call SearchCustomers in the Customers API to search for a customer by phone number, email address, or other supported attribute.

  3. 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, you must provide the card_id.

  4. 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 take no action if you or the seller wants to follow up with the customer directly. Square manages automatic payments and payments that customers make from the invoice payment page. Square also updates the invoice payment status and sends reminders and receipts as scheduled.

    For more information, see Create and Publish an Invoice.

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 update the invoice, cancel the invoice, or refund the invoice. However, you can subscribe to receive webhook notifications about invoice events.

Note

If sellers accept payment directly from customers, they can record the payment in the Seller Dashboard, Square Point of Sale, or Square Invoices application.

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 an Invoice.

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:

A diagram showing the process flow 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 does not 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:

  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11
  • 12
  • 13
  • 14
  • 15
  • 16
  • 17
  • 18
  • 19
  • 20
  • 21
  • 22
  • 23
  • 24
  • 25
  • 26
  • 27
  • 28
  • 29
  • 30
  • 31
  • 32
  • 33
  • 34
  • 35
  • 36
  • 37
  • 38
  • 39
  • 40
  • 41
  • 42
  • 43
  • 44
  • 45
  • 46
  • 47
  • 48
  • 49
  • 50
  • 51
  • 52
  • 53
  • 54
  • 55
  • 56
  • 57
  • 58
  • 59
  • 60
{
  "invoice": {
    "id": "inv:0-s0XFqYEBhBWDYERO9C_Zexample",
    "version": 0,
    "location_id": "S8GWD5example",
    "order_id": "4NuiKTlFzWmbLnRz9YfoL8example",
    "payment_requests": [
      {
        "uid": "83c2716e-f859-4d75-a015-77489example",
        "request_type": "BALANCE",
        "due_date": "2021-08-27",
        "tipping_enabled": true,
        "computed_amount_money": {
          "amount": 1200,
          "currency": "USD"
        },
        "total_completed_amount_money": {
          "amount": 0,
          "currency": "USD"
        },
        "automatic_payment_source": "NONE",
        "reminders": []
      }
    ],
    "invoice_number": "000020",
    "title": "Downtown Print Shop",
    "status": "DRAFT",
    "timezone": "Etc/UTC",
    "created_at": "2021-08-26T15:40:34Z",
    "updated_at": "2021-08-26T15:40:34Z",
    "primary_recipient": {
      "customer_id": "HXJKX5BBKGWX34XEMS2example",
      "given_name": "John",
      "family_name": "Doe",
      "email_address": "doe@email.com"
    },
    "accepted_payment_methods": {
      "card": true,
      "square_gift_card": true,
      "bank_account": false,
      "buy_now_pay_later": true
    },
    "custom_fields": [
      {
        "label": "Rules",
        "value": "You must agree to the following terms and conditions ...",
        "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": "2021-08-24",
    "store_payment_method_enabled": false
  },
  "errors": []
}

The following table describes key invoice settings. For information about all available invoices settings, see Invoice.

Field
Description
order_idThe ID of the corresponding order that was created using the Orders API. You can create one invoice for each order. The total computed_amount_money amounts of all invoice payment requests equals 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_requestsThe payment schedule for the invoice. The example invoice contains one payment request for the full order amount due by the specified date. Square calculates the following amounts and adds them to the invoice:
 •   computed_amount_money is the amount due for the payment request.
 •   total_completed_amount_money is the amount the customer has paid for the payment request. For more information, see Configuring payment requests.
delivery_methodThe method Square uses to send invoices, reminders, or receipts to the customer. If set to SHARE_MANUALLY, Square does not send the invoice or receipt.
scheduled_atThe date to process the invoice. If not specified, Square processes the invoice immediately after it is published.
primary_recipientThe customer responsible for the invoice. You specify the customer ID for the invoice and Square retrieves additional information from the customer profile in the seller's Customer Directory. Note that the customer who receives the invoice can be different from the customer who placed the order.
statusThe invoice status. When an invoice is created, the status is set to DRAFT. You must publish the draft invoice for the customer to receive the invoice, either immediately or at the scheduled date.
invoice_numberA 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. Do not confuse this field with the Square-assigned invoice id used for requests to the Invoices API.
versionThe 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_methodsThe 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 Seller Dashboard.
custom_fieldsUp to two customer-facing seller-defined custom fields. Custom fields require an Invoices Plus subscription.
public_urlThe URL of the invoice payment page. This field is added after the invoice is published and the scheduled_at date (if specified) is reached.
titleThe 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_dateThe date of the sale or the date of the service. This display field appears on the invoice but does not drive any business logic.
store_payment_method_enabledIndicates 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 is not supported.
subscription_idThe ID of the subscription associated with the invoice. This field is present only on recurring subscription billing invoices.

For more information, including additional requirements, see Create and Publish an Invoice.

During the lifecycle of an invoice, Square sends automated communications to customers and 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 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 does not 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.

EventCommunication
Invoice publishedSquare sends an invoice after a successful PublishInvoice request. Invoices are sent on the scheduled_at date if one is specified; otherwise, they are 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 does not 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 reachedOn the scheduled date, Square sends the reminder at 11:00 AM in the invoice's time zone. Note the following considerations:
 •    For SMS, Square does not send reminders.
 •    For SHARE_MANUALLY, Square emails scheduled reminders. The SHARE_MANUALLY delivery method does not 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 does not send the reminder.
Payment madeSquare 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 Seller Dashboard, Square Point of Sale, or Square Invoices application and selects the Send receipt checkbox.
 •    If delivery method is set to SHARE_MANUALLY, Square does not 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 unsuccessfulSquare sends the invoice by email and changes the automatic_payment_source field of the payment request to NONE.
Invoice updatedSquare 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 does not notify the customer.
Invoice canceledSquare 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 does not 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 Seller 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.

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 Seller Dashboard. For more information, see Edit Your Notification Settings in Manage Your Square Invoices.

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.

The following requirements, limitations, and other considerations apply when using the Invoices API.

  • OAuth permissions. Applications that use OAuth and the Invoices API require the following OAuth permissions:

    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. For more information, see Connect your Application to a Seller's Account Using OAuth.

  • 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 Keep Records of 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 does not 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.

  • The minimum invoice amount. The minimum amount for an invoice payment request is 100 base units. For more information, see Minimum invoice amounts by currency.

  • App Marketplace requirements. If you intend to list your application on the Square App Marketplace, see the related Invoices 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. For more information, see 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 does not 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 Seller 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:

An invoice that includes a **Special Offer** custom field above the invoice line items and an **Arrival instructions** custom field below the invoice line items.

The following CreateInvoice request creates an invoice similar to the preceding example:

Create Invoice
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11
  • 12
  • 13
  • 14
  • 15
  • 16
  • 17
  • 18
  • 19
  • 20
  • 21
  • 22
  • 23
  • 24
  • 25
  • 26
  • 27
  • 28
  • 29
  • 30
  • 31
  • 32
  • 33
  • 34
  • 35
  • 36
  • 37
  • 38
curl https://connect.squareupsandbox.com/v2/invoices \
  -X POST \
  -H 'Square-Version: 2022-11-16' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{
    "idempotency_key": "{UNIQUE_KEY}",
    "invoice": {
      "order_id": "AdSjVqPCzOAQqvTnzy46VLexample",
      "custom_fields": [
        {
          "label": "Special Offer",
          "value": "Refer a friend and get 10% off your next visit! Check our website for offer details.",
          "placement": "ABOVE_LINE_ITEMS"
        },
        {
          "label": "Arrival instructions",
          "value": "Please arrive 5 minutes before your scheduled appointment.\nWe offer free parking behind our office.",
          "placement": "BELOW_LINE_ITEMS"
        }
      ],
      "primary_recipient": {
        "customer_id": "DJREAYPRBMSSFAB4TGAexample"
      },
      "delivery_method": "EMAIL",
      "payment_requests": [
        {
          "request_type": "BALANCE",
          "due_date": "2020-12-31"
        }
      ],
      "accepted_payment_methods": {
        "card": true,
        "square_gift_card": true
      },
      "title": "Sports Medicine Group"
    }
  }'

The following considerations apply to custom fields:

  • Custom fields are supported only with an Invoices Plus subscription.

  • If two custom fields use the same placement above or below line items, the custom fields are rendered in the order that they are 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 does not support sparse updates for custom fields. To update a custom field, you must provide the complete custom_fields list in the update request. For more information, see Update custom fields.

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.

Installment payments are supported only with an Invoices Plus subscription.

Note

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 Seller 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.

  1. Open the Developer Dashboard.

  2. In the Sandbox Test Accounts section, choose Open next to Default Test Account. This opens the Seller Dashboard associated with the default test account.

  3. After you sign in and open the Seller Dashboard as described in the previous steps, navigate to the following page: https://squareupsandbox.com/dashboard/invoices/learn-more.

  4. Choose Try free for 30 days.

  5. To ensure that the subscription does not expire after 30 days, provide test credit card information:

    1. Open the Pricing & Subscriptions page for the account. From the main menu, choose Account & Settings, expand Business information, and then choose Pricing & Subscriptions.

    2. For the Invoices Plus subscription, choose Subscribe.

    3. 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.

For more information about the Square Sandbox, see Sandbox Overview.

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 four equal 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.

For information about Afterpay integration, see Afterpay and Square. For pricing information, see Invoice payments.

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.

The following requirements apply when using 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 Seller Dashboard.

      Square APIs cannot be used to determine whether sellers accept Afterpay payments. If the seller account does not accept Afterpay payments, the Pay by Afterpay payment option is not 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 are not 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 do not already have an account can sign up for one from the invoice payment page.

      The invoice amount is split into four equal installments due every 2 weeks over a 6 week period. The installments are interest free if they are paid on time.

  • Square 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 version 2022-10-19 or later.


Currently supported countries and corresponding processing limits are shown in following table:

CountryMinimum invoice amountMaximum 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$2,000

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 of four installment payments. 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 does not accept Afterpay payments, the Pay by Afterpay option is not 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 is not a supported country, Square returns the following 400 BAD_REQUEST error:

If the invoice is configured with multiple payment requests, Square returns the following 400 BAD_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 makes the initial payment 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. Note that the payment type is BUY_NOW_PAY_LATER.

  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11
  • 12
  • 13
  • 14
  • 15
  • 16
  • 17
  • 18
  • 19
  • 20
  • 21
  • 22
  • 23
  • 24
  • 25
  • 26
  • 27
  • 28
  • 29
  • 30
  • 31
  • 32
  • 33
  • 34
  • 35
  • 36
  • 37
  • 38
  • 39
  • 40
  • 41
{
  "order": {
    "id": "yUsEDCsfAtaHiewzVUNp0Aexample",
    "location_id": "LSHCVFexample",
    "line_items": [
      {
        "uid": "209b68f4-681b-4449-8251-34cfeexample",
        "quantity": "1",
        "name": "Winter jacket",
        "base_price_money": {
          "amount": 10000,
          "currency": "USD"
        },
        ...
      }
    ],
    "created_at": "2022-08-22T22:03:08.388Z",
    "updated_at": "2022-08-23T00:45:39.000Z",
    "state": "COMPLETED",
    ...
    "tenders": [
      {
        "id": "NimOlcvySGXCrL4LHtRTTVexample",
        "location_id": "LSHCVFexample",
        "transaction_id": "yUsEDCsfAtaHiewzVUNp0Aexample",
        "created_at": "2022-08-23T00:45:37Z",
        "amount_money": {
          "amount": 10000,
          "currency": "USD"
        },
        "type": "BUY_NOW_PAY_LATER",
        "payment_id": "NimOlcvySGXCrL4LHtRTTVexample"
      }
    ],
    ...
    "net_amount_due_money": {
      "amount": 0,
      "currency": "USD"
    }
  }
}

You can test the end-to-end customer experience for making Afterpay invoice payments in the Square Sandbox. The following steps describe how to create a test Afterpay customer account directly from the invoice payment page.

  1. Create and publish an invoice that has the buy_now_pay_later payment method enabled.

  2. 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).

  3. 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 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.

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. 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:

    • Australia

    • Canada

    • United Kingdom

    • United States

    Sellers in these countries can configure their accounts to use this payment method. For more information, see Buy Now Pay Later payments with Afterpay.

  • Order service charge. Only orders with locations in Canada or the United States can include a service charge at this time. Specifically, the location referenced by the location_id of the order or invoice must have country set to CA or US. This behavior aligns with the seller experience in the Seller Dashboard, Square Point of Sale application, and Square Invoices application.

You can subscribe to webhook notifications for the following invoice events.

Event
Permission
Description
invoice.createdINVOICES_READA draft invoice was created.
invoice.publishedINVOICES_READAn invoice was published. This also applies to invoices that are published but scheduled to be processed at a later time.
invoice.updatedINVOICES_READAn invoice was changed. This event is also invoked following invoice.published and invoice.canceled events.
invoice.payment_madeINVOICES_READA payment was made for an invoice.
invoice.scheduled_charge_failedINVOICES_READA scheduled automatic payment has failed.
invoice.canceledINVOICES_READAn invoice was canceled.
invoice.refundedINVOICES_READA refund was processed for an invoice.
invoice.deletedINVOICES_READA draft invoice was deleted. A deleted invoice is removed entirely from the seller account and cannot be retrieved.

Invoice event notifications include the invoice ID and the invoice object. The exception is invoice.deleted, which does not include the invoice object.

The following is an example invoice.created notification:

  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11
  • 12
  • 13
  • 14
  • 15
  • 16
  • 17
  • 18
  • 19
  • 20
  • 21
  • 22
  • 23
  • 24
  • 25
  • 26
  • 27
  • 28
  • 29
  • 30
  • 31
  • 32
  • 33
  • 34
  • 35
  • 36
  • 37
  • 38
  • 39
  • 40
  • 41
  • 42
  • 43
  • 44
  • 45
  • 46
  • 47
  • 48
  • 49
  • 50
  • 51
  • 52
  • 53
  • 54
  • 55
{
  "merchant_id": "031FEVexample",
  "location_id": "S8GWD5example",
  "type": "invoice.created",
  "event_id": "b407d383-c47f-4eeb-6785-c235Aexample",
  "created_at": "2021-11-22T21:45:11Z",
  "data": {
    "type": "invoice",
    "id": "inv:0-ChDjw6T3HRaM2WeOo32zYexample",
    "object": {
      "invoice": {
        "accepted_payment_methods": {
          "card": true,
          "square_gift_card": true,
          "bank_account": false,
          "buy_now_pay_later": true
        },
        "created_at": "2021-11-22T21:45:11Z",
        "delivery_method": "EMAIL",
        "id": "inv:0-ChDjw6T3HRaM2WeOo32zYexample",
        "invoice_number": "2021_04523",
        "location_id": "S8GWD5example",
        "order_id": "Wc3lDgzNtDKLH01jwhB4example",
        "payment_requests": [
          {
            "automatic_payment_source": "NONE",
            "computed_amount_money": {
              "amount": 5581,
              "currency": "USD"
            },
            "due_date": "2021-12-31",
            "request_type": "BALANCE",
            "tipping_enabled": false,
            "total_completed_amount_money": {
              "amount": 0,
              "currency": "USD"
            },
            "uid": "255e2f25-0487-4e29-8457-87baa60f50ac"
          }
        ],
        "primary_recipient": {
          "customer_id": "HXJKX5BBKGWX34XEMS2example",
          "given_name": "John",
          "family_name":"Doe",
          "email_address":"doe@email.com"
        },
        "status": "DRAFT",
        "timezone": "America/Los_Angeles",
        "title": "Downtown Print Shop",
        "updated_at": "2021-11-22T21:45:11Z",
        "version": 0
      }
    }
  }
}  

For more information about subscribing to events and validating notifications, see Square Webhooks Overview.

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. 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 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

  • Square version 2021-07-21 and earlier: 400 BAD REQUEST

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 is not included in returned Invoice objects. The API migrates request_method options in responses as follows:

request_methoddelivery_methodautomatic_payment_source
EMAILEMAILNONE
CHARGE_CARD_ON_FILEEMAILCARD_ON_FILE
CHARGE_BANK_ON_FILEEMAILBANK_ON_FILE
SHARE_MANUALLYSHARE_MANUALLYNONE
SMSSMSNONE
SMS_CHARGE_CARD_ON_FILESMSCARD_ON_FILE
SMS_CHARGE_BANK_ON_FILESMSBANK_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.

If you need more assistance, contact Developer Support or ask for help in the Developer Forums.