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 invoices. In addition, the Invoices API enables developers to integrate Square invoices in third-party applications.

Overview

Managing invoices can be hard, but Square has simplified the experience when you integrate the Invoices API in your application flow:

• You do not need to worry about sending invoices, collecting payments, and sending reminders to customers. Square follows up with your customers with the invoices you create: sends invoices to the customer's email address or automatically charges the customer's card on file. If an invoice is split into multiple payment requests, Square follows up with the customer based on the schedule.

• Square makes it easy for your customers to pay by hosting each invoice on a web page where customers can pay their invoices.

• The seller has access to all the invoices on the Square Seller Dashboard.

You can use the Invoices API to create invoices for orders created using the Orders API. Integrating the Invoices API with the Orders API and Customers API reduces the application development costs. For example, to create an invoice using the Invoices API, you provide:

• An order ID. The API reads the order and creates an invoice for the amount identified in the order.

• A customer ID, the invoice recipient. The API reads the customer profile in the seller's Customer Directory and can send an invoice to the customer's email address or charge the customer's card on file.

You have the option to direct Square to email the invoice or charge a customer's card on file (and email the receipt). You also have the option to only create an invoice, in which case the seller follows up with the customer. These invoices are available on a Square-hosted page that customers can use to pay a specified amount.

You can also use the Invoices API to access invoices created using the Square Seller Dashboard or the mobile applications.

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

• invoice_number is a user-friendly string. If you do not provide this string, Square assigns a value. You might use the invoice number for client-side operations. You only need the invoice id when requesting any invoice action using the Invoices API.

Payment requests

In the preceding invoice, payment_requests specifies one payment request (see InvoicePaymentRequest) for the balance amount (the total_amount 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.

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 a payment_requests must equal the order amount (the total_money field).

• 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

To create an invoice, the order ID and customer ID are required. The total_amount in the order is the invoice amount. The following applies:

• The order must have a customer ID assigned and the order status must be OPEN. The order location and the invoice location must be the same.

• The customer ID is the ID from the seller's Customer Directory. The customer who creates the order and who receives the invoice can be different.

Creating an invoice is a two-step process: create a draft invoice and publish the invoice. Only after you publish the invoice does Square process it by emailing the invoice to the customer or charging the customer's card on file.

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

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

Step 2: Publish the invoice

You call PublishInvoice to publish the draft as shown. In the request, you provide the invoice ID and invoice 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",
    "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 responds based on the request_method you specified. In this example, Square emails the invoice to the customer. For information about other request methods, see Invoice.

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 not take action when the invoice is published. In this case, the seller processes the invoice.

Update an invoice

You call UpdateInvoice to update an invoice. There are no restrictions to updating an invoice in a DRAFT state. However, the following guidelines apply to updating a published invoice:

• You cannot update the primary_recipient, order_id, and location_id fields.

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

• You cannot update an invoice or initiate another payment for an invoice in the PAYMENT_PENDING 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.

All update invoice operations require an invoice ID and version. You call ListInvoices or GetInvoice to retrieve the invoice and find 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. You must provide the invoice version in the request and it changes 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 uidvalue. 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 an 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. The invoice version is required.

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 terminal states: PAID, REFUNDED, CANCELED, or FAILED. 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 an invoice. You can only delete draft invoices. 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. The invoice version is required.

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, you specify a location. The location you choose 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 (for example, 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 have an order ID field set.

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

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