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 in the Orders API using the 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
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
{
"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 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.
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
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
{
"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 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.
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.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
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
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
{
"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:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
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.