Invoices API

Applies to: Invoices API | Orders API | Customers API | Cards API

Use the Invoices API to request or automatically collect a payment from a customer for an order.

The Square Invoices platform lets sellers request or automatically collect payments from their customers. Sellers can use the Square Dashboard, Square Point of Sale, and Square Invoices application to create and manage invoices.

Developers can use the Invoices API to manage invoicing for orders created using the Orders API, and then Square collects the payment from customers.

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

Simplify invoice management and reduce your application development costs by integrating the Invoices API into your application flow:

• You don't need to collect or process payments. Square collects payments from customers by generating a Square-hosted online payment page or by processing automatic payments. For more information, see Pay an invoice.

• You don't need to send invoices, reminders, or receipts. Square follows up with customers based on the invoice settings you specify, even when invoices are split into multiple payment requests. By default, Square also sends notifications to sellers. For more information, see Configuring how Square processes an invoice.

• You don't need to manage order status. Using the order ID you provide when creating an invoice, Square updates the order when the invoice is paid or canceled. Square also gets customer contact information based on the customer ID you provide.

All invoices can be managed using the Invoices API or Square products (the Square Dashboard, Square Point of Sale, and Square Invoices application). However, note the following considerations:

• Invoices created with the Invoices API must be associated with an order that was created with the Orders API. Orders created from Square products cannot be associated with an invoice because they don't include an order ID, which is required by the CreateInvoice endpoint.
• 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.

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 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, provide a card_id retrieved using ListCards in the Cards API.

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 let you or the seller send the payment page URL to the customer. Square collects all invoice payments, either directly from customers (from the online payment page) or through automatic payments. Square also updates the invoice payment status and sends reminders and receipts as scheduled.

   For more information, see Create and Publish Invoices.

Because Square APIs cannot be used to pay invoices or manage payment status, no action is required from you after the invoice is published unless you need to add or remove attachments, update the invoice, cancel the invoice, or refund the invoice.

The Invoices API supports the following operations:

• Create and publish an invoice
• Retrieve, list, or search invoices
• Create or delete invoice attachments
• Update an invoice
• Cancel or delete an invoice

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

You can subscribe to receive webhook notifications for invoice events.

The following diagram shows the order of Invoices API requests that you use to manage an invoice and the webhook events triggered 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.

The Invoice object is the core component of the Invoices API. Consider the following draft invoice that requests a single payment of $12 by the due date:

{
    "invoice": {
        "id": "inv:0-ChAk0kZZW5IUxO0bgfIux95oEI4I",
        "version": 1,
        "location_id": "M8AKAD8160XGR",
        "order_id": "4AGVyEPgvg3RYVZFYjol6QN7Bg4F",
        "payment_requests": [
            {
                "uid": "1c6e2c0a-0124-40a8-a90f-51957be40f64",
                "request_type": "BALANCE",
                "due_date": "2024-01-13",
                "tipping_enabled": false,
                "computed_amount_money": {
                    "amount": 6213,
                    "currency": "USD"
                },
                "total_completed_amount_money": {
                    "amount": 0,
                    "currency": "USD"
                },
                "automatic_payment_source": "NONE"
            }
        ],
        "primary_recipient": {
            "customer_id": "0K8P8KCSV9NXQV2V5129RASF4W",
            "given_name": "Sara",
            "family_name": "Vera",
            "email_address": "[email protected]"
        },
        "invoice_number": "2408_0920",
        "title": "Downtown Print Shop",
        "description": "Canvas photo prints",
        "status": "DRAFT",
        "timezone": "America/Los_Angeles",
        "created_at": "2023-12-14T21:22:16Z",
        "updated_at": "2023-12-14T21:24:10Z",
        "accepted_payment_methods": {
            "card": true,
            "square_gift_card": true,
            "bank_account": false,
            "buy_now_pay_later": true,
            "cash_app_pay": true
        },
        "custom_fields": [
            {
                "label": "Service Agreement",
                "value": "The following terms and conditions apply to orders ...",
                "placement": "ABOVE_LINE_ITEMS"
            },
            {
                "label": "Refund Policy",
                "value": "Refunds will be made on the original payment method ...",
                "placement": "ABOVE_LINE_ITEMS"
            }
        ],
        "delivery_method": "EMAIL",
        "sale_or_service_date": "2023-12-11",
        "store_payment_method_enabled": true,
        "attachments": [
            {
                "id": "inva:0-ChDp54tYJAPaJtfwCyzkAEPO",
                "filename": "terms_and_agreements.pdf",
                "description": "Service contract",
                "filesize": 81839,
                "hash": "2ec7f007ad6d470668a5855aefcb377f",
                "mime_type": "application/pdf",
                "uploaded_at": "2023-12-14T21:24:10Z"
            }
        ]
    }
}

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

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

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

• Automatic communication from Square to customers
• Automatic communication from Square to 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 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.

Square notifies sellers about the following invoice-related events using email, unless noted otherwise:

• A customer views the Square-hosted invoice payment page. This push notification is sent only to the Square Invoices mobile application.
• An invoice or reminder is sent to the customer.
• An invoice is updated or canceled.
• A payment is made on the invoice payment page, or an automatic payment is completed.

These events include all invoice-related communications sent to customers. Sellers can manage their notification settings in the Square Dashboard. For more information, see Edit Your Notification Settings in Manage Your Square Invoices Online.

Square also emails sellers after the following events:

• Square encounters problems when attempting to communicate with a customer using the email address or phone number recorded in the primary_recipient field of the invoice.
• The invoice is canceled due to suspicious activity.
• A scheduled automatic invoice payment fails.

