Use the GetInvoice, ListInvoices, and SearchInvoices endpoints in the Invoices API to retrieve a specific invoice, list invoices at a specific location, and search for invoices at a specific location.
Note
To view itemization and other order information associated with the invoice, call RetrieveOrder in the Orders API using the order_id in the invoice.
To retrieve an invoice by ID, call GetInvoice.
Get invoice
The following is an example response:
{
"invoice": {
"id": "inv:0-ChD_YNSHr4E6FJDariEoAexample",
"version": 1,
"location_id": "S8GWD5example",
"order_id": "IVbTFOMBAGigR3fQYXlRexample",
"payment_requests": [
{
"uid": "b165ffb1-e406-4ad7-bff3-6c216example",
"request_type": "BALANCE",
"due_date": "2022-09-29",
"tipping_enabled": true,
"computed_amount_money": {
"amount": 5000,
"currency": "USD"
},
"total_completed_amount_money": {
"amount": 0,
"currency": "USD"
},
"reminders": [
{
"uid": "65338625-5512-4bc6-9c8b-636aBexample",
"relative_scheduled_days": -1,
"message": "Your payment is due tomorrow.",
"status": "PENDING"
},
{
"uid": "98d9c2b6-35a0-4392-ab5c-bb791example",
"relative_scheduled_days": 3,
"message": "Your payment is overdue.",
"status": "PENDING"
}
],
"automatic_payment_source": "NONE"
}
],
"primary_recipient": {
"customer_id": "PGN6M13PEMX0S3D81NCexample",
"given_name": "Jane",
"family_name": "Doe",
"email_address": "[email protected]",
"phone_number": "1-206-555-1234"
},
"invoice_number": "99846825",
"title": "My Invoice Title",
"public_url": "https://squareupsandbox.com/pay-invoice/inv:0-ChD_YNSHr4E6FJDariEoAexample",
"next_payment_amount_money": {
"amount": 5000,
"currency": "USD"
},
"status": "UNPAID",
"timezone": "America/Los_Angeles",
"created_at": "2022-07-25T14:26:54Z",
"updated_at": "2022-07-25T14:29:02Z",
"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": false
}
}For information about key invoice fields, see Invoice object.
To list invoices, call ListInvoices and specify the required location ID. The following example uses the limit query parameter to specify a maximum page size of three results. The default page size is 100.
List invoices
The following is an excerpt of an example paged response:
{ "invoices": [ { "id": "inv:0-ChCHu2mZEabLeeHahQnXexample", "version": 3, "location_id": "S8GWD5example", "order_id": "IVbTFOMBAGigR3fQYXlbexample", ... }, { "id": "inv:0-ChCBZAO3T41KICmePMAfCexample", "version": 0, "location_id": "S8GWD5example", "order_id": "M3nZRcF6b7MmIPobPKVPexample", ... }, { "id": "inv:0-ChB8ZZei5_Hn7WiK8tGL0example", "version": 1, "location_id": "S8GWD5example", "order_id": "yedFUsE9sEflYGqqnVQgexample", ... } ], "cursor": "PNEhVUKHBuTOuRIZoUcX5VQexample" }
If the response is paged, the response includes a cursor field. To retrieve the next page of results, include the cursor query parameter in the next ListInvoices call, as shown in the following example:
List invoices
To search for invoices at a specified location, call SearchInvoices and provide the location ID. You can optionally provide a customer ID to filter for invoices that belong to a specific customer at the specified location. If you need to get the customer ID, you can search customer profiles by phone number, email address, or other supported attribute.
The following example request filters by a customer and location. Although the location_ids and customer_ids fields are arrays, only a single customer ID and a single location ID can be specified in each filter.
Search invoices
The following is an excerpt of an example response:
{ "invoices": [ { "id": "inv:0-ChBnIWSTQQA57plbuL_nUexample", "version": 4, "location_id": "S8GWD5example", "order_id": "CgoqT20VKa29hwznQgLHexample", ... }, { "id": "inv:0-ChCBZAO3T41KICmePMAfCexample", "version": 0, "location_id": "S8GWD5example", "order_id": "M3nZRcF6b7MmIPobPKVPexample", ... }, ... ] }
The following example request filters by a specific customer and location and sorts the results in order from oldest to newest:
Search invoices
The INVOICE_SORT_DATE sort field works as follows:
- If the invoice is a draft, the invoice
created_atdate is used for sorting. - If the invoice was published and has a
scheduled_atdate, thescheduled_atdate is used for sorting. - If the invoice was published and doesn't have a
scheduled_atdate, the publish date is used for sorting.