Walkthrough: Create and Publish Invoices

Applies to: Invoices API | Orders API | Customers API | Cards API

Learn how to use the Invoices API to send an invoice to a customer or automatically charge a card on file.

In this walkthrough, you use the Invoices API to create and publish invoices and then simulate the customer experience of paying an invoice. You also use the Orders API to create orders and the Customers API and Cards API to create a customer and add a card on file. These resources are created in the Square Sandbox test environment, which provides the test credit card and payment token used to pay the invoices.

Before you begin the walkthrough, do the following:

• Review Sandbox testing considerations to understand how you use the Square Sandbox for testing.

• Gather account information to use for your API requests. You need your Sandbox access token to authorize API requests and your location ID to create orders.

• Create a customer and a card on file in the seller's Customer Directory. The customer profile includes an email address where Square sends invoices and receipts. The card on file associated with the customer profile enables automatic payments.

  The procedures in this walkthrough show you how to configure two invoices. The first procedure directs Square to email the invoice to request payment from the customer. The second procedure directs Square to automatically charge a card on file.

  Note

  It's also possible for customers to remit a payment directly to a seller using a credit card, check, cash, or other accepted form of payment. The seller can then record the payment using the Seller Dashboard, Point of Sale (POS) application, or Square Invoices application.

In this walkthrough, you create your customer, order, and invoice resources in the Sandbox. The Sandbox is an isolated server environment provisioned for each Sandbox test account. You should use the Sandbox for testing. For more information, see Square Sandbox.

Invoices define a payment schedule that specifies payment amounts, due dates, and whether Square should send the customer an invoice requesting payment or automatically charge a card on file. You use Sandbox test payment values to test both payment flows:

• Test credit card - For example 1 of this walkthrough, you use a Sandbox credit card to pay an invoice on the Square-hosted invoice payment page.
• Test payment token - To prepare for this walkthrough, you use the Sandbox payment token to add a card on file for a customer. Then, for example 2, you specify the ID of the card on file so Square can charge the card automatically.

Sandbox payment methods are never charged.

You can also use the Sandbox Seller Dashboard to view your Sandbox resources and verify the changes that you make with the Square API.

Follow these steps to get the access token and location ID used in this walkthrough.

1. Sign in to the Developer Dashboard and open your application. If you don't have a Square account, see Get Started to learn how to create an account and an application.

2. Get your Sandbox access token:

   1. At the top of the page, in the Sandbox and Production toggle, choose Sandbox.
   2. On the Credentials page, under Sandbox Access Token, choose Show and then copy the token. All Square API requests require an access token for authorization. This personal access token grants full access to the Sandbox resources in your account.

   Important

   The Sandbox access token is a secure secret. Don't share it with anyone.

3. Get your location ID:

   1. In the left pane, choose Locations.
   2. On the Locations page, keep Default Test Account selected and copy a location ID.

   

   Note

   To retrieve location IDs programmatically, call ListLocations.

To prepare for this walkthrough, you create a customer profile in your Customer Directory and then add a card on file.

1. Call CreateCustomer to create a customer profile with an email address. Square sends invoices and receipts to this email address.

   Replace {ACCESS_TOKEN} with your Sandbox access token and {UNIQUE_KEY} with a unique string. A unique idempotency key guarantees that Square processes a request only once.

   Create customer

   cURL

   The following is an example response:

   {
     "customer":{
       "id": "DJREAYPRBMSSFAB4TGAexample",
       "created_at": "2021-05-30T18:38:16.973Z",
       "updated_at": "2021-05-30T18:38:17Z",
       "given_name": "John",
       "family_name": "Doe",
       "email_address": "[email protected]",
       "preferences": {
         "email_unsubscribed": false
       },
       "creation_source": "THIRD_PARTY",
       "version": 0
     }
   }

2. Copy the customer ID from the response. You use it to save a card on file in the next step and also when you create orders and invoices.

3. Call CreateCard to associate a card on file with the customer profile.

   • Replace {ACCESS_TOKEN} with your Sandbox access token.
   • Replace the example value for customer_id with the customer ID you copied.

   Create card

   cURL

   Note

   For simplicity, this walkthrough uses the Sandbox payment token for source_id. It skips the process of generating a payment token using the Web Payments SDK or In-App Payments SDK. Note that when using the cnon:card-nonce-ok payment token to create a card in the Sandbox, you must specify 94103 as the postal code.

4. Copy the card ID from the response. You use it to define invoice payment requests that automatically charge the card on file.

   To retrieve an existing card ID, you can call ListCards and include the customer_id query parameter.

In this example, you create an order, create an invoice for the order, and then publish the invoice. The invoice settings direct Square to send an invoice to the customer requesting one payment for the full order amount. Then, you pay the invoice on the invoice payment page and retrieve the invoice to verify the payment status.

