Invoices API

Create and Publish Invoices

Use the Invoices API to create invoices that enable Square sellers to request or collect payment from customers. First, you use the CreateInvoice endpoint to create a draft invoice that configures the payment schedule and other settings. Then, you use the PublishInvoice endpoint to direct Square to begin processing the invoice based on its settings. Invoices created with the Invoices API must be associated with orders created with the Orders API.

Prerequisites
Create an invoice
Publish an invoice
Configuring payment requests
Configuring how Square processes an invoice
Related topics

Link to section
Prerequisites

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

The ID of the associated order. If needed, you can call SearchOrders to get the order ID. An invoice can be associated with one order only. Note the following:
- The order must be created using the Orders API.
- The order status must be OPEN.
- The order cannot be associated with another invoice.
- The order cannot include rewards.
- The order cannot use rule-based pricing options. Therefore, the pricing_options.auto_apply_discounts and pricing_options.auto_apply_taxes fields cannot be set to true.
- The order can include a service charge only if the country of the order location is CA or US.
- After an invoice is created, updates to the associated order are subject to restrictions. For more information, see Limitations with the Orders API integration.
The ID of the customer profile that represents the invoice recipient. Note the following:
- You can use the customer ID from the order or specify a different customer ID. If needed, call SearchCustomers to get the customer ID.
- The customer profile must exist in the seller's Customer Directory and include either email_address or phone_number.
- If the invoice is delivered by email, which includes invoices configured for automatic payments, the customer profile must have a valid email address. Square uses this email address to send invoices, reminders, and receipts to the customer.
- A customer ID is not required to create the invoice, but it must be provided before you can publish the invoice.
- After an invoice is created, the Invoices API does not update the contact information of the recipient if the name, phone number, or email address changes in the associated customer profile. For more information, see Limitations with the Customers API integration.
The ID of a card on file (automatic payments only). To obtain the card ID, call ListCards using the customer_id query parameter.
The payment schedule for the invoice and other invoices settings. For more information, see Configuring payment requests and Configuring how Square processes an invoice.

In addition, you should be aware of the following considerations:

To use custom fields or installment payments, the seller for whom you create the invoice must have an active (or trial) Invoices Plus subscription.
Invoice requirements and features might vary by location. For more information, see International availability and considerations.

For other considerations, see Requirements and limitations.

Link to section
Create an invoice

Call CreateInvoice to create a draft invoice. Ensure that the prerequisites are met and provide the following information in the request:

The order_id of the associated order.
The customer_id of the invoice recipient.
The payment_requests for the invoice, with one or more payment requests that equal the total_money of the order. The Invoices API computes percentage-based payment amounts for the payment schedule based on the total_money of the order. For more information about payment requests and how to configure them, see Invoice payment requests.
The accepted_payment_methods that customers can use to pay the invoice on the invoice payment page. At least one of the following payment methods must be enabled:
- card (credit or debit card)
- square_gift_card
- bank_account
This setting is independent of any automatic payment requests for the invoice. Customers can choose to make a payment from the invoice payment page even when the invoice is configured for automatic payments.
An optional idempotency_key used to ensure idempotency.

The following example request includes one BALANCE payment request due by September 30, 2022:

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

curl https://connect.squareupsandbox.com/v2/invoices \
  -X POST \
  -H 'Square-Version: 2023-03-15' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{
    "idempotency_key": "{UNIQUE_KEY}",
    "invoice": {
      "order_id": "AdSjVqPCzOAQqvTnzy46VLexample",
      "primary_recipient": {
        "customer_id": "DJREAYPRBMSSFAB4TGAexample"
      },
      "delivery_method": "EMAIL",
      "payment_requests": [
        {
          "request_type": "BALANCE",
          "due_date": "2022-09-30"
        }
      ],
      "accepted_payment_methods": {
        "card": true,
        "square_gift_card": true
      },
      "title": "My Invoice Title",
      "sale_or_service_date": "2022-08-24",
      "store_payment_method_enabled": true
    }
  }'

You can also configure the invoice to be sent at a future date and configure reminders for before and after the due date. The following CreateInvoice request directs Square to send the invoice on the scheduled_at date and send a reminder 1 day before the payment due date. If the payment is made before the due date, Square does not send the reminder.

Create Invoice

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35

