Invoices API

Manage Invoices Using the Invoices API

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 (POS) application, and Square Invoices application to create and manage invoices. In addition to these first-party Square products, developers can use the Invoices API to integrate Square invoices into third-party applications.

Overview Permalink Get a link to this section

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

  • You can create an invoice to request payment for an order. Square follows up with customers for the invoices you create, so you do not need to collect payments or send invoices, reminders, and receipts. Depending on the invoice settings you specify, Square can automatically email the invoice or charge a credit or debit card on file, even when invoices are split into multiple payment requests. By default, Square also emails invoice status and payment notifications to sellers.

  • Square generates and hosts a web page where customers can easily pay the invoice. After each payment, Square sends a receipt to the customer and updates the invoice status as needed.

  • The Invoices API requires an order ID and a customer ID to create and publish an invoice. This enables built-in integration with the Orders API and Customers API. For example, the Invoices API ensures that the invoice payment requests are equal to the total order amount and retrieves the customer's email address from the customer profile.

  • All invoices can be managed using the Invoices API or first-party Square products. However, note the following:

    • To create an invoice with the Invoices API, the associated order must be created with the Orders API. You cannot use orders created from first-party Square products because they do not include an order ID, which is required by the CreateInvoice endpoint.

    • Invoices created from first-party 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 first-party Square products. For example, you cannot set an SMS delivery method or BANK_ON_FILE automatic payment method. For more information, see Limitations.

  • You can subscribe to receive webhook notifications about invoice events.

How it works Permalink Get a link to this section

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

  2. Get the customer ID of the invoice recipient. If the order includes a customer_id, you can use the same customer ID or specify a different one.

  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 payments from a card on file, you must specify the card_id for each payment request. For information about getting a card ID, see Configuring payment requests.

  4. Publish the invoice by calling PublishInvoice in the Invoices API. The Invoice object in the response includes the URL of the Square-hosted invoice page where customers can view the invoice and make a payment, if required.

    For more information, including additional requirements, see Create and publish an invoice.

After you publish the invoice, Square processes it based on the invoice settings and handles the remaining workflow. For example, Square can email the invoice, charge a customer's card on file, or take no action if you or the seller want to follow up with the customer directly. For more information, see Configuring how Square processes an invoice.

Developers cannot use Square APIs to pay invoices or manage payment status. Therefore, no action is required from you after the invoice is published, unless you need to update the invoice or cancel the invoice. Square manages automatic payments and payments that customers make from the invoice page. Square also updates the invoice payment status and sends reminders and receipts. For more information, see Pay an invoice.

Note

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

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, Square processes it based on the invoice settings, generates the invoice payment page, and manages payments and status. For more information, see Configuring how Square processes an invoice.

Note

The diagram does not represent Square API calls used to obtain required information (such as order_id and customer_id) or GetInvoice, ListInvoices, or SearchInvoices requests that can be used to access invoices.

Invoice object Permalink Get a link to this section

The core of the Invoices API is the Invoice object. 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",
            "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":"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"
   }
}

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

FieldDescription
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. This example 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 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. You must also publish invoices that are scheduled to be processed at a later 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 Square-hosted invoice 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 Square-hosted invoice payment page. This field is added after the invoice is published.
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.

Payment requests Permalink Get a link to this section

The payment_requests field defines the payment schedule for an invoice, which includes payment amounts, due dates, and other related settings. The example invoice in the previous section contains one payment request for the full order amount, but you can optionally split the invoice into multiple payment requests. A payment request is represented by the InvoicePaymentRequest object.

The following table shows possible payment scenarios and the corresponding request_type combinations for the invoice payment requests.

Payment scenariorequest_type combination
One payment in full1 BALANCE
A deposit with the balance due later1 DEPOSIT and 1 BALANCE
A deposit with remaining payments in installments
  (requires subscription)
1 DEPOSIT and 2–12 INSTALLMENT
All payments in installments
  (requires subscription)
2–12 INSTALLMENT

Note

Installment payments are supported only with an Invoices Plus subscription.

Deposit or installment payments can be specified by percentage or as a fixed amount.

Example payment requests Permalink Get a link to this section

The following examples show how you can define payment scenarios in the payment_requests field when you create an invoice:

  • One payment in full. The following payment_requests example shows how to request one payment in full:

    ...
    "payment_requests": [
       {
          "request_type":"BALANCE",
          "due_date":"2030-02-01"
       }
    ]
    ...
    

    The single BALANCE payment request represents the total amount of the order.

  • Deposit with balance due later. The following payment_requests example shows how to request a 50% deposit and the remaining 50% balance at a later date:

    ...
    "payment_requests": [
       {
          "request_type":"DEPOSIT",
          "due_date":"2030-02-01",
          "percentage_requested":"50"
       },
       {
          "request_type":"BALANCE",
          "due_date":"2030-03-01"
       }
    ]
    ...
    

    The first DEPOSIT payment request indicates 50% of the total amount on the order. Therefore, the balance is for the remaining amount and is not explicitly specified.

Configuring payment requests Permalink Get a link to this section