In this step, you create an order to associate with your invoice. To create the invoice in the next step, you must provide the ID of an order that was created using the Orders API.

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

   • Replace {ACCESS_TOKEN} with your Sandbox access token and {UNIQUE_KEY} with a unique string.
   • Replace the example values for location_id and customer_id with your actual values.

   Create order

   cURL

   The following is an excerpt of the example response:

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

   When you create an invoice, the Invoices API uses the total_money of the associated order to calculate percentage-based payments and ensure that the sum of all invoice payment requests equals the total order amount.

2. Copy the order ID from the response. You use it in the next step to create an invoice.

In this step, you create a draft invoice and then publish it. Square takes no action on an invoice until it's published.

1. Call CreateInvoice to create a draft invoice. The invoice in this example specifies one payment request for the full order amount, due by the specified date. It also enables the credit or debit card payment option on the invoice payment page and directs Square to use email to send invoice-related communication to the customer.

   • Replace {ACCESS_TOKEN} with your Sandbox access token and {UNIQUE_KEY} with a unique string.
   • Replace the example values for order_id and customer_id with your actual values.
   • Replace the example due date with a date in YYYY-MM-DD format.

   Create invoice

   cURL

   The following example response contains the draft invoice:

   {
     "invoice": {
       "id": "inv:0-ChC9tyZuZGGkQ1op9mVTSDexample",
       "version": 0,
       "location_id": "S8GWD5example",
       "order_id": "AdSjVqPCzOAQqvTnzy46VLexample",
       "payment_requests": [
         {
           "uid": "ccc0fc9b-c2a5-42a9-836d-92d01example",
           "request_type": "BALANCE",
           "due_date": "2021-06-30",
           "computed_amount_money": {
             "amount": 100,
             "currency": "USD"
           },
           "total_completed_amount_money": {
             "amount": 0,
             "currency": "USD"
           },
           "automatic_payment_source": "NONE"
         }
       ],
       "invoice_number": "000006",
       "status": "DRAFT",
       "timezone": "America/Los_Angeles",
       "created_at": "2021-05-30T19:01:32Z",
       "updated_at": "2021-05-30T19:01:32Z",
       "primary_recipient": {
         "customer_id": "DJREAYPRBMSSFAB4TGAexample",
         "given_name": "John",
         "family_name": "Doe",
         "email_address": "[email protected]"
       },
       "accepted_payment_methods": {
         "card": true,
         "square_gift_card": false,
         "bank_account": false,
         "buy_now_pay_later": false,
         "cash_app_pay": false
       },
       "delivery_method": "EMAIL",
       "store_payment_method_enabled": false
     }
   }

   Note the following invoice fields:

   • version is 0 because this is the first version of the invoice.
   • status is DRAFT because the invoice hasn't been published.
   • computed_amount_money is the amount due for the payment request.
   • total_completed_amount_money is the amount the customer has paid for the payment request, in this case 0.
   • primary_recipient includes additional customer profile information retrieved by the Invoices API.
   • accepted_payment_methods are the payment methods customers can use to pay the invoice on the invoice payment page.

2. Copy the invoice ID from the response. You use it to publish and retrieve the invoice.

3. Optionally, review the draft invoice in the Sandbox Seller Dashboard as follows:

   1. Sign in to the Developer Dashboard.
   2. On the Sandbox test accounts page, choose Square Dashboard for the Default Test Account. This opens the Sandbox Seller Dashboard associated with the default test account.
   3. In the left pane, choose Payments, and then choose Invoices.
   4. Verify that the unpaid invoice is created and that the status is DRAFT.

4. Call PublishInvoice to publish the draft invoice.

   • Replace {ACCESS_TOKEN} with your Sandbox access token and {UNIQUE_KEY} with a unique string.
   • Replace the example invoice ID in the path with your actual invoice ID.

   Publish invoice

   cURL

   Square generates the invoice page and processes the invoice based on the payment requests, scheduled date, delivery method, and other invoice settings. For more information, see Configuring how Square processes an invoice.

   The following is an example response:

   {
     "invoice": {
       "id": "inv:0-ChC9tyZuZGGkQ1op9mVTSDexample",
       "version": 1,
       "location_id": "S8GWD5example",
       "order_id": "AdSjVqPCzOAQqvTnzy46VLexample",
       "payment_requests": [
         {
           "uid": "ccc0fc9b-c2a5-42a9-836d-92d01example",            
           "request_type": "BALANCE",
           "due_date": "2021-06-30",
           "computed_amount_money": {
             "amount": 100,
             "currency": "USD"
           },
           "total_completed_amount_money": {
             "amount": 0,
             "currency": "USD"
           },
           "automatic_payment_source": "NONE"
         }
       ],
       "invoice_number": "000006",
       "public_url": "https://squareupsandbox.com/pay-invoice/inv:0-ChC9tyZuZGGkQ1op9mVTSDexample",
       "status": "UNPAID",
       "timezone": "America/Los_Angeles",
       "created_at": "2021-05-30T19:01:32Z",
       "updated_at": "2021-05-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": false,
         "bank_account": false,
         "buy_now_pay_later": false,
         "cash_app_pay": false
       },
       "next_payment_amount_money": {
         "amount": 100,
         "currency": "USD"
       },
       "delivery_method": "EMAIL",
       "store_payment_method_enabled": false
     }
   }

   The published invoice has the following changes:

   • version changed to 1.

   • status changed from DRAFT to UNPAID.

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

   • next_payment_amount_money is added to the invoice. This example requests one payment in full, so the amount equals the total order amount. If you request multiple payments, the field shows the amount that is due next based on the payment schedule. If one or more payments are overdue, the field includes the overdue amount. 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.

     The following is an example email sent to the customer. The customer can choose Pay Invoice to open the invoice payment page and make a payment.

     

   Although not supported in the Sandbox environment, Square also emails the invoice to the seller. For more information about invoice-related communication from Square, see Automatic communication from Square.