Sellers cannot unsubscribe from receiving these emails.

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.

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.

The following requirements apply to BNPL invoice payments:

• Seller account requirements:

  • The seller account must be activated in a country where Afterpay invoice payments are supported. This setting is found in the country field of the corresponding Merchant object.

  • The seller account must be configured to accept Afterpay as a payment method for the Online channel. Sellers can set up payment methods on the Payment methods page in the Square Dashboard.

    Square APIs cannot be used to determine whether sellers accept Afterpay payments. If the seller account doesn't accept Afterpay payments, the Pay by Afterpay payment option isn't shown on the invoice payment page.

• Invoice requirements:

  • The invoice must contain a single BALANCE payment request. Recurring invoices and invoices configured with deposit or installment payment requests aren't supported.
  • The total invoice amount (including tip) must be within the minimum and maximum processing limits for the country.

• Customer requirements:

  • Customers must have an Afterpay account. Customers who don't already have an account can sign up for one from the invoice payment page.

    The invoice amount is split into installments that are interest free if paid on time.

• Square API version 2021-04-21 or later is required to enable BNPL invoice payments using the Invoices API. However, to access the buy_now_pay_later field using a Square SDK, you must use a version of the SDK that supports Square API version 2022-10-19 or later.

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

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

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.

1. Create an order (example request).

2. Create an invoice that enables buy_now_pay_later as an accepted payment method (example request) and then publish the invoice.

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

4. Choose Pay by Afterpay, and then follow the prompts to create an Afterpay customer account. You can provide fake contact information, but the phone number format and address must be valid.

   • Enter 111111 for the verification code. No SMS messages are sent in the Sandbox.

   • To link a test credit card with Afterpay, enter 4111 1111 1111 1111 for the card number and 111 for the CVV code.

   After the payment is processed, it is shown at the bottom of the invoice payment page.

   Note

   Sandbox test seller accounts are automatically enabled to accept Afterpay payments. The Sandbox ignores Afterpay eligibility checks, such as whether the seller's business category is eligible to accept Afterpay payments.

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.

The following requirements apply to Cash App Pay for invoices:

• To enable Cash App Pay as a payment method, the seller account must be activated in the United States. For information about processing rates, see Invoice payments.

  Square returns the following error for CreateInvoice or UpdateInvoice requests that set cash_app_pay in non-US locations:

  {
    "errors": [
      {
        "code": "BAD_REQUEST",
        "detail": "Cash App payments are not supported for this location's country",
        "field": "invoice.accepted_payment_methods",
        "category": "INVALID_REQUEST_ERROR"
      }
    ]
  }

  If needed, you can check whether the country of the corresponding Merchant object or the country of the order location is set to US before sending the request.

• To use Cash App to pay an invoice, the customer must have a Cash App account and install Cash App on a mobile device. Cash App is available only in the United States.

• Square API version 2021-04-21 or later is required to configure Cash App Pay using the Invoices API. However, to access the cash_app_pay field using a Square SDK, you must use a version of the SDK that supports Square API version 2023-07-20 or later.

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:

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.

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

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.

1. Create an order (example request).

2. Create an invoice with cash_app_pay as an accepted payment method (example request) and then publish the invoice.

3. Pay the invoice:

   1. Open the invoice payment page. You can find the URL in the public_url field of the published invoice.

   2. Choose Cash App Pay, and then choose Continue to Cash App Pay.

   3. Scan the QR code with the camera of your mobile device, which directs you to Cash App's Sandbox test application.

   4. Approve the payment.

      After the payment is processed, the invoice payment page displays payment information.

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:

  {
    "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 cannot be changed after the invoice is published.

• Pricing - Per-transaction pricing for invoice payments varies by location and payment method. For more information, see Invoice payments.

• Buy Now Pay Later payments - Afterpay (also known as Clearpay) payments enable customers to pay an invoice using interest-free installments. Afterpay payments for Square invoices are supported in the following countries:

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

  This behavior aligns with the seller experience in the Square Dashboard, Square Point of Sale application, and Square Invoices application.

• Payment conditions field - The payment_conditions field is available only for sellers in France. This text field contains payment terms and conditions that are displayed on the invoice, such as late payment penalties and early payment discounts. This field is provided so that sellers in France can comply with requirements for documenting this information.

  The following excerpt shows an example invoice that includes the payment_conditions field. The field can contain up to 2000 characters and use \n to render a new line. No other formatting characters are supported.

  {
    "invoice": {
      "id": "inv:0-sNXFnYEYEBhBWDRO9Z_Cexample",
      "version": 0,
      "location_id": "S8GWD5example",
      "order_id": "f1XiKTrBzwMBetRz8Yfo9Lexample",
      ...
      "payment_conditions": "Cette facture a été envoyée le 7 avril. Celle-ci doit être réglée sous 15 jour(s) à compter de cette date.\nPassé ce délai, une pénalité de retard de 10 % sera appliquée, ainsi qu'une indemnité forfaitaire de 40 EUR due au titre des frais de recouvrement. Pas d'escompte pour paiement anticipé."
      }
    }
  }

  If this field is included in CreateInvoice or UpdateInvoice requests for other locations, Square returns the following error:

  {
    "errors": [
      {
        "category": "INVALID_REQUEST_ERROR",
        "code": "BAD_REQUEST",
        "detail": "Payment conditions are not supported for this location's country",
        "field": "invoice.payment_conditions"
      }
    ]
  }

  Before attempting to set the payment_conditions field, you can call RetrieveMerchant and check the country of the seller account.

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.