The following requirements and considerations apply when configuring payment requests:

  • The due_date and request_type fields must be specified for all payment requests.

  • For DEPOSIT or INSTALLMENT payment requests, you can specify a percentage-based amount or a fixed amount.

    • To specify a percentage-based amount, set the percentage_requested field.

      • For a DEPOSIT request, base the percentage on the total order amount.

      • For INSTALLMENT requests, base the percentage on the total order amount minus any deposit amount. The percentages of all installment payment requests must add up to 100%, as shown in the preceding example.

        Installment payments are supported only with an Invoices Plus subscription.

    • To specify a fixed amount, set the fixed_amount_requested_money field.

      • The total payment amounts in payment_requests must equal the total_money amount of the associated order.

  • The automatic_payment_source field of the payment request indicates whether the request is configured for automatic payments. The following are valid values:

    ValueDescription
    NONENo automatic payment is configured. This is the default value.
    CARD_ON_FILEDirects Square to charge the credit or debit card on file specified by the card_id field of the payment request. To get a card ID, call ListCards and include the customer_id.

    To set up automatic payments from a card on file, you must set the delivery_method of the invoice to EMAIL.
    BANK_ON_FILEDirects Square to initiate a transfer from the bank account on file, which is provided by the customer during the payment flow.

    This value cannot be set from the Invoices API. It applies only to recurring invoices that sellers create in first-party Square products. Invoices with a bank account payment can have only one payment request of type BALANCE.

    If an automatic payment fails, Square sends an invoice to the customer.

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

  • Reminders are scheduled relative to the due_date of the payment request. For more information, see InvoicePaymentReminder. Square sends reminders at 11:00 AM in the timezone specified for the invoice.

Custom fields Permalink Get a link to this section

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 invoice Square-hosted invoice 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: 2021-11-17' \
  -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.

Manage invoices Permalink Get a link to this section

This section describes how you can use the Invoices API to create and manage invoices for orders created using the Orders API.

Create and publish an invoice Permalink Get a link to this section

Creating an invoice is a two-step process: first create a draft invoice and then publish it. Only after you publish the invoice does Square process it. For example, Square can email an invoice to the customer or charge the customer's card on file. You must also publish an invoice that you want to schedule for processing.

To create and publish an invoice, you must provide the following information:

  • The order_id of the associated order. An invoice can be associated with one order only.

    • The order must be created using the Orders API.

    • The order status must be OPEN.

    • The order cannot be associated with another invoice.

    • The order cannot include rewards.

    • The order cannot use rule-based pricing options. Therefore, the pricing_options.auto_apply_discounts and pricing_options.auto_apply_taxes fields cannot be set to true.

  • The customer_id of the invoice recipient.

    • This customer can be different than the customer who created the order. The customer ID is not required until you publish the invoice.

    • The customer profile must exist in the seller's Customer Directory and include either email_address or phone_number. You can call ListCustomers or SearchCustomers if you do not use the customer ID from the order.

    • The customer profile must have a valid email address if the invoice is delivered by email, which includes invoices configured for automatic payments. Square uses this email address to send invoices, reminders, and receipts to the customer.

      Note

      After an invoice is created, the Invoices API does not update the contact information of the recipient if the name, phone number, or email address changes in the associated customer profile. For more information, see Limitations with the Customers API integration.

  • The payment_requests for the invoice, with one or more payment requests that equal the total_money of the order. The Invoices API computes percentage-based payment amounts for the payment schedule based on the total_money of the order. For more information, see Payment requests.

  • The accepted_payment_methods that customers can use to pay the invoice on the Square-hosted invoice page. At least one payment method must be enabled. This setting is independent of any automatic payment requests for the invoice. Customers can choose to make a payment from the invoice page even when the invoice is configured for automatic payments. For supported payment methods, see InvoiceAcceptedPaymentMethods.

Step 1: Create a draft invoice Permalink Get a link to this section

Call CreateInvoice to create a draft invoice, as shown in the following example request:

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
curl https://connect.squareupsandbox.com/v2/invoices \
  -X POST \
  -H 'Square-Version: 2021-11-17' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{
    "idempotency_key": "{UNIQUE_KEY}",
    "invoice": {
      "order_id": "AdSjVqPCzOAQqvTnzy46VLexample",
      "primary_recipient": {
        "customer_id": "DJREAYPRBMSSFAB4TGAexample"
      },
      "delivery_method": "EMAIL",
      "payment_requests": [
        {
          "request_type": "BALANCE",
          "due_date": "2021-09-30"
        }
      ],
      "accepted_payment_methods": {
        "card": true,
        "square_gift_card": true
      },
      "title": "My Invoice Title",
      "sale_or_service_date": "2021-10-14"
    }
  }'

The request body provides the invoice details. In this example, the payment_requests field specifies one payment request (of type BALANCE) for the total order amount, due by the specified due date. In response, the Invoices API returns an invoice with status set to DRAFT.

You can also set reminders on a payment request. The following CreateInvoice request directs Square to send a reminder to the customer one day before the due date. If the payment is made before the due date, Square does not send the reminder.

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
curl https://connect.squareupsandbox.com/v2/invoices \
  -X POST \
  -H 'Square-Version: 2021-11-17' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{
    "idempotency_key": "{UNIQUE_KEY}",
    "invoice": {
      "order_id": "AdSjVqPCzOAQqvTnzy46VLexample",
      "primary_recipient": {
        "customer_id": "DJREAYPRBMSSFAB4TGAexample"
      },
      "delivery_method": "EMAIL",
      "payment_requests": [
        {
          "request_type": "BALANCE",
          "due_date": "2021-09-29",
          "reminders": [
            {
              "relative_scheduled_days": -1,
              "message": "Your payment is due tomorrow."
            }
          ]
        }
      ],
      "accepted_payment_methods": {
        "card": true,
        "square_gift_card": true
      },
      "title": "My Invoice Title",
      "sale_or_service_date": "2021-08-24"
    }
  }'

For more CreateInvoice request examples, see Example Walkthrough: Create and Publish Invoices.

Step 2: Publish the invoice Permalink Get a link to this section

Call PublishInvoice to publish the draft invoice. In the request, you provide the invoice ID and current version.

You can get the ID and version from the invoice returned in the CreateInvoice response. You can also call ListInvoices to retrieve the ID and version or call GetInvoice if you have the ID but need to retrieve the version.

Publish Invoice
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
curl https://connect.squareupsandbox.com/v2/invoices/{invoice_id}/publish \
  -X POST \
  -H 'Square-Version: 2021-11-17' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{
    "version": 0,
    "idempotency_key": "{UNIQUE_KEY}"
  }'

