Learn how to use the CreateInvoice and PublishInvoice endpoints in the Square Invoices API to configure, create, and publish invoices.
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.

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:

For other considerations, see Requirements and limitations.

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: 2022-09-21' \
  -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: 2022-09-21' \
  -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
  • 56
{
  "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": "doe@email.com"
    },
    "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
    },
    "delivery_method": "EMAIL",
    "sale_or_service_date": "2022-08-24",
    "store_payment_method_enabled": true,
    "custom_fields": []
  },
  "errors": []
}

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_numberA 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.
titleThe invoice title that displays on the invoice. If not specified, the business name is used as the title.
descriptionThe description that displays on the invoice.
sale_or_service_dateThe 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_fieldsUp to two custom fields that display on the invoice. Custom fields require an Invoices Plus subscription.
store_payment_method_enabledIndicates 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.

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
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
curl https://connect.squareupsandbox.com/v2/invoices/{invoice_id}/publish \
  -X POST \
  -H 'Square-Version: 2022-09-21' \
  -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
  • 60
{
  "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": "doe@email.com"
    },
    "accepted_payment_methods": {
      "card": true,
      "square_gift_card": true,
      "bank_account": false
    },
    "delivery_method": "EMAIL",
    "sale_or_service_date": "2021-08-24",
    "store_payment_method_enabled": true,
    "custom_fields": []
  },
  "errors": []
}

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.

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 minimum amount for a payment request is 100 base units in the target currency (for example, $1.00 in USD).

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

Payment scenariorequest_type combination
One payment in full1 BALANCE
A deposit with the balance due later1 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.

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

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
    NONENo automatic payment is configured. This is the default value.
    CARD_ON_FILEDirects 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_FILEDirects 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.

  • The minimum amount of a single payment request is 100 base units. For more information, see Minimum invoice amounts by currency.

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

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.


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.


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.

Note

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.

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