The customer has the following options to pay the invoice:

• Choose Pay Invoice in the emailed invoice to open the invoice payment page and pay the invoice.
• Contact the seller and pay by credit card, cash, or other accepted payment method. Sellers can record the payment in the Seller Dashboard, POS application, or Square Invoices application.

In this step, you pay the invoice on the invoice payment page.

1. Open the invoice payment page. You can find the page URL in the public_url field in the PublishInvoice response.

2. Use the Sandbox test credit card information to pay the invoice.

3. Call GetInvoice to retrieve the invoice and verify status.

   • Replace {ACCESS_TOKEN} with your Sandbox access token.
   • Replace the example invoice ID in the path with your actual invoice ID.

   Get invoice

   cURL

   If you paid in full, the invoice in the response has the following changes:

   • status is PAID.
   • total_completed_amount_money specifies 100 for the amount paid.
   • next_payment_amount_money is removed from the invoice.

   You can also verify the changes in the Sandbox Seller Dashboard.

In this example, you create an order, create an invoice for the order, and then publish the invoice. The invoice settings direct Square to automatically charge a card on file for a deposit when the invoice is published and a balance at a later date. Then, you retrieve the invoice to verify the payment status.

In this step, you create an order to associate with your invoice. To create the invoice in the next step, you must provide the ID of an order that was created using the Orders API.

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

   • Replace {ACCESS_TOKEN} with your Sandbox access token and {UNIQUE_KEY} with a unique string.
   • Replace the example values for location_id and customer_id with your actual values.

   Create order

   cURL

2. Copy the order ID from the response. You use it in the next step to create an invoice.

In this step, you create a draft invoice and then publish it. Square takes no action on an invoice until it's published.

1. Call CreateInvoice to create a draft invoice. The invoice in this example specifies a deposit payment request for 25% of the order amount and a balance payment request. Both payment requests direct Square to charge a card on file and provide the card ID. The invoice sets the delivery method that Square uses for invoice-related communication with the customer to EMAIL, which is required for automatic payments. It also enables the credit or debit card and Square gift card payment options on the invoice payment page.

   • Replace {ACCESS_TOKEN} with your Sandbox access token and {UNIQUE_KEY} with a unique string.
   • Replace the example values for order_id, customer_id, and card_id with your actual values.
   • Replace the example values for due_date with dates in YYYY-MM-DD format. Use the current date for the deposit (so Square charges the card immediately and you can verify the charge) and a future date for the balance.

   Create invoice

   cURL

   Note

   Instead of specifying percentage-based payment amounts, you can specify exact amounts. The sum of the exact amounts must match the total_money of the order. For more information, see Configuring payment requests.

   The following is an example response:

   {
     "invoice": {
       "id": "inv:0-ChB1vUizal7VFGWas0H1Bexample",
       "version": 0,
       "location_id": "S8GWD5example",
       "order_id": "8NW3YYM7Ho58Ur7k9vkLexample",
       "payment_requests": [
         {
           "uid": "968d4546-3d4b-4be7-8411-cddcbexample",
           "request_type": "DEPOSIT",
           "due_date": "2021-05-30",
           "percentage_requested": "25",
           "card_id": "ccof:aC1D4q9aUXTkexample",
           "computed_amount_money": {
             "amount": 100,
             "currency": "USD"
           },
           "total_completed_amount_money": {
             "amount": 0,
             "currency": "USD"
           },
           "automatic_payment_source": "CARD_ON_FILE"
         },
         {
           "uid": "8e1e2012-c9fc-491b-9545-6380fexample",
           "request_type": "BALANCE",
           "due_date": "2021-06-15",
           "card_id": "ccof:aC1D4q9aUXTkexample",
           "computed_amount_money": {
             "amount": 300,
             "currency": "USD"
           },
           "total_completed_amount_money": {
             "amount": 0,
             "currency": "USD"
           },
           "automatic_payment_source": "CARD_ON_FILE"
         }
       ],
       "invoice_number": "000007",
       "status": "DRAFT",
       "timezone": "America/Los_Angeles",
       "created_at": "2021-05-30T03:09:48Z",
       "updated_at": "2021-05-30T03:09:48Z",
       "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",
       "store_payment_method_enabled": false
     }
   }

   Note the following invoice fields:

   • version is 0 because this is the first version of the invoice.
   • status is DRAFT because the invoice hasn't been published.
   • computed_amount_money is the amount due for each payment request.
   • total_completed_amount_money is the amount the customer has paid for the payment request.
   • accepted_payment_methods are the payment methods customers can use to pay the invoice on the invoice payment page. At least one payment method must be set to true. This setting is independent of any automatic payment requests for the invoice.

   You can review the draft invoice in the Sandbox Seller Dashboard as described in the first walkthrough example.