The following is an example response:

{
  "invoice": {
    "id": "inv:0-ChBoaXkM5QOPv9UO9C_Zexample",
    "version": 1,
    "location_id": "S8GWD5example",
    "order_id": "AdSjVqPCzOAQqvTnzy46VLexample",
    "payment_requests": [
      {
        "uid": "ccc0fc9b-c2a5-42a9-836d-92d01example",
        "request_type": "BALANCE",
        "due_date": "2021-09-29",
        "computed_amount_money": {
          "amount": 100,
          "currency": "USD"
        },
        "total_completed_amount_money":{
           "amount":0,
           "currency":"USD"
        },
        "automatic_payment_source": "NONE"
      }
    ],
    "invoice_number": "000028",
    "title": "My Invoice Title",
    "sale_or_service_date": "2021-08-24",
    "public_url": "https://squareupsandbox.com/pay-invoice/inv:0-ChBoaXkM5QOPv9UO9C_Zexample",
    "status": "UNPAID",
    "timezone": "Etc/UTC",
    "created_at": "2021-08-30T19:01:32Z",
    "updated_at": "2021-08-30T19:05:01Z",
    "primary_recipient": {
      "customer_id": "DJREAYPRBMSSFAB4TGAexample",
      "given_name": "John",
      "family_name": "Doe",
      "email_address": "doe@email.com"
    },
    "accepted_payment_methods": {
      "card": true,
      "square_gift_card": true,
      "bank_account": false
    },
    "next_payment_amount_money": {
      "amount": 100,
      "currency": "USD"
    },
    "delivery_method": "EMAIL"
  }
}

After you publish an invoice, Square generates an invoice payment page and returns the page URL in the public_url field. Then, Square uses the invoice settings to determine how to process the invoice. Square takes no action on draft invoices.

Configuring how Square processes an invoice Permalink Get a link to this section

After you publish an invoice, Square performs activities to manage the payment schedule, such as sending an invoice, reminder, or receipt to the customer, or initiating an automatic payment.

You can configure invoice settings to control how Square processes the invoice.

Option 1: Send an invoice to request payment. Square sends the customer an invoice requesting payment by the due date. Square also sends a receipt after a payment is made.

  • scheduled_at. To send an invoice immediately after publishing, omit this field. Otherwise, specify the date to send the invoice.

  • delivery_method. Specify EMAIL.

  • accepted_payment_methods. Specify true for one or more payment methods that customers can use to pay the invoice on the Square-hosted invoice page.

  • For each payment request, configure the following fields:

    • due_date. Specify the date that the payment is due.

    • automatic_payment_source. Keep the default value of NONE.

    • request_type, reminders, and other payment fields, as needed. For more information, see Payment requests. For invoices with multiple payment requests, Square sends invoices and reminders according to the payment schedule.

Option 2: Automatically charge a credit or debit card on file. If the invoice is published on the due date, Square charges the card on file and sends a receipt. If the payment is due later, Square sends an invoice notifying the customer about the upcoming automatic payment. On the due date, Square charges the card on file and sends a receipt.

  • scheduled_at. To send the invoice or receipt immediately after publishing, omit this field. Otherwise, specify the date to send the invoice.

  • delivery_method. Specify EMAIL.

  • accepted_payment_methods. Specify true for one or more payment methods that customers can use to pay the invoice on the Square-hosted invoice page. This field is required even when the invoice is configured for automatic payments because customers can optionally make a payment from the invoice page.

  • For each payment request, configure the following fields:

    • due_date. Specify the date that the payment is due.

    • automatic_payment_source. Specify CARD_ON_FILE.

    • card_id. Specify the ID of the card on file to charge. To get a card ID, call ListCards and provide the customer_id.

    • request_type,reminders, and other payment fields, as needed. For more information, see Payment requests. For invoices with multiple payment requests, Square sends invoices and reminders according to the payment schedule.

Option 3: Square takes no action. In this case, the seller or the application developer follows up with the customer. Square does not send the invoice or receipt to the customer.

  • delivery_method. Specify SHARE_MANUALLY.

  • accepted_payment_methods. Specify true for one or more payment methods that customers can use to pay the invoice on the Square-hosted invoice page.

  • For each payment request, configure the following fields:

    • due_date. Specify the date that the payment is due.

    • automatic_payment_source. Keep the default value of NONE.

    • request_type, reminders, and other payment fields, as needed. For more information, see Payment requests.

Note

The following settings can be configured only from first-party Square products:

  • SMS (text message) delivery method.

  • BANK_ON_FILE automatic payment method, which applies only to recurring invoices.

You cannot use the Invoices API to set these values, but you can use the Invoices API to change them. For example, you can change an SMS invoice delivery method to EMAIL or SHARE_MANUALLY.

For additional considerations about the SMS delivery method, see Limitations.

Automatic communication from Square to customers Permalink Get a link to this section

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 Square-hosted invoice 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 timezone. 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 Square-hosted invoice page.
 •   An automatic payment was 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, POS application, or 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.

Note: 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 Square-hosted invoice 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 Square-hosted invoice 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, POS application, or 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.

Automatic communication from Square to sellers Permalink Get a link to this section

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

  • A customer views the Square-hosted invoice 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 Square-hosted invoice 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 customers 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.

Update an invoice Permalink Get a link to this section

You call UpdateInvoice to update an invoice. You can modify invoice fields, clear invoice fields, or do both.

In the request body, you provide one or both of the following:

  • A sparse Invoice object that contains only the fields you want to add or change, along with the new values.

  • A fields_to_clear array with a comma-separated list of fields to remove.

Note

Updating a custom field is an exception. You must provide the complete custom_fields list to add or change a custom field. For more information, see Update custom fields.

The following restrictions apply to updating an invoice in a DRAFT state:

  • You cannot update the order_id or location_id field.

