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.
To view itemization and other order information associated with the invoice, call RetrieveOrder order_id in the invoice.
Retrieve an invoice by ID
To retrieve an invoice by ID, call GetInvoice
curl https://connect.squareupsandbox.com/v2/invoices/{invoice_id} \
-H 'Square-Version: 2023-03-15' \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'Content-Type: application/json'
The following is an example response:
Copy
123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566
{
"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
},
"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 limit query parameter to specify a maximum page size
curl https://connect.squareupsandbox.com/v2/invoices?location_id=S8GWD5example&limit =3 \
-H 'Square-Version: 2023-03-15' \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'Content-Type: application/json'
The following is an excerpt of an example paged response:
Copy
1234567891011121314151617181920212223242526
{
"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:
curl https://connect.squareupsandbox.com/v2/invoices?location_id=S8GWD5example&limit =3&cursor=PNEhVUKHBuTOuRIZoUcX5VQexample \
-H 'Square-Version: 2023-03-15' \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'Content-Type: application/json'
To search for invoices at a specified location, call SearchInvoices
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.
1234567891011121314151617
curl https://connect.squareupsandbox.com/v2/invoices/search \
-X POST \
-H 'Square-Version: 2023-03-15' \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'Content-Type: application/json' \
-d '{
"query": {
"filter": {
"location_ids": [
"S8GWD5example"
],
"customer_ids": [
"HXJKX5BBKGWX34XEMS2example"
]
}
}
}'
The following is an excerpt of an example response:
Copy
12345678910111213141516171819
{
"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:
123456789101112131415161718192021
curl https://connect.squareupsandbox.com/v2/invoices/search \
-X POST \
-H 'Square-Version: 2023-03-15' \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'Content-Type: application/json' \
-d '{
"query": {
"filter": {
"location_ids": [
"S8GWD5example"
],
"customer_ids": [
"HXJKX5BBKGWX34XEMS2example"
]
}
},
"sort": {
"field": "INVOICE_SORT_DATE",
"order": "ASC"
}
}'
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, the scheduled_at date is used for sorting.
If the invoice was published and does not have a scheduled_at date, the publish date is used for sorting.