2. Call PublishInvoice to publish the invoice.

   • Replace {ACCESS_TOKEN} with your Sandbox access token and {UNIQUE_KEY} with a unique string.
   • Replace the example invoice ID in the path with your actual invoice ID.

   Publish invoice

   cURL

   Square generates the invoice page and processes the invoice based on the payment requests, scheduled date, delivery method, and other invoice settings. For more information, see Configuring how Square processes an invoice.

   The following is an example response:

   {
     "invoice": {
       "id": "inv:0-ChB1vUizal7VFGWas0H1Bexample",
       "version": 1,
       "location_id": "S8GWD5example",
       "order_id": "8NW3YYM7Ho58Ur7k9vkLexample",
       "payment_requests": [
         {
           "uid": "968d4546-3d4b-4be7-8411-cddcbexample",
           "request_type": "DEPOSIT",
           "due_date": "2021-05-30",
           "percentage_requested": "25",
           "card_id": "ccof:aC1D4q9aUXTkexample",
           "computed_amount_money": {
             "amount": 100,
             "currency": "USD"
           },
           "total_completed_amount_money": {
             "amount": 0,
             "currency": "USD"
           },
           "automatic_payment_source": "CARD_ON_FILE"
         },
         {
           "uid": "8e1e2012-c9fc-491b-9545-6380fexample",
           "request_type": "BALANCE",
           "due_date": "2021-05-30",
           "card_id": "ccof:aC1D4q9aUXTkexample",
           "computed_amount_money": {
             "amount": 300,
             "currency": "USD"
           },
           "total_completed_amount_money": {
             "amount": 0,
             "currency": "USD"
           },
           "automatic_payment_source": "CARD_ON_FILE"
         }
       ],
       "invoice_number": "000007",
       "public_url": "https://squareupsandbox.com/pay-invoice/inv:0-ChB1vUizal7VFGWas0H1Bexample",
       "status": "UNPAID",
       "timezone": "America/Los_Angeles",
       "created_at": "2021-05-30T03:09:48Z",
       "updated_at": "2021-05-30T03:12:33Z",
       "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
       },
       "next_payment_amount_money": {
         "amount": 100,
         "currency": "USD"
       },
       "delivery_method": "EMAIL",
       "store_payment_method_enabled": false
     }
   }

   The published invoice has the following changes:

   • version is incremented. The value depends on whether Square started processing the payment before returning the response.

   • status changed from DRAFT to UNPAID or PAYMENT_PENDING. The value depends on whether Square started processing the payment before returning the response.

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

   • next_payment_amount_money is added to the invoice.

     Soon after the invoice is published, Square charges the customer's card on file if you specified the current date for the deposit. Square sends an invoice receipt to both the seller and customer (in the Production environment only). If the due date is in the future, the customer can optionally choose Make Early Payment to pay the invoice sooner.

In this step, you verify that Square automatically charged the card on file for the deposit amount.

1. Call GetInvoice to retrieve the invoice and verify status.

   • Replace {ACCESS_TOKEN} with your Sandbox access token.
   • Replace the example invoice ID in the path with your actual invoice ID.

   Get invoice

   cURL

   After Square charges the card for the deposit, the invoice in the response has the following changes:

   • status changed to PARTIALLY_PAID.
   • total_completed_amount_money for the deposit is 100, which equals the computed_amount_money and indicates that the deposit was paid.
   • next_payment_amount_money is 300, which is the amount of the balance payment request.

   You can also verify the changes in the Sandbox Seller Dashboard or on the invoice payment page.

• Retrieve, list, or search invoices
• Create or delete invoice attachments
• Update an invoice
• Cancel or delete an invoice