The following restrictions apply to updating a published invoice:

  • You cannot update the primary_recipient, order_id, or location_id field.

  • You cannot update an invoice in the PAID, REFUNDED, CANCELED, or FAILED terminal states.

  • You cannot update an invoice in the PAYMENT_PENDING state. You must wait for the payment to complete before you can update it. In addition, the seller or customer cannot initiate another payment for an invoice in this state.

When you update a published invoice, Square notifies the seller that the invoice was updated. Square might also notify the customer, depending on the invoice delivery method:

  • EMAIL. Square sends an email to the customer.

  • SMS. Square sends a text message to the customer unless the customer has opted out of text message updates from Square invoices.

  • SHARE_MANUALLY. Square does not notify the customer.

You must provide the invoice ID and current version for all UpdateInvoice requests. You can call ListInvoices to retrieve the ID and version, or you can call GetInvoice if you have the ID but need to retrieve the version.

Example 1: Update an invoice number and title Permalink Get a link to this section

The following UpdateInvoice request updates the title and invoice_number:

Update Invoice
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11
  • 12
  • 13
curl https://connect.squareupsandbox.com/v2/invoices/{invoice_id} \
  -X PUT \
  -H 'Square-Version: 2021-11-17' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{
    "idempotency_key": "{UNIQUE_KEY}",
    "invoice": {
      "version": 0,
      "title": "My Updated Title",
      "invoice_number": "new-number-100"
    }
  }'

If these fields are not previously set, the update operation adds them to the invoice. The invoice version increments each time the invoice is updated.

Example 2: Update payment requests by removing the deposit request Permalink Get a link to this section

Consider the following draft invoice that requests a deposit payment and a balance payment due at a later date. The invoice is configured to automatically charge a card on file and to accept credit and debit card payments on the Square-hosted invoice page.

{
   "invoice":{
      "id":"bn9CXYfwPZh6Ednexample",
      "version":0,
      "location_id":"S8GWD5example",
      "order_id":"81b7Ar7KPHmlXHs2qhjMc5example",
      "payment_requests":[
         {
            "uid":"a17ee758-fb36-4226-a535-95916example",
            "request_type":"DEPOSIT",
            "due_date":"2020-06-15",
            "percentage_requested":"20",
            "card_id":"ccof:aD1D4q9aUXTkexample",
            "computed_amount_money":{
               "amount":100,
               "currency":"USD"
            },
            "total_completed_amount_money":{
               "amount":0,
               "currency":"USD"
            },
            "automatic_payment_source":"CARD_ON_FILE"
         },
         {
            "uid":"79e1d50d-6a35-40fc-bfd2-05913example",
            "request_type":"BALANCE",
            "due_date":"2020-07-01",
            "card_id":"ccof:aD1D4q9aUXTkexample",
            "computed_amount_money":{
               "amount":400,
               "currency":"USD"
            },
            "total_completed_amount_money":{
               "amount":0,
               "currency":"USD"
            },
            "automatic_payment_source":"CARD_ON_FILE"
         }
      ],
      "invoice_number":"000034",
      "status":"DRAFT",
      "timezone":"Etc/UTC",
      "created_at":"2020-06-10T18:49:06Z",
      "updated_at":"2020-06-10T18:49:06Z",
      "primary_recipient":{
         "customer_id":"DJREAYPRBMSSFAB4TGAexample",
         "given_name":"John",
         "family_name":"Doe",
         "email_address":"doe@email.com"
      },
      "accepted_payment_methods": {
        "card": true,
        "square_gift_card": false,
        "bank_account": false
      },
      "delivery_method":"EMAIL"
   }
}

The following UpdateInvoice request removes the deposit payment request from the preceding invoice and allows customers to use a Square gift card to make a payment on the invoice page. Note the fields_to_clear field, which specifies payment_requests[a17ee758-fb36-4226-a535-95916example] as the field to remove. The uid index value for payment_requests identifies the specific payment request to remove.

Update Invoice
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11
  • 12
  • 13
  • 14
  • 15
  • 16
  • 17
curl https://connect.squareupsandbox.com/v2/invoices/bn9CXYfwPZh6Ednexample \
  -X PUT \
  -H 'Square-Version: 2021-11-17' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{
    "idempotency_key": "{UNIQUE_KEY}",
    "invoice": {
      "version": 0,
      "accepted_payment_methods": {
        "square_gift_card": true
      }
    },
    "fields_to_clear": [
      "payment_requests[a17ee758-fb36-4226-a535-95916example]"
    ]
  }'

The following is the updated draft invoice. It now requests only one automatic payment in full (no deposit) and accepts credit card, debit card, and Square gift card payments on the invoice page.

{
   "invoice":{
      "id":"bn9CXYfwPZh6Ednexample",
      "version":1,
      "location_id":"S8GWD5example",
      "order_id":"81b7Ar7KPHmlXHs2qhjMc5example",
      "payment_requests":[
         {
            "uid":"79e1d50d-6a35-40fc-bfd2-05913example",
            "request_type":"BALANCE",
            "due_date":"2020-07-01",
            "card_id":"ccof:aD1D4q9aUXTkexample",
            "computed_amount_money":{
               "amount":500,
               "currency":"USD"
            },
            "total_completed_amount_money":{
               "amount":0,
               "currency":"USD"
            },
            "automatic_payment_source":"CARD_ON_FILE"
         }
      ],
      "invoice_number":"000034",
      "status":"DRAFT",
      "timezone":"Etc/UTC",
      "created_at":"2020-06-10T18:49:06Z",
      "updated_at":"2020-06-10T20:28:50Z",
      "primary_recipient":{
         "customer_id":"DJREAYPRBMSSFAB4TGexample",
         "given_name":"John",
         "family_name":"Doe",
         "email_address":"doe@email.com"
      },
      "accepted_payment_methods": {
        "card": true,
        "square_gift_card": true,
        "bank_account": false
      },
      "delivery_method":"EMAIL"
   }
}

