Beta Release
This is pre-release documentation for an API in public beta and is subject to change.
Invoices API

Example Walkthrough: Create and Publish Invoices

In this walkthrough, you explore the Invoices API. You create an invoice, publish it, and explore the customer experience by paying for the invoice. You use the Square Sandbox and cURL commands to test the API endpoints. The Square Sandbox test environment provides a fake card that you use to pay after you receive an invoice. The Square Sandbox also supports adding a fake card on file that Square can charge for the invoice. These cards are never charged.

Prepare Permalink Get a link to this section

To prepare for the walkthrough, you:

  • Review Sandbox testing considerations. Understand how you test the walkthrough in the Square Sandbox.

  • Gather account information. You need your Sandbox credentials (access token) and location ID. You use the access token to authenticate requests and your location ID when you create an order using the Orders API.

  • Create a customer profile. A customer profile must exist in the seller's Customer Directory to send an invoice. You create a customer profile using the Customers API. You also add a card on file for this customer. You then have an option to email an invoice or charge the card on file.

Step 1: Square Sandbox testing considerations Permalink Get a link to this section

When you create an invoice, you have the option to specify a card on file along with the customer. In this case, Square charges the card on file and sends a receipt to the customer. If you do not provide a payment card when creating an invoice, Square sends an invoice to the customer's email address. Customers can go to the Square-hosted invoice page and provide card information to pay the invoice.

You use the following Sandbox test values to test both the experiences:

  • Fake credit card. Customers can choose to receive an invoice by email. They can then pay using a credit card, a check, or cash. This walkthrough uses this fake credit card to pay an invoice.

  • Test nonce. The Sandbox provides a test nonce (cnon:card-nonce-ok) for you to create a card on file. You can then specify this card on file at the time of creating an invoice so Square can charge the card on file.

Step 2: Gather account information Permalink Get a link to this section

Follow these steps to gather account information for your Sandbox environment:

  1. Sign in to the Developer Dashboard.

  2. Open an application, which provides you with the credentials you use. If you do not have an application, you need to create one.

  3. Get Sandbox credentials:

    1. You can toggle between the Sandbox and Production account. Choose Sandbox.

    2. On the Credentials page, copy the token from Sandbox Access Token.

  4. Get a location ID:

    1. Choose Locations in the left navigation.

    2. On the Locations page, choose an ID from Location ID.

Step 3: Create a customer Permalink Get a link to this section

In this step, you create a customer profile in the seller's Customer Directory. You also add a card on file for this customer.

  1. Call CreateCustomer to create a customer profile. Make sure you provide a valid email address because Square sends invoices to this address (Square Sandbox does not send email but in production emails are sent).

    curl https://connect.squareupsandbox.com/v2/customers \
     -X POST \
     -H 'Authorization: Bearer {{ACCESS_TOKEN}}' \
     -H 'Content-Type: application/json' \
     -H 'Accept: application/json' \
     -d '{
       "idempotency_key": "{{UNIQUE_KEY}}",
       "email_address": "{{EMAIL_ADDRESS}}",
       "given_name": "John",
       "family_name": "Doe"
     }'
    

    The following is an example response:

    {
       "customer":{
          "id":"DJREAYPRBMSSFAB4TGABC26K4C",
          "created_at":"2020-05-30T18:38:16.973Z",
          "updated_at":"2020-05-30T18:38:17Z",
          "given_name":"John",
          "family_name":"Doe",
          "email_address":"{{EMAIL_ADDRESS}}",
          "preferences":{
             "email_unsubscribed":false
          },
          "creation_source":"THIRD_PARTY"
       }
    }
    
You need the customer ID to create an order.
  1. Call CreateCustomerCard to add a card on file to the customer profile.

    curl https://connect.squareupsandbox.com/v2/customers/{{CUSTOMER_ID}}/cards \
      -X POST \
      -H 'Authorization: Bearer {{ACCESS_TOKEN}}' \
      -H 'Content-Type: application/json' \
      -H 'Accept: application/json' \
      -d '{
        "card_nonce": "cnon:card-nonce-ok"
      }'
    

    The following is an example response:

    {
       "card":{
          "id":"ccof:aD1D4q9aUXTkA2ET3GB",
          "card_brand":"AMERICAN_EXPRESS",
          "last_4":"6550",
          "exp_month":5,
          "exp_year":2022
       }
    }
    

    When you create an invoice, you have the option to charge the card on file (instead of emailing the invoice), in which case you need the card ID.