curl https://connect.squareupsandbox.com/v2/invoices \
  -X POST \
  -H 'Square-Version: 2023-03-15' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{
    "idempotency_key": "{UNIQUE_KEY}",
    "invoice": {
      "order_id": "AdSjVqPCzOAQqvTnzy46VLexample",
      "scheduled_at": "2022-09-01T09:00:00Z",
      "primary_recipient": {
        "customer_id": "DJREAYPRBMSSFAB4TGAexample"
      },
      "delivery_method": "EMAIL",
      "payment_requests": [
        {
          "request_type": "BALANCE",
          "due_date": "2022-09-30",
          "reminders": [
            {
              "relative_scheduled_days": -1,
              "message": "Your payment is due tomorrow."
            }
          ]
        }
      ],
      "accepted_payment_methods": {
        "card": true,
        "square_gift_card": true
      },
      "title": "My Invoice Title",
      "sale_or_service_date": "2022-08-24",
      "store_payment_method_enabled": true
    }
  }'

The following is an example response. Note that the status of the returned invoice is set to DRAFT.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55

{
  "invoice": {
    "id": "inv:0-ChBoaXkM5QOPv9UO9C_Zexample",
    "version": 0,
    "location_id": "S8GWD5example",
    "order_id": "AdSjVqPCzOAQqvTnzy46VLexample",
    "payment_requests": [
      {
        "uid": "ccc0fc9b-c2a5-42a9-836d-92d01example",
        "request_type": "BALANCE",
        "due_date": "2022-09-30",
        "tipping_enabled": false,
        "computed_amount_money": {
          "amount": 2699,
          "currency": "USD"
        },
        "total_completed_amount_money":{
           "amount":0,
           "currency":"USD"
        },
        "reminders": [
          {
            "uid": "b0325b84-b231-4c8a-b3ca-d9e23example",
            "relative_scheduled_days": -1,
            "message": "Your invoice is due tomorrow",
            "status": "PENDING"
          }
        ],
        "automatic_payment_source": "NONE"
      }
    ],
    "primary_recipient": {
      "customer_id": "DJREAYPRBMSSFAB4TGAexample",
      "given_name": "John",
      "family_name": "Doe",
      "email_address": "[email protected]"
    },
    "invoice_number": "000028",
    "title": "My Invoice Title",
    "scheduled_at": "2022-09-01T09:00:00Z",
    "status": "DRAFT",
    "timezone": "Etc/UTC",
    "created_at": "2022-08-26T19:01:32Z",
    "updated_at": "2022-08-26T19:01:32Z",
    "accepted_payment_methods": {
      "card": true,
      "square_gift_card": true,
      "bank_account": false,
      "buy_now_pay_later": false
    },
    "delivery_method": "EMAIL",
    "sale_or_service_date": "2022-08-24",
    "store_payment_method_enabled": true
  }
}

The following table lists some other optional fields that you can specify in a CreateInvoices request. For information about all invoices fields, see Invoice.

Field	Description
`invoice_number`	A user-friendly string that displays on the invoice. You might use the invoice number for client-side operations. If not specified, Square assigns a value.
`title`	The invoice title that displays on the invoice. If not specified, the business name is used as the title.
`description`	The description that displays on the invoice.
`sale_or_service_date`	The date of the sale or the date when the service was rendered. This date displays on the invoice but does not drive any business logic.
`custom_fields`	Up to two custom fields that display on the invoice. Custom fields require an Invoices Plus subscription.
`store_payment_method_enabled`	Indicates whether to allow customers to save credit card, debit card, or bank transfer payment information when paying an invoice. The default value is `false`. When set to `true`, Square displays a Save my card on file or Save my bank on file checkbox on the invoice payment page. If the checkbox is selected, Square creates a card on file or a bank account on file for the customer using the information provided in the payment form. Stored payment information can be used for future automatic payments. Allowing customers to save gift cards on file is not supported.

After an invoice is created, Square adds the following fields to each payment request:

computed_amount_money with the amount of the payment request.
total_completed_amount_money with a zero amount, which represents the amount paid for the payment request. Square updates the amount after the payment request is paid.

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

After an invoice is created, Square invokes an invoice.created webhook event. The order.updated event is also invoked after Square associates the order with the invoice.

Link to section
Publish an invoice

To publish an invoice, call PublishInvoice provide the following information:

The ID of the invoice to publish. The invoice must be in the DRAFT state.
The current version of the invoice.
An optional idempotency_key used to ensure idempotency.