Example variation: Remove the deposit request and change the balance due date

Now consider the following variation. Suppose you want to remove the deposit payment request and also change the due date of the remaining balance payment request. In other words, you want to remove one payment request and update another.

In this case, the UpdateInvoice request body must include:

  • A payment_requests field in the invoice object that specifies the uid of the payment request to update, along with the new value for the due_date field.

  • The fields_to_clear field that specifies the uid of the payment request to remove.

Update Invoice
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11
  • 12
  • 13
  • 14
  • 15
  • 16
  • 17
  • 18
  • 19
  • 20
curl https://connect.squareupsandbox.com/v2/invoices/bn9CXYfwPZh6Ednexample \
  -X PUT \
  -H 'Square-Version: 2021-11-17' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{
    "idempotency_key": "{UNIQUE_KEY}",
    "invoice": {
      "version": 0,
      "payment_requests": [
        {
          "uid": "79e1d50d-6a35-40fc-bfd2-05913example",
          "due_date": "2020-06-15"
        }
      ]
    },
    "fields_to_clear": [
      "payment_requests[a17ee758-fb36-4226-a535-95916example]"
    ]
  }'

Example 3: Remove and add payment requests Permalink Get a link to this section

The following UpdateInvoice request removes an existing payment request and adds two new payment requests:

Update 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
curl https://connect.squareupsandbox.com/v2/invoices/{invoice_id} \
  -X PUT \
  -H 'Square-Version: 2021-11-17' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{
    "idempotency_key": "{UNIQUE_KEY}",
    "invoice": {
      "version": 0,
      "invoice_number": "new-number-100",
      "payment_requests": [
        {
          "request_type": "DEPOSIT",
          "due_date": "2020-11-30",
          "percentage_requested": "25",
          "automatic_payment_source": "CARD_ON_FILE",
          "card_id": "ccof:I6pHF8bMQghMexample"
        },
        {
          "request_type": "BALANCE",
          "due_date": "2020-12-30",
          "automatic_payment_source": "CARD_ON_FILE",
          "card_id": "ccof:I6pHF8bMQghMexample"
        }
      ]
    },
    "fields_to_clear": [
      "payment_requests[ea89248e-ff10-4958-98e9-2433bexample]"
    ]
  }'

Note the following:

  • fields_to_clear identifies the specific payment request to remove by providing its uid value.

  • invoice specifies payment_requests without referring to any existing uid value. Therefore, the Invoices API adds these payment requests. If you added a uid value to any of these payment requests, it would indicate you wanted to update the values of an existing payment request.

Example 4: Replace payment request percentages with exact amounts Permalink Get a link to this section

Consider the following draft invoice that has two payment requests: a deposit of 20% and the remaining balance due at a later date. Here is an excerpt of the invoice:

{
  "invoice": {
    "id": "lsBlUr0vkDIu_mAexample",
    "version": 0,
    "location_id": "S8GWD5example",
    "order_id": "8tXvK5qwjkEPbeLixWaKSxexample",
    "payment_requests": [
      {
        "uid": "32d69642-1614-4d84-ae4a-75d51example",
        "request_type": "DEPOSIT",
        "due_date": "2020-06-22",
        "percentage_requested": "20",
        "computed_amount_money": {
          "amount": 100,
          "currency": "USD"
        },
        "total_completed_amount_money": {
          "amount": 0,
          "currency": "USD"
        },
        "automatic_payment_source": "NONE"
      },
      {
        "uid": "622a0315-e640-4a7a-9763-87461example",
        "request_type": "BALANCE",
        "due_date": "2020-09-01",
        "computed_amount_money": {
          "amount": 400,
          "currency": "USD"
        },
        "total_completed_amount_money": {
          "amount": 0,
          "currency": "USD"
        },
        "automatic_payment_source": "NONE"
      }
    ],
    ...
  }
}

Now suppose you want to specify the exact amount for these payment requests instead of percentages. These are two distinct updates to the same payment request:

  • Add a new fixed_amount_requested_money field.

  • Remove the percentage_requested field.

The following UpdateInvoice request performs both of these updates:

Update Invoice
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11
  • 12
  • 13
  • 14
  • 15
  • 16
  • 17
  • 18
  • 19
  • 20
  • 21
  • 22
  • 23
curl https://connect.squareupsandbox.com/v2/invoices/{invoice_id} \
  -X PUT \
  -H 'Square-Version: 2021-11-17' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{
    "idempotency_key": "{UNIQUE_KEY}",
    "invoice": {
      "version": 0,
      "payment_requests": [
        {
          "uid": "32d69642-1614-4d84-ae4a-75d51example",
          "fixed_amount_requested_money": {
            "amount": 100,
            "currency": "USD"
          }
        }
      ]
    },
    "fields_to_clear": [
      "payment_requests[32d69642-1614-4d84-ae4a-75d51example].percentage_requested"
    ]
  }'

Both invoice and fields_to_clear specify the same uid value. As a result, the specified update is applied to the same payment request:

  • invoice adds the fixed_amount_requested_money field.

  • fields_to_clear removes the percentage_requested field.

The updated invoice is shown:

{
  "invoice": {
    "id": "lsBlUr0vkDIu_mAexample",
    "version": 1,
    "location_id": "S8GWD5example",
    "order_id": "8tXvK5qwjkEPbeLixWaKSxexample",
    "payment_requests": [
      {
        "uid": "32d69642-1614-4d84-ae4a-75d51example",
        "request_type": "DEPOSIT",
        "due_date": "2020-06-22",
        "fixed_amount_requested_money": {
          "amount": 100,
          "currency": "USD"
        },
        "computed_amount_money": {
          "amount": 100,
          "currency": "USD"
        },
        "total_completed_amount_money": {
          "amount": 0,
          "currency": "USD"
        },
        "automatic_payment_source": "NONE"
      },
      {
        "uid": "622a0315-e640-4a7a-9763-87461example",
        "request_type": "BALANCE",
        "due_date": "2020-09-01",
        "computed_amount_money": {
          "amount": 400,
          "currency": "USD"
        },
        "total_completed_amount_money": {
          "amount": 0,
          "currency": "USD"
        },
        "automatic_payment_source": "NONE"
      }
    ],
    ...
}

Example 5: Update custom fields Permalink Get a link to this section

Unlike other invoice fields, the Invoices API does not support using sparse updates to add or change custom fields. To make these changes, you must provide the complete custom_fields list in the update request. For example, consider an invoice that includes the following custom fields:

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

Note

Custom fields are supported only with an Invoices Plus subscription.

If you want to change the label from "Rules" to "Terms and Conditions", the invoice object in the request must include complete definitions for both custom fields. For example:

Update Invoice
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11
  • 12
  • 13
  • 14
  • 15
  • 16
  • 17
  • 18
  • 19
  • 20
  • 21
  • 22
  • 23
curl https://connect.squareupsandbox.com/v2/invoices/{invoice_id} \
  -X PUT \
  -H 'Square-Version: 2021-11-17' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{
    "idempotency_key": "{UNIQUE_KEY}",
    "invoice": {
      "version": 0,
      "custom_fields": [
        {
          "label": "Terms and Conditions",
          "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"
        }
      ]
    }
  }'

Omitting a custom field object or field from the request removes the object or field, or returns an error if the field is required. However, you can use the fields_to_clear field if you want to remove all custom fields from the invoice. For example:

Update Invoice
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11
  • 12
  • 13
  • 14
curl https://connect.squareupsandbox.com/v2/invoices/{invoice_id} \
  -X PUT \
  -H 'Square-Version: 2021-11-17' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{
    "idempotency_key": "{UNIQUE_KEY}",
    "invoice": {
      "version": 0
    },
    "fields_to_clear": [
      "custom_fields"
    ]
  }'

Cancel an invoice Permalink Get a link to this section

You call CancelInvoice to cancel a published invoice. When you cancel an invoice, Square does the following:

  • Sends a notification to the customer, depending on the delivery_method setting:

    • For EMAIL, Square sends an email notification.

    • For SMS, Square sends a text message.

    • For SHARE_MANUALLY, Square does not notify the customer.

  • Sets the status of the invoice to CANCELED.

  • Sets the state of the associated order to CANCELED.

  • Stops any automatic scheduled actions, such as emailing reminders or charging a card on file. Sellers cannot collect payments for a canceled invoice.

The following is an example CancelInvoice request. You must provide the invoice ID and current version for all CancelInvoice requests. You can call ListInvoices to retrieve the ID and version or call GetInvoice if you have the ID but need to retrieve the version.

Cancel Invoice
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
curl https://connect.squareupsandbox.com/v2/invoices/{invoice_id}/cancel \
  -X POST \
  -H 'Square-Version: 2021-11-17' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{
    "version": 1
  }'

The canceled invoice is returned in the response, as shown in the following example excerpt:

{
  "invoice": {
    "id": "gt2zv1z6mnUm1V7example",
    "version": 2,
    "location_id": "S8GWD5example",
    "order_id": "AdSjVqPCzOAQqvTnzy46VLexample",
    ...
    "status": "CANCELED",
    ...
  }
}

You cannot cancel invoices in the DRAFT state or in the PAID, REFUNDED, CANCELED, or FAILED terminal state. Canceled invoices remain accessible in the seller account. The GetInvoice, ListInvoices, and SearchInvoices requests return canceled invoices.

Delete an invoice Permalink Get a link to this section

You call DeleteInvoice to delete a draft invoice. You cannot delete published invoices, including those scheduled for processing at a later time. Deleted invoices are removed from the account and are not returned by GetInvoice, ListInvoices, or SearchInvoices requests.

When you delete a draft invoice, Square changes the state of the associated order to CANCELED.

The following is an example DeleteInvoice request. You must provide the invoice ID for all DeleteInvoice requests. You can call ListInvoices to retrieve the ID.

Delete Invoice
  • 1
  • 2
  • 3
  • 4
  • 5
curl https://connect.squareupsandbox.com/v2/invoices/{invoice_id} \
  -X DELETE \
  -H 'Square-Version: 2021-11-17' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json'

The following is an example response:

{}

Retrieve invoices Permalink Get a link to this section

Use the GetInvoice, ListInvoices, or SearchInvoices endpoint to retrieve invoices. You can retrieve a specific invoice, list invoices at a specific location, and search for invoices at a specific location for a specific customer.

Note

To view itemization and other order information associated with the invoice, call RetrieveOrder in the Orders API using the order_id in the invoice.

Get an invoice by ID Permalink Get a link to this section

Call GetInvoice if you know the invoice ID.

Get Invoice
  • 1
  • 2
  • 3
  • 4
curl https://connect.squareupsandbox.com/v2/invoices/{invoice_id} \
  -H 'Square-Version: 2021-11-17' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json'

List invoices Permalink Get a link to this section

Call ListInvoices to retrieve invoices at a specific location. The following example uses the limit to specify a maximum page size of three results. The default page size is 100.

List Invoices
  • 1
  • 2
  • 3
  • 4
curl https://connect.squareupsandbox.com/v2/invoices?location_id=S8GWD5example&limit=3 \
  -H 'Square-Version: 2021-11-17' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json'

The following is an excerpt of an example paged response:

{
  "invoices": [
    {
      "id": "avWaZewQ42Np4PCexample",
      ...
    },
    {
      "id": "7OXWh6-VEakBWtUexample",
      ...
    },
    {
      "id": "VnxeTa-xrHPNz0Aexample",
      ...
    }
  ],
  "cursor": "PNEhVUKHBuTOuRIZoUcX5VQexample"
}

When a response is truncated, the response includes a cursor to use in the next ListInvoices call. You add the cursor query parameter in the request as shown:

List Invoices
  • 1
  • 2
  • 3
  • 4
curl https://connect.squareupsandbox.com/v2/invoices?location_id=S8GWD5example&limit=3&cursor=PNEhVUKHBuTOuRIZoUcX5VQexample \
  -H 'Square-Version: 2021-11-17' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json'

Search invoices Permalink Get a link to this section

Call SearchInvoices to retrieve invoices that match a specific query. You must provide a location ID, and you can optionally include a customer ID if you want to retrieve invoices for a specific customer at the specified location.

The following example request filters by a specific customer and location. In the current implementation, the SearchInvoices endpoint supports only a single customer ID and a single location ID in the filter.

Search Invoices
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11
  • 12
  • 13
  • 14
  • 15
  • 16
  • 17
curl https://connect.squareupsandbox.com/v2/invoices/search \
  -X POST \
  -H 'Square-Version: 2021-11-17' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{
    "query": {
      "filter": {
        "location_ids": [
          "S8GWD5example"
        ],
        "customer_ids": [
          "HXJKX5BBKGWX34XEMS2example"
        ]
      }
    }
  }'

The following is an excerpt of an example response:

{
  "invoices": [
    {
      "id": "UcPT3fgiZi8lbX3example",
      ...
    },
    {
      "id": "BSW5ck83F7JoDqIexample",
      ...
    },
    ...
  ]
}

The following example request filters by a specific customer and location, and also sorts the results in order from oldest to newest:

Search Invoices
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11
  • 12
  • 13
  • 14
  • 15
  • 16
  • 17
  • 18
  • 19
  • 20
  • 21
curl https://connect.squareupsandbox.com/v2/invoices/search \
  -X POST \
  -H 'Square-Version: 2021-11-17' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{
    "query": {
      "filter": {
        "location_ids": [
          "S8GWD5example"
        ],
        "customer_ids": [
          "HXJKX5BBKGWX34XEMS2example"
        ]
      }
    },
    "sort": {
      "field": "INVOICE_SORT_DATE",
      "order": "ASC"
    }
  }'

The sort field INVOICE_SORT_DATE works as follows:

  • If the invoice is a draft, it uses the invoice created_at date.

  • If the invoice is scheduled for publication, it uses the scheduled_at date.

  • If the invoice is published, it uses the invoice publication date.

Pay an invoice Permalink Get a link to this section

Square APIs cannot be used to pay an invoice (or the associated order) or to manage payment status. Square manages all payment flows except when customers remit payment directly to sellers. In this case, sellers can record the direct payment using the Seller Dashboard, POS application, or Invoices application. Square then updates the status and payment amounts for the invoice and order accordingly.

After an invoice is published, Square generates and hosts a web page where the customer can pay the invoice. Square also adds the public_url field containing the page URL to the invoice object at this time.

Square updates the invoice page for each invoice payment request, according to the payment schedule and any prior payments. In addition, if the invoice is configured for automatic payments, Square charges the specified card on file or initiates a bank transfer on the payment due date.

Although Square APIs cannot be used to pay an invoice, you can retrieve the corresponding Payment object after a payment is made. To do so, call ListPayments or GetPayment using the ID of the tender that represents the payment in the associated order. Payments also appear on the Transactions page of the Seller Dashboard.

After a payment is made, Square sets the invoice status to PAID, PAYMENT_PENDING, or PARTIALLY_PAID and sets the total_completed_amount_money of the payment request to the amount paid. Square also adds payment information to the tenders field of the associated order and sets the order state to COMPLETED when the order is fully paid.

Refund an invoice Permalink Get a link to this section

You can call the RefundPayment endpoint in the Refunds API to refund invoice payments.

The invoice status must be PAID, CANCELED, or FAILED to refund a payment. Invoices with a status of PARTIALLY_PAID must be canceled using CancelInvoice before they can be refunded.

Refunding an invoice payment Permalink Get a link to this section

To refund an invoice payment, you need the ID of the tender that was recorded for the payment on the associated order. An order can have multiple tenders. You must make a separate call to RefundPayment for each tender that you want to refund.

  1. Get the order ID from the invoice. To retrieve the invoice, call GetInvoice if you have the invoice ID or call ListInvoices or SearchInvoices if you do not have the ID. The following example request calls GetInvoice:

    Get Invoice
    • 1
    • 2
    • 3
    • 4
    curl https://connect.squareupsandbox.com/v2/invoices/{invoice_id} \
      -H 'Square-Version: 2021-11-17' \
      -H 'Authorization: Bearer {ACCESS_TOKEN}' \
      -H 'Content-Type: application/json'

    Copy the order_id from the response.

  2. Get the tender ID from the order. To retrieve the order, call RetrieveOrder in the Orders API and provide the order ID.

    Retrieve Order
    • 1
    • 2
    • 3
    • 4
    curl https://connect.squareupsandbox.com/v2/orders/{order_id} \
      -H 'Square-Version: 2021-11-17' \
      -H 'Authorization: Bearer {ACCESS_TOKEN}' \
      -H 'Content-Type: application/json'

    The following excerpt of an example response shows the tenders field:

     {
       "order": {
         "id": "DIxOlEityYPJtcuvKTVKT1example",
         "location_id": "P3CCK6example",
         ...
         "tenders": [
           {
             "id": "EnZdNAlWCmfh6Mt5FMN3example",
             "location_id": "P3CCK6example",
             "transaction_id": "lgwOlEityYPJtcuvKTVKT1example",
             "created_at": "2020-08-06T02:47:36.293Z",
             "amount_money": {
               "amount": 1000,
               "currency": "USD"
             },
             "type": "CARD",
             "card_details": {
               "status": "CAPTURED",
               "card": {
                 "card_brand": "AMERICAN_EXPRESS",
                 "last_4": "6550"
               },
               "entry_method": "ON_FILE"
             },
             "tip_money": {
               "amount": 0,
               "currency": "USD"
             }
           }
         ],
         ...
       }
     }
    

    Copy the id of the tender. This is the payment ID that you use to refund the payment. Also, note the amount paid for the tender, which is the maximum amount that you can refund for the payment.

  3. Refund the payment. Call RefundPayment in the Refunds API and provide the payment ID and the amount to refund.

    Refund Payment
    • 1
    • 2
    • 3
    • 4
    • 5
    • 6
    • 7
    • 8
    • 9
    • 10
    • 11
    • 12
    • 13
    • 14
    curl https://connect.squareupsandbox.com/v2/refunds \
      -X POST \
      -H 'Square-Version: 2021-11-17' \
      -H 'Authorization: Bearer {ACCESS_TOKEN}' \
      -H 'Content-Type: application/json' \
      -d '{
        "idempotency_key": "{UNIQUE_KEY}",
        "payment_id": "EnZdNAlWCmfh6Mt5FMN3example",
        "amount_money": {
          "amount": 1000,
          "currency": "USD"
        },
        "reason": "Optional reason for the refund."
      }'

    The following is an example response:

    {
      "refund": {
        "id": "EnZdNAlWCmfh6Mt5FMN3example_qOfJKjOzCyU3fZexample",
        "status": "COMPLETED",
        "amount_money": {
          "amount": 1000,
          "currency": "USD"
        },
        "payment_id": "EnZdNAlWCmfh6Mt5FMN3example",
        "order_id": "AqBDyr9oJqj4oDHj8example",
        "created_at": "2020-08-16T18:28:33Z",
        "reason": "Optional reason for the refund."
      }
    }
    

