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

Overview

Managing invoices can be hard, but integrating the Invoices API into your application flow helps to simplify the experience 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 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 applications. 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 applications because they do not include an order ID, which is required by the CreateInvoice endpoint.
- Invoices created from first-party applications do not include an order_id field unless a payment has been made on the invoice.

You can subscribe to webhooks to receive notifications about invoice events.

How it works

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

Create an order by calling CreateOrder in the Orders API. Only orders created with the Orders API are supported.

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.
If you are configuring automatic payments from a card on file, you must specify the card_id for each payment request. You can get card IDs from the cards field of the customer profile.

Create a draft invoice by calling CreateInvoice in the Invoices API.

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.

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.

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.

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

Invoice object

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

{
   "invoice": {
      "id": "s0XFqYEBhBWDYERexample",
      "version": 0,
      "location_id": "S8GWD5example",
      "order_id": "4NuiKTlFzWmbLnRz9YfoL8example",
      "payment_requests": [
         {
            "uid": "83c2716e-f859-4d75-a015-77489example",   
            "request_type": "BALANCE",  
            "due_date": "2020-05-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": "2020-05-26T15:40:34Z",
      "updated_at": "2020-05-26T15:40:34Z",
      "primary_recipient": {
         "customer_id": "HXJKX5BBKGWX34XEMS2example",
         "given_name": "John",
         "family_name":"Doe",
         "email_address":"doe@email.com"
      },
      "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"
   }
}

The following fields represent several key invoice settings:

order_id is the ID of the corresponding order that was created using the Orders API. You can create one invoice for each order:
- The invoice location must match the order location.
- The sum of the computed_amount_money amounts in all invoice payment requests equals the total_money of the order.

payment_requests is the payment schedule for the invoice. This example contains one payment request for the full order amount, due by the specified date.

computed_amount_money is the amount due for the payment request, and total_completed_amount_money is the amount the customer has paid for the payment request. Square calculates these values and adds them to the invoice.

delivery_method is the method Square uses to send invoices, reminders, or receipts to the customer.

primary_recipient is the customer responsible for the invoice. You only specify the customer ID when creating an invoice. The rest of the information is taken from the customer profile in the seller's Customer Directory. Note that the person receiving the invoice can be different from the person who placed the order.

status indicates that the invoice is a 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_number is a 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.

version is 0 because it is the first version of the invoice. Square increments this value each time the invoice changes. You must provide the current version of the invoice for PublishInvoice, UpdateInvoice, andCancelInvoice requests. You cannot perform actions on previous versions of the invoice.

custom_fields can contain up to two customer-facing, seller-defined custom fields.

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

Payment requests

The payment_requests field defines the payment schedule for an invoice, which includes payment amounts, due dates, and other related settings. The example invoice 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.

An invoice can contain up to 13 payment requests, with a maximum of 12 installments. You can specify deposit or installment payments by percentage or as a fixed amount.

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

Payment scenario	request_type combination
One payment in full	1 BALANCE
A deposit with the balance due later	1 DEPOSIT and 1 BALANCE
A deposit with remaining payments in installments	1 DEPOSIT and 2–12 INSTALLMENT
All payments in installments	2–12 INSTALLMENT

Example payment requests

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

Invoice with one payment request. Suppose you want to request one payment in full. An example payment_requests object is shown:
```
...
"payment_requests": [
   {
      "request_type":"BALANCE",
      "due_date":"2030-02-01"
   }
]
...
```
The single BALANCE payment request represents the total amount of the order.

Invoice with two payment requests (a deposit followed by the balance request). Suppose you want to request a 50% deposit and the remaining 50% balance at a later date. An example payment_requests object is shown:
```
...
"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.

Invoice with three payment requests (a deposit followed by two installments). Suppose you want to request a 50% deposit and the balance paid in two equal installments. An example payment_requests object shows the payment schedule:

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

Note that the 50% in the installments refers to the amount after the deposit is paid. Suppose the order is for $100. This invoice then requests a $50 deposit, followed by two installments of $25 each. Instead of percentages, you can specify exact amounts in payment_requests:

...
"payment_requests": [
   {
      "request_type":"DEPOSIT",
      "due_date":"2020-07-30",
      "fixed_amount_requested_money":{
         "amount":5000,
         "currency":"USD"
      }
   },
   {
      "request_type":"INSTALLMENT",
      "fixed_amount_requested_money":{
         "amount":2500,
         "currency":"USD"
      },
      "due_date":"2020-08-30"
   },
   {
      "request_type":"INSTALLMENT",
      "fixed_amount_requested_money":{
         "amount":2500,
         "currency":"USD"
      },
      "due_date":"2020-09-30"
   }
]
...

The following requirements and considerations apply when specifying a payment schedule:

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

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

For DEPOSIT or INSTALLMENT payment requests, you can specify a fixed amount or a percentage-based amount. To specify a fixed amount, set the fixed_amount_requested_money field. 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.

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

Value	Description
NONE	No automatic payment is configured. This is the default value.
CARD_ON_FILE	Directs Square to charge the customer's card on file, which is specified by the `card_id` field. You can call ListCustomers or RetrieveCustomer and get the ID of the target card from the `cards` field in the response.
BANK_ON_FILE	Directs 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 applications.

Automatic payments require that the delivery_method of the invoice is set to EMAIL. If an automatic payment fails, Square sends an invoice to the customer.

The minimum amount of a single payment request is $1.00.

Custom fields

You can use the Invoices API to add up to two custom fields to an invoice, each of which can be placed above or below the line items on the invoice. This enables sellers to customize their invoices by adding information such as their terms of service or a 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.

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.

Invoice with two custom fields

The following CreateInvoice request creates the invoice shown in 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

curl https://connect.squareupsandbox.com/v2/invoices \
  -X POST \
  -H 'Square-Version: 2021-02-26' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{
    "idempotency_key": "{UNIQUE_KEY}",
    "invoice": {
      "order_id": "AdSjVqPCzOAQqvTnzy46VLexample",
      "location_id": "S8GWD5example",
      "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"
        }
      ],
      "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.

Manage invoices

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

Create and publish an invoice

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 cannot be associated with another invoice.
- The order status must be OPEN.
The location_id of the invoice.
- The location_id of the invoice must match the location_id of the order.
- The location status must be ACTIVE.
The customer_id of the invoice recipient. The customer who creates the order and who receives the invoice can be different.
- The customer profile must exist in the seller's Customer Directory. You can call ListCustomers 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.
  The Invoices API does update the customer_id of the recipient if the customer profile is merged.
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 based on the total_money in the payment request schedule. For more information, see Payment requests.

Step 1: Create a draft invoice

You call CreateInvoice to create a draft invoice as shown:

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

curl https://connect.squareupsandbox.com/v2/invoices \
  -X POST \
  -H 'Square-Version: 2021-02-26' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{
    "idempotency_key": "{UNIQUE_KEY}",
    "invoice": {
      "order_id": "AdSjVqPCzOAQqvTnzy46VLexample",
      "location_id": "S8GWD5example",
      "primary_recipient": {
        "customer_id": "DJREAYPRBMSSFAB4TGAexample"
      },
      "delivery_method": "EMAIL",
      "payment_requests": [
        {
          "request_type": "BALANCE",
          "due_date": "2021-06-29"
        }
      ],
      "title": "My Invoice Title"
    }
  }'

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 a reminder 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 invoice is paid, Square does not send a 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

curl https://connect.squareupsandbox.com/v2/invoices \
  -X POST \
  -H 'Square-Version: 2021-02-26' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{
    "idempotency_key": "{UNIQUE_KEY}",
    "invoice": {
      "order_id": "AdSjVqPCzOAQqvTnzy46VLexample",
      "location_id": "S8GWD5example",
      "primary_recipient": {
        "customer_id": "DJREAYPRBMSSFAB4TGAexample"
      },
      "delivery_method": "EMAIL",
      "payment_requests": [
        {
          "request_type": "BALANCE",
          "due_date": "2021-06-29",
          "reminders": [
            {
              "relative_scheduled_days": -1,
              "message": "Your payment is due tomorrow."
            }
          ]
        }
      ],
      "title": "My Invoice Title"
    }
  }'

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

Step 2: Publish the invoice

You 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

curl https://connect.squareupsandbox.com/v2/invoices/{invoice_id}/publish \
  -X POST \
  -H 'Square-Version: 2021-02-26' \
  -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": "gt2zv1z6mnUm1V7example",
    "version": 1,
    "location_id": "S8GWD5example",
    "order_id": "AdSjVqPCzOAQqvTnzy46VLexample",
    "payment_requests": [
      {
        "uid": "ccc0fc9b-c2a5-42a9-836d-92d01example",
        "request_type": "BALANCE",
        "due_date": "2021-06-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",
    "public_url": "https://squareupsandbox.com/pay-invoice/gt2zv1z6mnUm1V7example",
    "status": "UNPAID",
    "timezone": "Etc/UTC",
    "created_at": "2021-05-30T19:01:32Z",
    "updated_at": "2021-05-30T19:05:01Z",
    "primary_recipient": {
      "customer_id": "DJREAYPRBMSSFAB4TGAexample",
      "given_name": "John",
      "family_name": "Doe",
      "email_address": "doe@email.com"
    },
    "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

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.
For each payment request, do the following:
- due_date. Specify the date the payment is due.
- automatic_payment_source. Keep the default value of NONE.
- reminders, request_type, and other payment fields. Configure as needed (see Payment requests).
  For invoices with multiple payment requests, Square sends invoices and reminders according to the payment schedule.

Option 2: Automatically charge a 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.
For each payment request, do the following:
- due_date. Specify the date that the payment is due.
- automatic_payment_source. Specify CARD_ON_FILE.
- card_id. Set to the ID of the card on file to charge. If you have the customer ID and need the card ID, call RetrieveCustomer. The IDs of cards on file are stored in the cards field in the response.
- reminders, request_type, and other payment fields. Configure as needed (see Payment requests).
  For invoices with multiple payment requests, Square sends invoices and reminders according to the payment schedule.

You cannot configure automatic bank transfers from the Invoices API. The BANK_ON_FILE automatic payment method applies only to recurring invoices created in first-party Square applications.

Option 3: Square takes no action. In this case, the seller or the application developer follows up with the customer.

delivery_method. Specify SHARE_MANUALLY.
For each payment request, do the following:
- due_date. Specify the date that the payment is due.
- automatic_payment_source. Keep the default value of NONE.
- reminders, request_type, and other payment fields. Configure as needed. For more information, see Payment requests.

Update an invoice

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.

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.

If you update a published invoice, Square notifies the seller and the customer that the invoice was updated.

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

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-02-26' \
  -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

Consider the following draft invoice, which requests a deposit payment and a balance payment due at a later date.

{
   "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"
      },
      "delivery_method":"EMAIL"
   }
}

Suppose you want to remove the deposit payment request from the preceding invoice. The request body in the following request includes 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

curl https://connect.squareupsandbox.com/v2/invoices/bn9CXYfwPZh6Ednexample \
  -X PUT \
  -H 'Square-Version: 2021-02-26' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{
    "idempotency_key": "{UNIQUE_KEY}",
    "invoice": {
      "version": 0
    },
    "fields_to_clear": [
      "payment_requests[a17ee758-fb36-4226-a535-95916example]"
    ]
  }'

The updated draft invoice is shown, which now requests only one payment in full (no deposit):

{
   "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"
      },
      "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-02-26' \
  -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

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-02-26' \
  -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

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-02-26' \
  -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

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

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-02-26' \
  -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-02-26' \
  -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

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

Sends an email notification to 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

curl https://connect.squareupsandbox.com/v2/invoices/{invoice_id}/cancel \
  -X POST \
  -H 'Square-Version: 2021-02-26' \
  -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 states. Canceled invoices remain accessible in the seller account. The GetInvoice, ListInvoices, and SearchInvoices requests return canceled invoices.

Delete an invoice

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

curl https://connect.squareupsandbox.com/v2/invoices/{invoice_id} \
  -X DELETE \
  -H 'Square-Version: 2021-02-26' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json'

The following is an example response:

{}

Retrieve an invoice

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

Get an invoice by ID

Call GetInvoice if you know the invoice ID.

Get Invoice

curl https://connect.squareupsandbox.com/v2/invoices/{invoice_id} \
  -H 'Square-Version: 2021-02-26' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json'

List invoices

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

List Invoices

curl https://connect.squareupsandbox.com/v2/invoices?location_id=S8GWD5example&limit=3 \
  -H 'Square-Version: 2021-02-26' \
  -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

curl https://connect.squareupsandbox.com/v2/invoices?location_id=S8GWD5example&limit=3&cursor=PNEhVUKHBuTOuRIZoUcX5VQexample \
  -H 'Square-Version: 2021-02-26' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json'

Search invoices

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-02-26' \
  -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-02-26' \
  -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.

Refund an invoice

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. After a refund is processed, the status changes to REFUNDED if the entire amount paid for the invoice is refunded or changes to PARTIALLY_REFUNDED if only a portion of the payment is refunded. Invoices with a status of PARTIALLY_PAID must be canceled using CancelInvoice before they can be refunded.

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

Requirements

The Invoices API requires the following OAuth permissions:
- INVOICES_READ to use the following endpoints:
  - GetInvoice
  - ListInvoices
  - SearchInvoices
- INVOICES_WRITE and ORDERS_WRITE to use the following endpoints:
  - CreateInvoice
  - UpdateInvoice
  - DeleteInvoice
  - CancelInvoice
  - PublishInvoice
- CUSTOMERS_READ and PAYMENTS_WRITE to charge cards on file.
When creating an invoice, the location that you specify must have an ACTIVE status.
You can send an invoice to a customer only if the customer has a profile in the seller's Customer Directory. For more information about creating customer profiles, see Manage Customers and Integrate with Other Services.
The minimum amount for an invoice payment request is $1.00.

Limitations

An order associated with an invoice has the following restrictions:
- Canceling an invoice cancels the order. If you cancel an invoice, the corresponding order is also canceled.
- Paying for the order. You can only pay for the order by paying the invoice. You cannot use other Square APIs (such as PayOrder, CreatePayment, and Charge) to process the payment for the order. After the invoice is paid in full, the state field of the order is set to COMPLETED.
  
  Note
  
  After customers pay invoices, you can use the ListPayments and GetPayment endpoints in the Payments API to retrieve the corresponding Payment objects. The payments also appear on the Transactions page of the Seller Dashboard. You can use the Refunds API to refund a payment.
- Updating an order. You cannot update order fields (such as line items, taxes, and discounts) that change the order amount. To update these order fields, you must cancel the invoice, which also cancels the order (sets the order status to CANCELED). You then create a new order and a new invoice. You can update order fields that do not change the order amount.
When you create an invoice using the Invoices API, the order ID is required. However, an invoice created using the Seller Dashboard, the Square Point of Sale application, or the Square Invoices application is created without an order ID. When you retrieve such an invoice using the Invoices API, the invoice does not include an order_id field unless a payment has been made on the invoice.

The Invoices API does not support some of the features available in the Square Seller Dashboard, the Square Point of Sale application, and the Square Invoices application. For example:
- Color and logo customization for your email invoices and customer payment page is not supported.
- Recurring Invoice Series are not supported.
- Estimates are not supported.
- Attaching a file to an invoice is not supported. The Invoices API preserves any existing attachments on an invoice but the API does not support accessing and modifying invoice attachments.
- Adding or viewing a shipping address is not supported. You cannot add a shipping address to an invoice that you create with the Invoices API. In addition, the shipping address is not included in invoices that you retrieve with the Invoices API.

Webhooks

The Invoices API supports webhook notifications. For the list of invoice events you can subscribe to, see Subscribe to Events.

Migration notes

Deprecated InvoicePaymentRequest.request_method

The InvoicePaymentRequest.request_method field and corresponding InvoiceRequestMethod enum are deprecated. Request method options are now represented by the following fields:

Invoice.delivery_method specifies how Square should send invoices, reminders, and receipts to the customer. For valid values, see InvoiceDeliveryMethod.
InvoicePaymentRequest.automatic_payment_source specifies the payment method for an automatic payment. For valid values, see InvoiceAutomaticPaymentSource.

Deprecated in version: 2021-01-21
Retired in version: TBD

The Invoices API continues to accept request_method in create and update requests until the field is retired, but you should use delivery_method and automatic_payment_source when possible. However, starting in version 2021-01-21, request_method is not included in returned Invoice objects. The API migrates request_method options in responses as follows:

request_method	delivery_method	automatic_payment_source
EMAIL	EMAIL	NONE
CHARGE_CARD_ON_FILE	EMAIL	CARD_ON_FILE
CHARGE_BANK_ON_FILE	EMAIL	BANK_ON_FILE
SHARE_MANUALLY	SHARE_MANUALLY	NONE

Was this page helpful?

Still haven't found what you are looking for?

Contact Developer Support, or ask for help in the Developer Forums.

Manage Invoices Using the Invoices API

On this page

Overview Permalink Get a link to this section

How it works Permalink Get a link to this section

Note

Invoice object Permalink Get a link to this section

Payment requests Permalink Get a link to this section

Example payment requests Permalink Get a link to this section

Custom fields Permalink Get a link to this section

Manage invoices Permalink Get a link to this section

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

Note

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

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

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

Note

Update an invoice Permalink Get a link to this section

Note

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

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

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

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

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

Cancel an invoice Permalink Get a link to this section

Delete an invoice Permalink Get a link to this section

Retrieve an invoice Permalink Get a link to this section

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

List invoices Permalink Get a link to this section

Search invoices Permalink Get a link to this section

Refund an invoice Permalink Get a link to this section

Requirements and limitations Permalink Get a link to this section

Requirements Permalink Get a link to this section

Limitations Permalink Get a link to this section

Note

Webhooks Permalink Get a link to this section

Migration notes Permalink Get a link to this section

Still haven't found what you are looking for?

Overview

How it works

Invoice object

Payment requests

Example payment requests

Custom fields

Manage invoices

Create and publish an invoice

Step 1: Create a draft invoice

Step 2: Publish the invoice

Configuring how Square processes an invoice

Update an invoice

Example 1: Update an invoice number and title

Example 2: Update payment requests by removing the deposit request

Example 3: Remove and add payment requests

Example 4: Replace payment request percentages with exact amounts

Example 5: Update custom fields

Cancel an invoice

Delete an invoice

Retrieve an invoice

Get an invoice by ID

List invoices

Search invoices

Refund an invoice

Requirements and limitations

Requirements

Limitations

Webhooks

Migration notes