You can use the ID and version from the invoice returned in the CreateInvoice response. If you need to get the ID and version, call SearchInvoices or ListInvoices. If you have the ID but need the version, call GetInvoice.

Publish Invoice

curl https://connect.squareupsandbox.com/v2/invoices/{invoice_id}/publish \
  -X POST \
  -H 'Square-Version: 2023-03-15' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{
    "version": 0,
    "idempotency_key": "{UNIQUE_KEY}"
  }'

The following is an example response:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59

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

The status of the returned invoice depends on how the invoice is configured. For example, the status is SCHEDULED if scheduled_at is set to a future date or UNPAID if the payment due_date is set to a future date.

After an invoice is published and the scheduled_at date (if specified) is reached, Square does the following:

Generates the invoice payment page where customers can make a payment.
Adds the public_url field with the payment page URL to the invoice.
Adds the next_payment_amount_money field with the next payment amount due to the invoice, unless an automatic payment for the balance is completed immediately.
Processes the invoice based on the invoice settings and handles the remaining workflow.
For example, Square can email the invoice, charge a card on file, or take no action if you or the seller wants to follow up with the customer directly. Square manages automatic payments and payments that customers make from the invoice payment page. Square also updates the invoice payment status and sends reminders and receipts as scheduled.

When the invoice is published, Square invokes invoice.published and invoice.updated webhook events, along with additional events if the invoice is configured to immediately collect an automatic payment. For more information, see Pay an invoice.

Link to section
Configuring 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 in the previous section contains one payment request for the full order amount, but you can optionally split the invoice into multiple payment requests. A payment request is represented by the InvoicePaymentRequest object.

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

Payment 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 (requires an Invoices Plus subscription)	1 `DEPOSIT` and 2–12 `INSTALLMENT`
All payments in installments (requires an Invoices Plus subscription)	2–12 `INSTALLMENT`

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

For sellers who accept Afterpay (or Clearpay) payments, you can enable invoices to accept Buy Now Pay Later payments. For more information, see Buy Now Pay Later payments with Afterpay.

Link to section
Example payment requests

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

One payment in full
The following payment_requests example shows how to request one payment in full:
- 1
- 2
- 3
- 4
- 5
- 6
- 7
- 8
```
...
"payment_requests": [
   {
      "request_type":"BALANCE",
      "due_date":"2030-02-01"
   }
]
...
```
The single BALANCE payment request represents the total amount of the order.
Deposit with balance due later
The following payment_requests example shows how to request a 50% deposit and the remaining 50% balance at a later date:
- 1
- 2
- 3
- 4
- 5
- 6
- 7
- 8
- 9
- 10
- 11
- 12
- 13
```
...
"payment_requests": [
   {
      "request_type":"DEPOSIT",
      "due_date":"2030-02-01",
      "percentage_requested":"50"
   },
   {
      "request_type":"BALANCE",
      "due_date":"2030-03-01"
   }
]
...
```
This example contains two payment requests. The first is a DEPOSIT that uses the percentage_requested field to request 50% of the total amount of the order. The balance is for the remaining amount, which is not explicitly specified.

Deposit with two installments (requires an Invoices Plus subscription)

A deposit can also be combined with 2–12 installment payments.

Percentage example

The following payment_requests example shows how to use the percentage_requested field to request a 50% deposit and the balance paid in two equal installments:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

...
"payment_requests": [
   {
      "request_type":"DEPOSIT",
      "due_date":"2030-02-01",
      "percentage_requested":"50"    // 50% of total order amount
   },
   {
      "request_type":"INSTALLMENT",
      "percentage_requested":"50",   // 50% of remaining balance after deposit
      "due_date":"2030-03-01"
   },
   {
      "request_type":"INSTALLMENT",
      "percentage_requested":"50",   // 50% of remaining balance after deposit
      "due_date":"2030-04-01"
   }
]
...

The percentage requested for the installments applies to the amount remaining after the deposit is paid. For an order with a total amount of $100, this invoice would request a $50 deposit, followed by two installments of $25 each.

Fixed amount example

Instead of percentages, you can use the fixed_amount_requested_money field to specify exact (fixed) amounts for deposits and installments, as shown in the following payment_requests example:

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