After a refund is processed, the invoice status changes to REFUNDED if the entire amount paid for the invoice is refunded or PARTIALLY_REFUNDED if only a portion of the payment is refunded. The original order remains unchanged and set to the COMPLETED status.

Note

Sellers can also refund invoice payments using the Square Seller Dashboard or the mobile applications (Square Point of Sale and Square Invoices).

Requirements and limitations Permalink Get a link to this section

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

Requirements Permalink Get a link to this section

  • OAuth permissions. Applications that use OAuth and the Invoices API require the following OAuth permissions. For more information, see OAuth Overview.

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

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

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

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

Limitations Permalink Get a link to this section

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

    • Canceling or deleting an invoice also cancels the associated order (sets the order status to CANCELED). Orders that are associated with an invoice cannot be canceled using the Orders API.

    • Payment for the order must be made on the invoice. You cannot use Square APIs such as PayOrder, CreatePayment, or Charge to process a payment for an order that is associated with an invoice. After the invoice is paid in full, the state field of the order is set to COMPLETED.

    • You cannot update fields (such as line items, taxes, and discounts) that change the amount of an order that is associated with an invoice. To update these order fields, you must cancel the invoice, which also cancels the order. You can then create a new order and a new invoice. Order fields that do not change the order amount can be updated.

    • Invoices created using the Seller Dashboard, POS application, or Invoices application do not include the order_id field unless 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.

    For more information about order-related requirements and limitations, see Create and publish an invoice.

