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

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

• Square generates and hosts a web page where customers can easily pay the invoice. After each payment, Square emails 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:

After you publish the invoice, Square handles the remaining workflow based on the invoice settings. For example, you can direct Square to email the invoice or charge a customer's card on file. You can also direct Square to take no action if you or the seller want to follow up with the customer directly. Square takes no action on draft invoices.

Square manages payments that are charged to a card on file or initiated by customers from the invoice page. Square also updates the invoice payment status and sends email reminders and receipts.

No other direct action is required from the developer, unless you need to update the invoice or cancel the invoice.

The following sections explain the Invoices API.

Invoice object

The core of the Square Invoices API is the Invoice type. Consider the following sample invoice requesting a single payment of $12 by the due date from a customer:

{
   "invoice":{
      "id":"s0XFqYEBhBWDYERexample",
      "version":0,
      "location_id":"S8GWD5R9QB376",
      "order_id":"4NuiKTlFzWmbLnRz9YfoL8example",
      "payment_requests":[
         {
            "uid":"83c2716e-f859-4d75-a015-77489example",
            "request_method":"EMAIL",   
            "request_type":"BALANCE",  
            "due_date":"2020-05-27",
            "computed_amount_money":{
               "amount":1200,
               "currency":"USD"
            }
         }
      ],
      "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":"HXJKX5BBKGWX34XEMS2MWKAMY4",
         "given_name":"John",
         "family_name":"Doe",
         "email_address":"doe@email.com"
      }
   }
}

Some highlights of the invoice object are:

• You create one invoice for each order:

  • The invoice location must match the order location.

  • The invoice amount sum of computed_amount_money in all payment requests equals the total_money of the order.

• payment_requests describes a payment schedule. This example shows one payment request for the full order amount.

• 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 field each time the invoice changes. You must provide the current version of the invoice for PublishInvoice, UpdateInvoice, CancelInvoice, and DeleteInvoice requests. You cannot perform actions on previous versions of the invoice.

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

Payment requests

In the preceding example invoice, payment_requests specifies one payment request (see InvoicePaymentRequest) for the balance amount (the total_money as specified in the order). You can optionally split the invoice into multiple payment requests. For example, you can:

• Request a deposit and request the balance payment at a later date.

• Request a deposit and request payments in installments.

• Request the payment in installments.

An invoice supports the following payment request combinations:

• 1 balance

• 1 deposit with 1 balance

• 2–12 installments

• 1 deposit with 2–12 installments