Invoice example 1: Requests payment in full Permalink Get a link to this section

In this example, you create an order and send an invoice to the customer. The invoice requests one payment for the full order amount.

Create an order Permalink Get a link to this section

  1. Call CreateOrder to create a sample order for a $1 item.

    curl https://connect.squareupsandbox.com/v2/locations/{{LOCATION_ID}}/orders \
      -X POST \
      -H 'Authorization: Bearer {{ACCESS_TOKEN}}' \
      -H 'Content-Type: application/json' \
      -H 'Accept: application/json' \
      -d '{
        "idempotency_key": "{{UNIQUE_KEY}}",
        "order": {
          "customer_id": "{{CUSTOMER_ID}}",
          "line_items": [
            {
              "name": "Example Item",
              "quantity": "1",
              "base_price_money": {
                "amount": 100,
                "currency": "USD"
              }
            }
          ]
        }
      }'
    

    The following is an example order fragment:

    {
      "order": {
        "id": "AdSjVqPCzOAQqvTnzy46VLexample",
        "location_id": "S8GWD5R9QB376",
        "line_items": [
          {
             ...
          }
        ],
        ...
        "total_money": {
          "amount": 100,
          "currency": "USD"
        },
        ...
        "customer_id": "DJREAYPRBMSSFAB4TGABC26K4C"
      }
    }
    

    The total_money appears on the invoice you create in the next step.

Send an invoice to the customer Permalink Get a link to this section

Sending an invoice is a two step process: creating a draft invoice and publishing the invoice. When you publish the invoice, Square processes the invoice based on the payment_requests specified in the invoice.

  1. Create a draft invoice. Call CreateInvoice to create a draft invoice. The sample invoice specifies one payment_request for the full order amount due by the specified due date. The request_method directs Square to email the invoice to the customer's email address.

    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 following is an example response, which includes the created draft invoices:

    {
      "invoice": {
        "id": "VgOxWO7_gERgtSEexample",
        "version": 0,
        "location_id": "S8GWD5R9QB376",
        "order_id": "AdSjVqPCzOAQqvTnzy46VLexample",
        "payment_requests": [
          {
            "uid": "ccc0fc9b-c2a5-42a9-836d-92d01ba41498",
            "request_method": "EMAIL",
            "request_type": "BALANCE",
            "due_date": "2020-06-01",
            "computed_amount_money": {
              "amount": 100,
              "currency": "USD"
            },
            "total_completed_amount_money": {
              "amount": 0,
              "currency": "USD"
            }
          }
        ],
        "invoice_number": "000028",
        "status": "DRAFT",
        "timezone": "Etc/UTC",
        "created_at": "2020-05-30T19:01:32Z",
        "updated_at": "2020-05-30T19:01:32Z",
        "primary_recipient": {
          "customer_id": "DJREAYPRBMSSFAB4TGABC26K4C",
          "given_name": "John",
          "family_name": "Doe",
          "email_address": "johndoe@email.com"
        }
      }
    }
    

    In addition to the id, version, and order_id fields, note the following invoice fields:

    • status indicates that the invoice is a DRAFT.

    • computed_amount_money shows the amount due.

    • primary_recipient shows additional customer profile information.

  2. Review the invoice. You can review the draft invoice in the Sandbox Seller Dashboard.

    1. Sign in to the Developer Dashboard.

    2. In the Sandbox Test Accounts section, open the Default Test Account.

    3. In the Sandbox Seller Dashboard, choose Invoices.

    4. Verify that the unpaid invoice is created and that the status is DRAFT.

  3. Publish the invoice. Call PublishInvoice to publish the invoice.

    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": "VgOxWO7_gERgtSEexample",
        "version": 1,
        "location_id": "S8GWD5R9QB376",
        "order_id": "AdSjVqPCzOAQqvTnzy46VLIyaoaZY",
        "payment_requests": [
          {
            "uid": "ccc0fc9b-c2a5-42a9-836d-92d01ba41498",
            "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/VgOxWO7_gERgtSEexample",
        "status": "UNPAID",
        "timezone": "Etc/UTC",
        "created_at": "2020-05-30T19:01:32Z",
        "updated_at": "2020-05-30T19:05:01Z",
        "primary_recipient": {
          "customer_id": "DJREAYPRBMSSFAB4TGABC26K4C",
          "given_name": "John-InvoiceCustWithCard",
          "family_name": "Doe-InvoiceCustWithCard",
          "email_address": "{{EMAIL_ADDRESS}}"
        },
        "next_payment_amount_money": {
          "amount": 100,
          "currency": "USD"
        }
      }
    }
    

    The published invoice shows the following changes:

    • The status field changes from DRAFT to UNPAID.

    • The public_url field is added to the invoice. It is the URL to the Square-hosted invoice page. The customer can go to this page to pay.

    • The next_payment_amount_money field is added. Because this walkthrough requests only one payment, it shows the full amount. When you request the payment in multiple payment requests, the field shows the amount that is due next based on the schedule. When one or more payments in the schedule are overdue, this field reflects the amount due accordingly. For example, consider an invoice for $2 that requires a deposit of $1 and the balance of $1 at a later date. If the deposit is overdue, this field indicates $2 as the next payment amount.

    After you publish the invoice in the production environment, Square sends an email to both the seller and the customer. The following is an example email sent to the customer. The customer can click Pay Invoice to open the Square-hosted invoice page and pay.

    invoices-example-diagram

    The seller receives similar email indicating a new invoice was created.

