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 Square 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 Square 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
{
   "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
      },
      "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"
   },
   "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 you do not provide a value, Square assigns one. 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.
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.

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 OAuth API Overview.

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

Note

Custom fields are supported only with an Invoices Plus subscription.

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-07-20' \
  -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:

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

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

To test premium features and error handling in the Square Sandbox, you can subscribe to Invoices Plus in the Sandbox 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 Sandbox Seller Dashboard associated with the default test account.

  3. After you sign in and open the Sandbox 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, 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.

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.

Note

Installment payments are supported only with an Invoices Plus subscription.

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.

  • 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 Square Seller Dashboard, Square Point of Sale application, and Square Invoices application.

You can subscribe to webhook notifications for the following invoice events. All invoice events require the INVOICES_READ permission.

EventDescription
invoice.createdA draft invoice was created.
invoice.publishedAn invoice was published. This also applies to invoices that are published but scheduled to be processed at a later time.
invoice.updatedAn invoice was changed. This event is also invoked following invoice.published and invoice.canceled events.
invoice.payment_madeA payment was made for an invoice.
invoice.scheduled_charge_failedA scheduled automatic payment has failed.
invoice.canceledAn invoice was canceled.
invoice.refundedA refund was processed for an invoice.
invoice.deletedA 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
{
  "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": {
          "bank_account": false,
          "card": true,
          "square_gift_card": 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.