Each of these payment requests must specify the same request_method, which is how you want Square to process the payment request. Consider the following example invoices:

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

  Copy

  ...
  "payment_requests": [
     {
        "request_method":"EMAIL",
        "request_type":"DEPOSIT",
        "due_date":"2030-02-01",
        "percentage_requested":"50"
     },
     {
        "request_method":"EMAIL",
        "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:

  Copy

  ...
  "payment_requests": [
     {
        "request_method":"EMAIL",
        "request_type":"DEPOSIT",
        "due_date":"2030-02-01",
        "percentage_requested":"50"
     },
     {
        "request_method":"EMAIL",
        "request_type":"INSTALLMENT",
        "percentage_requested":"50",
        "due_date":"2030-03-01"
     },
     {
        "request_method":"EMAIL",
        "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:

  Copy

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

Note the following caveats when specifying a payment schedule:

• The sum of the amounts in payment_requests must equal the order amount, which is specified in the total_money field of the order.

• The request_method must be the same for all payments: email the invoice requesting the customer to pay (EMAIL), charge the customer's card on file (CHARGE_CARD_ON_FILE), or do nothing (SHARE_MANUALLY). In this case, the seller or the application developer processes the invoice.

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.

  • The customer profile must have a valid email address if the invoice request method is EMAIL or CHARGE_CARD_ON_FILE. Square uses this email address to send invoices to the customer.

You must also define 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:

curl https://connect.squareupsandbox.com/v2/invoices \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {{ACCESS_TOKEN}}' \
  -d '{
    "idempotency_key": "{{UNIQUE_KEY}}",
    "invoice": {
      "order_id": "{{ORDER_ID}}",
      "location_id": "{{LOCATION_ID}}",
      "primary_recipient": {
        "customer_id": "{{CUSTOMER_ID}}"
      },
      "payment_requests": [
        {
          "request_method": "EMAIL",
          "request_type": "BALANCE",
          "due_date": "{{DUE_DATE}}"
        }
      ],
      "title": "My Invoice Title"
    }
  }'

The request body provides the invoice details. The payment_requests field specifies one InvoicePaymentRequest for the balance amount (as determined by the specified order) due by the specified due date. In response, you get an invoice with status set to DRAFT. For an example, see Example Walkthrough: Create and Publish Invoices.

You can set a reminder on a payment request. The following CreateInvoice request sends a reminder to the customer one day before the due date. If the invoice is paid, Square does not send a reminder.

curl https://connect.squareupsandbox.com/v2/invoices \
  -H 'Authorization: Bearer {{ACCESS_TOKEN}}' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -d '{
    "idempotency_key":"{{UNIQUE_KEY}}",
    "invoice":{
      "order_id":"{{ORDER_ID}}",
      "location_id":"{{LOCATION_ID}}",
      "primary_recipient":{
        "customer_id":"{{CUSTOMER_ID}}"
      },
      "payment_requests":[
        {
          "request_method":"EMAIL",
          "request_type":"BALANCE",
          "due_date":"{{DUE_DATE}}",
          "reminders":[
            {
              "relative_scheduled_days":-1,
              "message":"Your invoice is due tomorrow"
            }
          ]
        }
      ],
      "title": "My Invoice Title"
    }
  }'

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.

curl https://connect.squareupsandbox.com/v2/invoices/{{INVOICE_ID}}/publish \
  -H 'Authorization: Bearer {{ACCESS_TOKEN}}' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -d '{
    "version": 0,
    "idempotency_key": "{{UNIQUE_KEY}}"
  }'

The following is an example response:

{
  "invoice": {
    "id": "gt2zv1z6mnUm1V7example",
    "version": 1,
    "location_id": "S8GWD5R9QB376",
    "order_id": "AdSjVqPCzOAQqvTnzy46VLexample",
    "payment_requests": [
      {
        "uid": "ccc0fc9b-c2a5-42a9-836d-92d01example",
        "request_method": "EMAIL",
        "request_type": "BALANCE",
        "due_date": "2020-06-01",
        "computed_amount_money": {
          "amount": 100,
          "currency": "USD"
        }
      }
    ],
    "invoice_number": "000028",
    "title": "My Invoice Title",
    "public_url": "https://squareupsandbox.com/pay-invoice/gt2zv1z6mnUm1V7example",
    "status": "UNPAID",
    "timezone": "Etc/UTC",
    "created_at": "2020-05-30T19:01:32Z",
    "updated_at": "2020-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"
    }
  }
}

After you publish the invoice, Square takes action based on the request_method specified for the payment request. The preceding example directs Square to email the invoice to the customer. Supported request methods are defined in the InvoiceRequestMethod enum.

By default, when you call PublishInvoice, Square processes the invoice immediately as follows:

• If the request_method is CHARGE_CARD_ON_FILE, Square charges the card on the due_date set for the payment request:

  • If the payment is due on the same day that the invoice is published, Square charges the card on file and emails a receipt to the customer.

  • If the payment is due at some future date, Square sends an email telling the customer the due date when the card will be charged. When the due date arrives, Square charges the card and emails a receipt to the customer.

• If the request_method is EMAIL, Square emails the invoice to the customer.

Instead of processing the invoice soon after it is published, you can optionally direct Square to process the invoice at some future date by adding the scheduled_at parameter in your CreateInvoice request. When the scheduled_at date arrives, Square processes the invoice:

• If the request_method is CHARGE_CARD_ON_FILE, Square charges the card on the due_date set for the payment request:

  • If the payment due_date is the same as the scheduled_at date (a date you tell Square to process the invoice), Square charges the card on file and emails a receipt to the customer.

  • If the payment due_date is some time in the future, Square sends an email telling the customer the due date when the card will be charged. When the due date arrives, Square charges the card and emails a receipt to the customer.

• If the request_method is EMAIL, Square emails the invoice to the customer.

None of the preceding applies if the request_method is SHARE_MANUALLY, which directs Square to take no action when the invoice is published. In this case, the seller processes the invoice.

Update an invoice

You call UpdateInvoice to update an invoice.

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. In addition, another payment cannot be initiated for an invoice in this state.

If you update a published invoice, Square republishes the invoice.