Pay the invoice Permalink Get a link to this section

The customer has the following options to pay for the invoice:

  • Choose Pay Invoice in the email to open the Square-hosted invoice page and pay the invoice.

  • Contact the seller and provide a payment card or cash. The sellers can process the payment in the Seller Dashboard or use mobile options (the Square Point of Sale application or Square Invoices application).

To pay the invoice on the Square-hosted invoice page, do the following:

  1. Open the Square-hosted invoice page (see public_url returned by the PublishInvoice call).

  2. Use the Sandbox-provided fake credit card information.

  3. After you pay, the invoice status changes to PAID. The seller can verify the status change in the Sandbox Seller Dashboard or use the mobile applications.

Invoice example 2: Request a deposit and charge a card on file Permalink Get a link to this section

The invoice you create in this example requests two payments: a deposit and the balance due at a later date. The invoice also charges the customer's card on file and sends a receipt to the customer's email address.

Create an order Permalink Get a link to this section

Call CreateOrder to create a sample order for $3.

curl https://connect.squareupsandbox.com/v2/locations/{{LOCATION_ID}}/orders \
  -X POST \
  -H 'Authorization: Bearer {{ACCESS_TOKEN}}' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -d '{
    "idempotency_key": "{{UNIQUE_KEY}}",
    "order": {
      "customer_id": "{{CUSTOMER_ID}}",
      "line_items": [
        {
          "name": "Example Item",
          "quantity": "1",
          "base_price_money": {
            "amount": 300,
            "currency": "USD"
          }
        }
      ]
    }
  }'

Note the order ID in the response.

Create and publish an invoice Permalink Get a link to this section

