Create and Publish Invoices

Applications can use the Invoices API to request or collect payment from customers on behalf of a Square seller. First, call the CreateInvoice endpoint to create a draft invoice for an order (which must be created with the Orders API) and configure the payment schedule, recipient, and other invoice settings. Then, call the PublishInvoice endpoint to begin processing the invoice.

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, call SearchOrders to get the order ID.

  • The order status must be OPEN.

  • The order cannot include rewards.

  • The order cannot use rule-based pricing options, which means that 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.

    • The treatment_type of the service charge isn't APPORTIONED_TREATMENT.

• The ID of the customer profile

  A customer record in the seller's Customer Directory.
  that represents the invoice recipient. The recipient can be the customer associated with the order or a different customer. If needed, call SearchCustomers to get the customer ID.

  The customer profile must include email_address or phone_number. An email address is required if the invoice is delivered by email or configured for automatic payment.

• The ID of a card on file if the invoice is configured for automatic payment. To obtain the card ID, call ListCards using the customer_id query parameter.

• The payment schedule for the invoice, list of payment methods accepted on the invoice payment page, and delivery method that Square should use to communicate with the recipient. For more information, see Configuring payment requests and Configuring how Square processes an invoice.

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

• An order can be associated with a single invoice, and an invoice can be associated with a single order. After an order is associated with an invoice, updates to the order are subject to restrictions.

  Orders created from Square Online or other Square products cannot be associated with an invoice because they don't initially include an order ID.

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

• When a customer ID is first specified for an invoice, Square retrieves contact information from the customer profile and adds it to the invoice. However, this recipient information isn't updated if the information changes in the Customer Directory.

For more information and 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. This field isn't required to create the invoice, but it's required to publish the invoice.

• The payment_requests for the invoice, with one or more payment requests that equal the total_money of the order. For more information, see Configuring payment requests.

• The delivery_method that Square should use to communicate with the recipient.

• 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

  • buy_now_pay_later

  • cash_app_pay

  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.

• Optional invoice settings.

• An optional idempotency_key to ensure idempotency.

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

curl https://connect.squareupsandbox.com/v2/invoices \
  -X POST \
  -H 'Square-Version: 2023-08-16' \
  -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 processed 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.

curl https://connect.squareupsandbox.com/v2/invoices \
  -X POST \
  -H 'Square-Version: 2023-08-16' \
  -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.

{
  "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,
      "cash_app_pay": false
    },
    "delivery_method": "EMAIL",
    "sale_or_service_date": "2022-08-24",
    "store_payment_method_enabled": true
  }
}

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

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.

When 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

Optional invoice settings

The following optional fields are commonly used in CreateInvoice requests. For information about all optional invoices fields, see 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 fields 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.

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

The following is an example response:

{
  "invoice": {
    "id": "inv:0-ChBoaXkM5QOPv9UO9C_Zexample",
    "version": 1,
    "location_id": "S8GWD5example",
    "order_id": "AdSjVqPCzOAQqvTnzy46VLexample",
    "payment_requests": [
      {
        "uid": "ccc0fc9b-c2a5-42a9-836d-92d01example",
        "request_type": "BALANCE",
        "due_date": "2021-09-29",
        "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,
      "cash_app_pay": 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.

Deposit or installment payments can be specified by percentage or as a fixed amount. For percentage-based payments, Square computes the amount based on the total_money amount of the order.

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:

  Copy

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

  Copy

  • 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 isn't 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:

  Copy

  • 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, the 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 amounts for deposits and installments, as shown in the following payment_requests example:

  Copy

  • 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. The customer must approve each payment. This value cannot be set from the Invoices API. It applies only to invoices that sellers create in Square products, such as the Seller Dashboard.

  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 doesn't 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 a reminder to the customer or initiating an automatic payment) based on invoice settings.

The following sections describe how to configure invoice settings to control how Square processes the invoice.

Link to section

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:

  • due_date - Specify the due date of the payment.

  • automatic_payment_source - Keep the default value of NONE.

  • request_type, reminders, and other payment fields - Specify 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.

Link to section

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

Link to section

Option 3: Square takes no action

In this case, the seller or the application developer follows up with the customer. Square doesn't 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:

  • due_date - Specify the due date of the payment.

  • automatic_payment_source - Keep the default value of NONE.

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

Link to section

See also

• Invoices API Overview

• Walkthrough: Create and Publish Invoices

• API Reference: Invoices