In an UpdateInvoice request, you can modify invoice fields, clear fields, or do both. In the request body, you provide one or both of the following:

• The invoice object with fields to update.

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

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:

curl https://connect.squareupsandbox.com/v2/invoices/{{INVOICE_ID}} \
 -X PUT \
 -H 'Authorization: Bearer {{ACCESS_TOKEN}}' \
 -H 'Content-Type: application/json' \
 -H 'Accept: application/json' \
 -d '{
   "idempotency_key":"{{UNIQUE_KEY}}",
   "invoice":{
      "version": 0,
      "title":"Updated Title",
      "invoice_number":"new-number-100"
   }
}'

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

Example 2: Update payment requests by removing a deposit request

Suppose you create a draft invoice with two payment requests: a deposit and 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_method":"CHARGE_CARD_ON_FILE",
            "request_type":"DEPOSIT",
            "due_date":"2020-06-11",
            "percentage_requested":"20",
            "card_id":"ccof:aD1D4q9aUXTkexample",
            "computed_amount_money":{
               "amount":100,
               "currency":"USD"
            },
            "total_completed_amount_money":{
               "amount":0,
               "currency":"USD"
            }
         },
         {
            "uid":"79e1d50d-6a35-40fc-bfd2-05913example",
            "request_method":"CHARGE_CARD_ON_FILE",
            "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"
            }
         }
      ],
      "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"
      }
   }
}

The following UpdateInvoice request removes the deposit request by adding payment_requests[a17ee758-fb36-4226-a535-9591664ef88f] to the fields_to_clear field in the request body as shown. The uid in the payment_requests identifies the specified payment request to remove.

curl https://connect.squareupsandbox.com/v2/invoices/{{INVOICE_ID}} \
 -H 'Authorization: Bearer {{ACCESS_TOKEN}}' \
 -H 'Content-Type: application/json' \
 -X PUT \
 -d '{
   "idempotency_key":"{{UNIQUE_KEY}}",
   "invoice":{
      "version": 0
   },
   "fields_to_clear":[
      "payment_requests[a17ee758-fb36-4226-a535-9591664ef88f]"
   ]
}'

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

{
   "invoice":{
      "id":"bn9CXYfwPZh6Ednexample",
      "version":1,
      "location_id":"S8GWD5R9QB376",
      "order_id":"81b7Ar7KPHmlXHs2qhjMc5example",
      "payment_requests":[
         {
            "uid":"79e1d50d-6a35-40fc-bfd2-05913example",
            "request_method":"CHARGE_CARD_ON_FILE",
            "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"
            }
         }
      ],
      "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"
      }
   }
}

Consider the following variation. Suppose you want to remove the deposit request and update due_date on the remaining balance payment request. In other words, you want to remove one payment request and update another. In this case, the UpdateInvoice request must include both invoice and fields_to_clear as shown:

curl https://connect.squareupsandbox.com/v2/invoices/{{INVOICE_ID}} \
 -H 'Authorization: Bearer {{ACCESS_TOKEN}}' \
 -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
 -X PUT \
 -d '{
   "idempotency_key":"{{UNIQUE_KEY}}",
   "invoice":{
      "version": 1,
      "payment_requests":[
         {
            "uid":"79e1d50d-6a35-40fc-bfd2-05913d774978",
            "due_date":"{{DUE_DATE}}",
         }
      ]
   },
   "fields_to_clear":[
      "payment_requests[a17ee758-fb36-4226-a535-9591664ef88f]"
   ]
}'

Both the invoice and fields_to_clear fields identify a specific payment request by providing the uid value.

Example 3: Update payment requests by removing and adding payment requests

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

curl https://connect.squareupsandbox.com/v2/invoices/{{INVOICE_ID}} \
 -H 'Authorization: Bearer {{ACCESS_TOKEN}}' \
 -H 'Content-Type: application/json' \
 -X PUT \
 -d '{
   "idempotency_key":"{{UNIQUE_KEY}}",
   "invoice":{
      "version": 0,
      "title":"Updated Title",
      "invoice_number":"new-number-100",
      "payment_requests":[
         {
            "request_type":"DEPOSIT",
            "due_date":"{{DUE_DATE}}",
            "percentage_requested":"25",
            "request_method":"CHARGE_CARD_ON_FILE",
            "card_id":"ccof:I6pHF8bMQghMAkoV4GB"
         },
         {
            "request_type":"BALANCE",
            "due_date":"{{DUE_DATE}}",
            "request_method":"CHARGE_CARD_ON_FILE",
            "card_id":"ccof:I6pHF8bMQghMAkoV4GB"
         }
      ]
   },
   "fields_to_clear":[
      "payment_requests[ea89248e-ff10-4958-98e9-2433ee1cee68]"
   ]
}'