International availability and considerations Permalink Get a link to this section

The Invoices API is supported in the following countries: Australia, Canada, Ireland, Japan, 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 Ireland 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":"doe@email.com",
          "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.

    Note

    The tax_ids implementation in the Customers API supports seller accounts in France. However, the Invoices API implementation currently does not include support for France.

Premium features available with Invoices Plus Permalink Get a link to this section

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 first-party invoice 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 type INSTALLMENT.

    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 subscription status, the Invoices API returns the complete invoice in applicable responses and webhook notifications, including fields related to premium features.

Testing Invoices Plus features in the Sandbox Permalink Get a link to this section

To test premium features and error handling in the Sandbox environment, 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 make sure 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 in the dashboard, 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 Sandbox environment, see Test in the Sandbox.

Webhooks Permalink Get a link to this section

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

All invoice event notifications include the invoice ID and the invoice object (except invoice.deleted), as shown in the following excerpt of an example invoice.created notification:

{
  "merchant_id": "031FEVexample",
  "location_id": "S8GWD5example",
  "type": "invoice.created",
  "event_id": "b407d383-c47f-4eeb-6785-c235Aexample",
  "created_at": "2020-10-25T23:01:51Z",
  "data": {
    "type": "invoice",
    "id": "inv:0-ChCSnXxUPe6t4laN_uCKexample",
    "object": {
      "invoice": {
        // invoice fields
      }
    }
  }
}  

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

Migration notes Permalink Get a link to this section

Premium features require an Invoices Plus subscription Permalink Get a link to this section

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 which 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 type INSTALLMENT.

The Invoices API returns one of the following error codes if the invoice contains an unsupported premium feature. The detail message indicates whether the unsupported feature is custom fields or installment payments. For example, the following errors are returned for a request that contains unsupported installment payments:

  • Square version 2021-08-18 and later: 403 MERCHANT_SUBSCRIPTION_NOT_FOUND

    {
      "errors": [
        {
          "category": "MERCHANT_SUBSCRIPTION_ERROR",
          "code": "MERCHANT_SUBSCRIPTION_NOT_FOUND",
          "detail": "Payment request type INSTALLMENT requires an Invoices Plus subscription."
        }
      ]
    }
    
  • Square version 2021-07-21 and earlier: 400 BAD REQUEST

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

New Invoice.accepted_payment_method Permalink Get a link to this section

The Invoice.accepted_payment_method field represents the payment methods that customers can use to make a payment on the Square-hosted invoice 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 first-party Square products. The default Payment method setting cannot be accessed by the Invoices API.

Deprecated InvoicePaymentRequest.request_method Permalink Get a link to this section

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.