As before, you follow a two-step process: create an invoice and publish the invoice.

  1. Create a draft invoice. Call CreateInvoice to create a draft invoice. In the payment_requests, set the due_date for the deposit to the current date (so Square charges the card immediately and you can verify the charge) and a future date for the balance payment request. Use this date format: YYYY-MM-DD.

    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_type":"DEPOSIT",
                "due_date":"{{SPECIFY_DATE}}",
                "percentage_requested":"50",
                "request_method":"CHARGE_CARD_ON_FILE",
                "card_id":"{{CARD_ID}}"
             },
             {
                "request_type":"BALANCE",
                "due_date":"{{SPECIFY_DATE}}",
                "request_method":"CHARGE_CARD_ON_FILE",
                "card_id":"{{CARD_ID}}"
             }
          ]
       }
    }'
    

    The invoice requests 50% of the order amount as the deposit payment request. Both payment requests specify CHARGE_CARD_ON_FILE as the request_method. Instead of a percentage, you can specify exact amounts. If you do, the sum of the amounts must match the total_amount in the order.

    The following is an example response:

    {
      "invoice": {
        "id": "6BFBNDUD_zV7V9Yexample",
        "version": 0,
        "location_id": "X9XWRESTK1CZ1",
        "order_id": "HwVp5kPRVipPzeFo6hotMViuri8YY",
        "payment_requests": [{
          "uid": "968d4546-3d4b-4be7-8411-cddcb04d6ef0",
          "request_method": "CHARGE_CARD_ON_FILE",
          "request_type": "DEPOSIT",
          "due_date": "2020-06-14",
          "percentage_requested": "50",
          "card_id": "ccof:KLpj1GtASdG0YLpj3GB",
          "computed_amount_money": {
            "amount": 150,
            "currency": "USD"
          },
          "total_completed_amount_money": {
            "amount": 0,
            "currency": "USD"
          }
        }, {
          "uid": "8e1e2012-c9fc-491b-9545-6380fce98e73",
          "request_method": "CHARGE_CARD_ON_FILE",
          "request_type": "BALANCE",
          "due_date": "2020-07-01",
          "card_id": "ccof:KLpj1GtASdG0YLpj3GB",
          "computed_amount_money": {
            "amount": 150,
            "currency": "USD"
          },
          "total_completed_amount_money": {
            "amount": 0,
            "currency": "USD"
          }
        }],
        "invoice_number": "000007",
        "status": "DRAFT",
        "timezone": "America/Los_Angeles",
        "created_at": "2020-06-14T03:09:48Z",
        "updated_at": "2020-06-14T03:09:48Z",
        "primary_recipient": {
          "customer_id": "KTJ0H5D6SWR4B1ZGY47Q14QD38",
          "given_name": "John",
          "family_name": "Doe",
          "email_address": "doe@email.com"
        }
      }
    }
    

    You can review this draft invoice in the Sandbox Seller Dashboard as explained in example 1 (see Send an invoice to the customer).

  1. Publish the invoice. Call PublishInvoice to publish the invoice.

    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": "6BFBNDUD_zV7V9Yexample",
        "version": 1,
        "location_id": "X9XWRESTK1CZ1",
        "order_id": "HwVp5kPRVipPzeFo6hotMViuri8YY",
        "payment_requests": [
          {
            "uid": "968d4546-3d4b-4be7-8411-cddcb04d6ef0",
            "request_method": "CHARGE_CARD_ON_FILE",
            "request_type": "DEPOSIT",
            "due_date": "2020-06-14",
            "percentage_requested": "50",
            "card_id": "ccof:KLpj1GtASdG0YLpj3GB",
            "computed_amount_money": {
              "amount": 150,
              "currency": "USD"
            },
            "total_completed_amount_money": {
              "amount": 0,
              "currency": "USD"
            }
          },
          {
            "uid": "8e1e2012-c9fc-491b-9545-6380fce98e73",
            "request_method": "CHARGE_CARD_ON_FILE",
            "request_type": "BALANCE",
            "due_date": "2020-07-01",
            "card_id": "ccof:KLpj1GtASdG0YLpj3GB",
            "computed_amount_money": {
              "amount": 150,
              "currency": "USD"
            },
            "total_completed_amount_money": {
              "amount": 0,
              "currency": "USD"
            }
          }
        ],
        "invoice_number": "000007",
        "public_url": "https://squareupsandbox.com/pay-invoice/6BFBNDUD_zV7V9Yexample",
        "status": "UNPAID",
        "timezone": "America/Los_Angeles",
        "created_at": "2020-06-14T03:09:48Z",
        "updated_at": "2020-06-14T03:16:48Z",
        "primary_recipient": {
          "customer_id": "KTJ0H5D6SWR4B1ZGY47Q14QD38",
          "given_name": "John",
          "family_name": "Doe",
          "email_address": "doe@email.com"
        },
        "next_payment_amount_money": {
          "amount": 150,
          "currency": "USD"
        }
      }
    }
    

    Soon after the invoice is published, Square charges the customer's card on file and sends an invoice receipt to both the seller and customer. The customer can optionally choose Make Early Payment to pay the invoice sooner. Otherwise, Square charges the customer's card on the specified due dates. Note that:

    • After Square charges the card for the deposit, total_completed_amount_money becomes the same as the computed_amount_money.

    • After the deposit is paid, the invoice status changes to PARTIALLY_PAID.

    • The next_payment_amount field shows the amount that is due next.

Verify the invoice status Permalink Get a link to this section

After the customer receives the email, the customer can open the Square-hosted invoice page and verify the invoice. The customer has the option to pay the balance before the due date.