Note the following:

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

• invoice specifies payment_requests without referring to any existing uid value. Therefore, these payment requests are added. If you add a uid value to any of these payment requests, it indicates an update of an existing payment request.

Example 4: Update payment requests by replacing percentages with exact amounts

Suppose you create a draft invoice with two payment requests: a deposit of 20% and the remaining balance due at a later date. A sample invoice fragment is shown:

{
   "invoice":{
      "id":"lsBlUr0vkDIu_mAexample",
      "version":0,
      "location_id":"S8GWD5R9QB376",
      "order_id":"8tXvK5qwjkEPbeLixWaKSxexample",
      "payment_requests":[
         {
            "uid":"32d69642-1614-4d84-ae4a-75d51c3c7f86",
            "request_method":"EMAIL",
            "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"
            }
         },
         {
            "uid":"622a0315-e640-4a7a-9763-87461fc5845d",
            "request_method":"EMAIL",
            "request_type":"BALANCE",
            "due_date":"2020-09-01",
            "computed_amount_money":{
               "amount":400,
               "currency":"USD"
            },
            "total_completed_amount_money":{
               "amount":0,
               "currency":"USD"
            }
         }
      ],
      ...
      }
   }
}

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

• Add a new fixed_amount_requested_money field.

• Remove the percentage_requested field.

The following UpdateInvoice example performs both of these updates:

curl https://connect.squareupsandbox.com/v2/invoices/{{INVOICE_ID}} \
 -X PUT \
 -H 'Authorization: Bearer {{ACCESS_TOKEN}}' \
 -H 'Content-Type: application/json' \
 -H 'Accept: application/json' \
 -d '{
   "idempotency_key":"{{UNIQUE_KEY}}",
   "invoice":{
      "version": 0,
      "payment_requests":[
         {
            "uid":"32d69642-1614-4d84-ae4a-75d51c3c7f86",
            "fixed_amount_requested_money":{
                "amount": 100,
                "currency": "USD"
            }
         }]},
   "fields_to_clear":[
      "payment_requests[32d69642-1614-4d84-ae4a-75d51c3c7f86].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":"S8GWD5R9QB376",
      "order_id":"8tXvK5qwjkEPbeLixWaKSxexample",
      "payment_requests":[
         {
            "uid":"32d69642-1614-4d84-ae4a-75d51c3c7f86",
            "request_method":"EMAIL",
            "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"
            }
         },
         {
            "uid":"622a0315-e640-4a7a-9763-87461fc5845d",
            "request_method":"EMAIL",
            "request_type":"BALANCE",
            "due_date":"2020-09-01",
            "computed_amount_money":{
               "amount":400,
               "currency":"USD"
            },
            "total_completed_amount_money":{
               "amount":0,
               "currency":"USD"
            }
         }
      ],
      ...
}

Cancel an invoice

You call CancelInvoice to cancel a published invoice. After you cancel an invoice, Square sends an email notification to the customer. Any automatic scheduled communication (such as emails and charges) stops. Also, the seller cannot collect payments for the 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.

curl https://connect.squareupsandbox.com/v2/invoices/{{YOUR_INVOICE_ID}}/cancel \
 -H 'Authorization: Bearer {{ACCESS_TOKEN}}' \
 -H 'Content-Type: application/json' \
 -H 'Accept: application/json' \
 -d '{
  "version": 0
}'

Example response:

{
  "invoice": {
    "id": "YOUR_INVOICE_ID",
    "version": 1,
    "status": "CANCELED",
    ...
  }
}

You cannot cancel invoices in the DRAFT state or in the PAID, REFUNDED, CANCELED, or FAILED terminal states. After you cancel an invoice, the invoice remains and the status changes to CANCELED. The GetInvoice or SearchInvoice request returns canceled invoices.

Delete an invoice

