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.

Link to section

Benefits of using the Invoices 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 don't 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 don't 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 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.

For additional considerations, see Requirements and limitations.

Link to section

How it works

The following high-level steps represent a typical workflow for using Square APIs to create 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.

Link to section

Supported operations

The Invoices API supports the following operations:

• Create and publish an invoice

• Update an invoice

• Retrieve, list, or search invoices

• Cancel or delete an invoice

Invoice payments are managed by Square. You cannot use Square APIs to pay invoices or associated orders directly. For more information, see Pay or Refund Invoices.

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.

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:

{
  "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"
      }
    ],
    "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": "[email protected]"
    },
    "accepted_payment_methods": {
      "card": true,
      "square_gift_card": true,
      "bank_account": false,
      "buy_now_pay_later": true,
      "cash_app_pay": 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",
    "store_payment_method_enabled": false
  }
}

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

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

Link to section

Automatic communication from Square

During the lifecycle of an invoice, Square sends automated communications to customers and sellers:

• Automatic communication from Square to customers

• Automatic communication from Square to sellers

Link to section

Automatic communication from Square to customers

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.

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

Requirements and limitations

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

Link to section

Requirements

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

  • INVOICES_READ to use the following endpoints:

    • GetInvoice

    • ListInvoices

    • SearchInvoices

  • INVOICES_WRITE and ORDERS_WRITE to use the following endpoints:

    • CreateInvoice

    • UpdateInvoice

    • DeleteInvoice

    • CancelInvoice

    • PublishInvoice

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

• App Marketplace requirements - If you intend to list your application on the Square App Marketplace, see 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.

Link to section

Limitations

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

  For more information about order-related requirements and limitations, see Create and Publish Invoices.

• Limitations with the Customers API integration - Invoices are associated with a customer profile through the primary_recipient.customer_id field of the invoice. 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.

  For more information about customer-related requirements and limitations, see Create and Publish Invoices.

• Payments and application fees - You should be aware of the following considerations related to payments and application fees:

  • Developers cannot collect application fees for invoices.

  • Square APIs cannot be used to pay an invoice. Square manages invoice payment flows. For more information, see Pay an invoice.

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

  • Installment payments are supported only with an Invoices Plus subscription.

  • The BANK_ON_FILE automatic payment method cannot be set using the Invoices API. This payment method applies only to invoices that sellers create in Square products.

  • The BUY_NOW_PAY_LATER accepted payment method can only be set for invoices that have a single payment request of 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 Seller 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 theSMS` 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

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)

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.

Link to section

Custom fields

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:

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

curl https://connect.squareupsandbox.com/v2/invoices \
  -X POST \
  -H 'Square-Version: 2023-08-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'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.

Link to section

Installment payments

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.

Link to section

Testing Invoices Plus features in the Sandbox

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.

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

Link to section

Buy Now Pay Later payments with Afterpay

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.

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

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

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:

{
  "invoice": {
    ...
    "payment_requests": [
      {
        "request_type": "BALANCE",
        "due_date": "2022-12-31"
      }
    ],
    "accepted_payment_methods": {
      "card": true,
      "square_gift_card": true,
      "buy_now_pay_later": true
    }
  }
}

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.

{
  "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"
    }
  }
}

Link to section

Testing Afterpay invoice payments

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.

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:

  Copy

  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10

  {
    "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:

curl https://connect.squareupsandbox.com/v2/invoices \
  -X POST \
  -H 'Square-Version: 2023-08-16' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{
    "idempotency_key": "{UNIQUE_KEY}",
    "invoice": {
      "order_id": "{ORDER_ID}",
      "primary_recipient": {
        "customer_id": "{CUSTOMER_ID}"
      },
      "accepted_payment_methods": {
        "card": true,
        "cash_app_pay": true
      },
      "delivery_method": "EMAIL",
      "payment_requests": [
        {
          "request_type": "BALANCE",
          "due_date": "2023-09-30"
        }
      ]
    }
  }'

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.

  Copy

  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11
  • 12
  • 13
  • 14
  • 15
  • 16
  • 17
  • 18
  • 19
  • 20

  { 
    "order": {
      ...
      "tenders": [
        {
          "id": "LHtNRTcimvOlySrLGXC4PGexample",
          "location_id": "LSHCVFexample",
          "transaction_id": "yUsEUNpDCstaHifAewzV0Aexample",
          "created_at": "2023-06-22T10:49:45:37Z",
          "amount_money": {
            "amount": 2900,
            "currency": "USD"
          },
          "type": "WALLET",
          "payment_id": "LHtNRTcimvOlySrLGXC4PGexample"
        }
      ],
      ...
    }
  }
  

  To get wallet_details and other information from the corresponding payment, call GetPayment using the id or payment_id of the tender.

• Sets the order state to COMPLETED when the order is fully paid.

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.

For more information about how sellers and buyers use Cash App, see Accept Payments with Cash App Pay and Cash App Pay.

Link to section

Testing Cash App Pay invoice payments

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.

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:

  Copy

  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11
  • 12
  • 13
  • 14
  • 15
  • 16
  • 17
  • 18

  {
    "invoice": {
      "id": "inv:0-s0XFqYEBhBWDYERO9C_Zexample",
      "version": 0,
      "location_id": "S8GWD5example",
      "order_id": "4NuiKTlFzWmbLnRz9YfoL8example",
      ...
      "primary_recipient": {
        "customer_id": "HXJKX5BBKGWX34XEMS2example",
        "given_name": "John",
        "family_name":"Doe",
        "email_address":"[email protected]",
        "tax_ids": {
          "eu_vat": "IE3426675K"
        }
      }
    }
  }
  

  Similar to other InvoiceRecipient fields, the tax ID is retrieved from the associated customer profile and can't 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:

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

• 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 can't contain a service charge that has treatment_type set to APPORTIONED_TREATMENT.

  This behavior aligns with the seller experience in the Seller 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.

  Copy

  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11

  {
    "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:

  Copy

  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10

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

Invoice event notifications include the invoice ID and the invoice object. The exception is invoice.deleted, which doesn't include the invoice object.

The following is an example invoice.created notification:

{
  "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,
          "cash_app_pay": false
        },
        "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":"[email protected]"
        },
        "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.

Link to section

Migration notes

The following migration notes apply to the Invoices API:

Link to section

Premium features require an Invoices Plus subscription

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.

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

  Copy

  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9

  {
    "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

  Copy

  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9

  {
    "errors": [
      {
        "category": "INVALID_REQUEST_ERROR",
        "code": "BAD_REQUEST",
        "detail": "Payment request type INSTALLMENT requires an Invoices Plus subscription."
      }
    ]
  }
  

Link to section

New Invoice.accepted_payment_method

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.

Link to section

Deprecated InvoicePaymentRequest.request_method

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: