Search invoices
Searches for invoices from a location specified in the filter.
You can optionally specify customers in the filter for whom to retrieve invoices. In the current implementation, you can only specify one location and optionally one customer.
The response is paginated. If truncated, the response includes a cursor
that you use in a subsequent request to retrieve the next set of invoices.
| Name | Description |
|---|---|
query
Required
|
Describes the query criteria for searching invoices. |
limit
|
The maximum number of invoices to return (200 is the maximum |
cursor
|
A pagination cursor returned by a previous call to this endpoint. Provide this cursor to retrieve the next set of results for your original query. For more information, see Pagination. |
Response Fields
| Name | Description |
|---|---|
invoices
|
The list of invoices returned by the search. |
cursor
|
When a response is truncated, it includes a cursor that you can use in a subsequent request to fetch the next set of invoices. If empty, this is the final response. For more information, see Pagination. |
errors
|
Information about errors encountered during the request. |
Examples
- cURL
- Ruby
- Python
- C#
- Java
- PHP
- Node.js
curl https://connect.squareup.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": [
"ES0RJRZYEC39A"
],
"customer_ids": [
"JDKYHBWT1D4F8MFH63DBMEN8Y4"
]
},
"sort": {
"field": "INVOICE_SORT_DATE",
"order": "DESC"
},
"limit": 100
}
}'{
"invoices": [
{
"id": "inv:0-ChCHu2mZEabLeeHahQnXDjZQECY",
"version": 0,
"location_id": "ES0RJRZYEC39A",
"order_id": "CAISENgvlJ6jLWAzERDzjyHVybY",
"payment_requests": [
{
"uid": "2da7964f-f3d2-4f43-81e8-5aa220bf3355",
"request_type": "BALANCE",
"due_date": "2030-01-24",
"tipping_enabled": true,
"reminders": [
{
"uid": "beebd363-e47f-4075-8785-c235aaa7df11",
"relative_scheduled_days": -1,
"message": "Your invoice is due tomorrow",
"status": "PENDING"
}
],
"computed_amount_money": {
"amount": 10000,
"currency": "USD"
},
"total_completed_amount_money": {
"amount": 0,
"currency": "USD"
},
"automatic_payment_source": "NONE"
}
],
"invoice_number": "inv-100",
"title": "Event Planning Services",
"description": "We appreciate your business!",
"scheduled_at": "2030-01-13T10:00:00Z",
"status": "DRAFT",
"timezone": "America/Los_Angeles",
"created_at": "2020-06-18T17:45:13Z",
"updated_at": "2020-06-18T17:45:13Z",
"primary_recipient": {
"customer_id": "JDKYHBWT1D4F8MFH63DBMEN8Y4",
"given_name": "Amelia",
"family_name": "Earhart",
"email_address": "[email protected]",
"phone_number": "1-212-555-4240"
},
"accepted_payment_methods": {
"card": true,
"square_gift_card": false,
"bank_account": false,
"buy_now_pay_later": false
},
"custom_fields": [
{
"label": "Event Reference Number",
"value": "Ref. #1234",
"placement": "ABOVE_LINE_ITEMS"
},
{
"label": "Terms of Service",
"value": "The terms of service are...",
"placement": "BELOW_LINE_ITEMS"
}
],
"delivery_method": "EMAIL",
"sale_or_service_date": "2030-01-24",
"store_payment_method_enabled": false
},
{
"id": "inv:0-ChC366qAfskpGrBI_1bozs9mEA3",
"version": 3,
"location_id": "ES0RJRZYEC39A",
"order_id": "a65jnS8NXbfprvGJzY9F4fQTuaB",
"payment_requests": [
{
"uid": "66c3bdfd-5090-4ff9-a8a0-c1e1a2ffa176",
"request_type": "DEPOSIT",
"due_date": "2021-01-23",
"percentage_requested": "25",
"tipping_enabled": false,
"card_id": "ccof:IkWfpLj4tNHMyFii3GB",
"computed_amount_money": {
"amount": 1000,
"currency": "USD"
},
"total_completed_amount_money": {
"amount": 1000,
"currency": "USD"
},
"automatic_payment_source": "CARD_ON_FILE"
},
{
"uid": "120c5e18-4f80-4f6b-b159-774cb9bf8f99",
"request_type": "BALANCE",
"due_date": "2021-06-15",
"tipping_enabled": false,
"card_id": "ccof:IkWfpLj4tNHMyFii3GB",
"computed_amount_money": {
"amount": 3000,
"currency": "USD"
},
"total_completed_amount_money": {
"amount": 0,
"currency": "USD"
},
"automatic_payment_source": "CARD_ON_FILE"
}
],
"invoice_number": "inv-455",
"public_url": "https://squareup.com/pay-invoice/h9sfsfTGTSnYEhISUDBhEQ",
"status": "PARTIALLY_PAID",
"timezone": "America/Los_Angeles",
"created_at": "2021-01-23T15:29:12Z",
"updated_at": "2021-01-23T15:29:56Z",
"primary_recipient": {
"customer_id": "JDKYHBWT1D4F8MFH63DBMEN8Y4",
"given_name": "Amelia",
"family_name": "Earhart",
"email_address": "[email protected]",
"phone_number": "1-212-555-4240"
},
"next_payment_amount_money": {
"amount": 3000,
"currency": "USD"
},
"accepted_payment_methods": {
"card": true,
"square_gift_card": true,
"bank_account": false,
"buy_now_pay_later": false
},
"delivery_method": "EMAIL",
"sale_or_service_date": "2030-01-24",
"store_payment_method_enabled": false
}
],
"cursor": "ChoIDhIWVm54ZVRhLXhySFBOejBBM2xJb2daUQoFCI4IGAE"
}