You call DeleteInvoice to delete a draft invoice. You cannot delete scheduled invoices (invoices scheduled for publication) or published invoices. Deleted invoices are removed and a GetInvoice or SearchInvoices request does not return deleted invoices.

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

The following is an example DeleteInvoice request. You must provide the invoice ID and current version for all DeleteInvoice 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.

curl https://connect.squareupsandbox.com/v2/invoices/{{YOUR_INVOICE_ID}}?version=0 \
 -H 'Authorization: Bearer {{ACCESS_TOKEN}}' \
 -H 'Accept: application/json' \
 -X DELETE

Example response:

{}

Retrieve an invoice

You can retrieve a specific invoice, list invoices at a location, and search for invoices at a specific location for a specific customer:

• Call GetInvoice if you know the invoice ID.

  Copy

  curl https://connect.squareupsandbox.com/v2/invoices/{{INVOICE_ID}} \
   -X GET \
   -H 'Authorization: Bearer {{ACCESS_TOKEN}}' \
   -H 'Content-Type: application/json' \
   -H 'Accept: application/json' 
  

• Call ListInvoices to retrieve invoices at a specific location.

  Copy

  curl https://connect.squareupsandbox.com/v2/invoices?location_id={{LOCATION_ID}}&limit=5 \
   -X GET \
   -H 'Authorization: Bearer {{ACCESS_TOKEN}}' \
   -H 'Content-Type: application/json' \
   -H 'Accept: application/json' 
  

  The following is an example response fragment:

  Copy

  {
    "invoices": [
      {
        "id": "AN_INVOICE_ID",
        ...
      },
      {
        "id": "ANOTHER_INVOICE_ID",
        ... 
      },
      ...
    ],
    "cursor": "NEXT_CURSOR"
  }
  

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

  Copy

  curl 
   -X GET \
  https://connect.squareupsandbox.com/v2/invoices?location_id={{LOCATION_ID}}&cursor={{CURSOR}} \
   -H 'Authorization: Bearer {{ACCESS_TOKEN}}' \
   -H 'Content-Type: application/json' 
  

• Call SearchInvoices to retrieve invoices that match a specific query. You can optionally include a customer ID to retrieve invoices for a specific customer at the specified location.

  In the current implementation, the SearchInvoices endpoint only supports filtering to a single customer and specifying a single location is required.

  The following is a SearchInvoice request that filters to a specific customer and orders the results from older to newer:

  Copy

  curl https://connect.squareupsandbox.com/v2/invoices/search \
   -X POST \
   -H 'Authorization: Bearer {{ACCESS_TOKEN}}' \
   -H 'Content-Type: application/json' \
   -H 'Accept: application/json' \
   -d '{
    "query": {
      "filter": {
        "location_ids": [ "YOUR_LOCATION_ID" ],
        "customer_ids": [ "YOUR_CUSTOMER_ID" ]
      },
      "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.

  Copy

  {
    "invoices": [
      {
        "id": "AN_INVOICE_ID",
        ...
      },
      {
        "id": "ANOTHER_INVOICE_ID",
        ... 
      },
      ...
    ],
    "cursor": "NEXT_CURSOR"
  }
  

  Copy

  curl https://connect.squareupsandbox.com/v2/invoices/search \
   -X POST \
   -H 'Authorization: Bearer {{ACCESS_TOKEN}}' \
   -H 'Content-Type: application/json' \
   -H 'Accept: application/json' \
   -d '{
    "query": {
      "filter": {
        "location_ids": [ "YOUR_LOCATION_ID" ],
        "customer_ids": [ "YOUR_CUSTOMER_ID" ]
      }
    }
  }'
  

  The following is an example response fragment:

  Copy

  {
    "invoices": [
      {
        "id": "AN_INVOICE_ID",
        ...
      },
      {
        "id": "ANOTHER_INVOICE_ID",
        ... 
      },
      ...
    ],
    "cursor": "NEXT_CURSOR"
  }
  

Refund an invoice

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

In the current implementation, the Refunds API does not support refunding 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 first canceled using CancelInvoice before they can be refunded.

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.

Limitations

• An order associated with an invoice has the following restrictions:

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

    Note

    However, after customers pay for the invoices, the resulting Payment objects are accessible using the Payments API (GetPayment and ListPayments). The payments also appear in the Seller Dashboard in the Transactions section along with other payments. 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.

Webhooks

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