...
"payment_requests": [
   {
      "request_type":"DEPOSIT",
      "due_date":"2030-07-30",
      "fixed_amount_requested_money":{
         "amount":5000,              // A $50 payment
         "currency":"USD"
      }
   },
   {
      "request_type":"INSTALLMENT",
      "fixed_amount_requested_money":{
         "amount":2500,              // A $25 payment
         "currency":"USD"
      },
      "due_date":"2030-08-30"
   },
   {
      "request_type":"INSTALLMENT",
      "fixed_amount_requested_money":{
         "amount":2500,              // A $25 payment
         "currency":"USD"
      },
      "due_date":"2030-09-30"
   }
]
...

Link to section
Payment request considerations

The following considerations apply when configuring payment requests:

The due_date and request_type fields must be specified for all payment requests.
For DEPOSIT or INSTALLMENT payment requests, either a percentage-based amount or a fixed amount must be specified.
- To specify a percentage-based amount, set the percentage_requested field.
  - For a DEPOSIT request, base the percentage on the total order amount.
  - For INSTALLMENT requests, base the percentage on the total order amount minus any deposit amount. The percentages of all installment payment requests must add up to 100%, as shown in the preceding example.
    Installment payments are supported only with an Invoices Plus subscription.
- To specify a fixed amount, set the fixed_amount_requested_money field.
  - The total payment amounts in payment_requests must equal the total_money amount of the associated order.

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

Value	Description
`NONE`	No automatic payment is configured. This is the default value.
`CARD_ON_FILE`	Directs Square to charge the credit or debit card on file specified by the `card_id` field of the payment request. To get a card ID, call ListCards and provide the `customer_id`. To set up automatic payments from a card on file, you must set the `delivery_method` of the invoice to `EMAIL`.
`BANK_ON_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 Square products, such as the Seller Dashboard. Invoices with a bank account payment can have only one payment request of the `BALANCE` type.

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

For each payment request, you can use the reminders field to schedule one or more reminders relative to the due_date of the payment. For more information, see InvoicePaymentReminder.
Square sends reminders at 11:00 AM in the timezone of the invoice. If the payment is made before the scheduled reminder date, Square does not send the reminder.

Link to section
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.
accepted_payment_methods. Specify true for one or more payment methods that customers can use to pay the invoice on the invoice payment page.
For each payment request, configure the following fields:

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

scheduled_at. To send the invoice or receipt immediately after publishing, omit this field. Otherwise, specify the date to send the invoice.
delivery_method. Specify EMAIL.
accepted_payment_methods. Specify true for one or more payment methods that customers can use to pay the invoice on the invoice payment page. This field is required even when the invoice is configured for automatic payments because customers can optionally make a payment from the invoice page.
For each payment request, configure the following fields:
- due_date. Specify the due date of the payment. Square charges the card on file on this date.
- automatic_payment_source. Specify CARD_ON_FILE.
- card_id. Specify the ID of the card on file to charge. To get a card ID, call ListCards and provide the customer_id.
- request_type,reminders, and other payment fields, as needed. For invoices with multiple payment requests, Square sends invoices and reminders according to the payment schedule. For more information, see Configuring payment requests and Automatic communication from Square.

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

delivery_method. Specify SHARE_MANUALLY.
accepted_payment_methods. Specify true for one or more payment methods that customers can use to pay the invoice on the invoice payment page.
For each payment request, configure the following fields:

The following settings can be configured only from Square products:

SMS (text message) delivery method. See additional SMS considerations.
BANK_ON_FILE automatic payment method, which applies only to recurring invoices.

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

Link to section
Related topics

If you need more assistance, contact Developer Support or ask for help in the Developer Forums.

Create and Publish Invoices

On this page

Link to section
Prerequisites

Link to section
Create an invoice

Link to section
Publish an invoice

Link to section
Configuring payment requests

Note

Link to section
Example payment requests

Link to section
Payment request considerations

Link to section
Configuring how Square processes an invoice

Note

Link to section
Related topics

On this page

Create and Publish Invoices

On this page

Link to section Prerequisites

Link to section Create an invoice

Link to section Publish an invoice

Link to section Configuring payment requests

Note

Link to section Example payment requests

Link to section Payment request considerations

Link to section Configuring how Square processes an invoice

Note

Link to section Related topics

On this page

Link to section
Prerequisites

Link to section
Create an invoice

Link to section
Publish an invoice

Link to section
Configuring payment requests

Link to section
Example payment requests

Link to section
Payment request considerations

Link to section
Configuring how Square processes an invoice

Link to section
Related topics