• Example searches: “transaction”, “CreateOrder”, “/v2/locations”, “inventory”, “delete customer”

You are viewing an old version of the API
Search invoices

POST /v2/invoices/search

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.


Permissions
INVOICES_READ
Guide
Search invoices
Try in API Explorer
Name Description
query
InvoiceQuery

Required

Describes the query criteria for searching invoices.

limit
integer (32-bit)

The maximum number of invoices to return (200 is the maximum limit). If not provided, the server uses a default limit of 100 invoices.

cursor
string

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
Invoice [ ]

The list of invoices returned by the search.

cursor
string

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
Error [ ]

Information about errors encountered during the request.

Examples

You are viewing an old version of the API
POST /v2/invoices/search
cURL
  • 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
    }
  }'
Response JSON
{
  "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"
}