Applies to: Invoices API | Orders API | Customers API | Payments API | Refunds API | Subscriptions API
Learn how to use Invoices API endpoints to retrieve, list, and search for invoices.
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.
ID fields that reference other objects can be used to get itemization details and other information related to the invoice. For more information, see Get related order, payment, and other information.
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_at
date is used for sorting. - If the invoice was published and has a
scheduled_at
date, thescheduled_at
date is used for sorting. - If the invoice was published and doesn't have a
scheduled_at
date, the publish date is used for sorting.
An invoice represents a payment schedule for an order and might not contain all the information needed for auditing and reporting. However, you can use invoice fields to retrieve the following related information:
Goods, services, or pricing associated with the invoice - Call RetrieveOrder using the
order_id
on the invoice and then check theline_items
field.The customer who received the invoice - Call RetrieveCustomer using the
primary_recipient.customer_id
on the invoice.The
customer_id
might be different on the invoice, underlying order, and any invoice payments. The customer who created the order can be different than the customer who received the invoice. For invoice payments, Square attempts to infer the customer based on the payment information.The payment or refund processed for an invoice payment request - Use the payment ID from the corresponding tender on the underlying order to call GetPayment. To learn how, see Retrieve an invoice payment. Note that an invoice might have multiple payment requests.
If an invoice payment is refunded, use the refund ID from the
payment.refund_ids
field to call GetPaymentRefund. A payment might have multiple partial refunds.The subscription associated with the invoice - Call RetrieveSubscription using the
subscription_id
on the invoice. This field is present only on recurring subscription billing invoices.