Learn how to use the GetInvoice, ListInvoices, and SearchInvoices endpoints in the Square Invoices API to retrieve or search for invoices.
Invoices API

Retrieve, List, or Search 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.

Note

To view itemization and other order information associated with the invoice, call RetrieveOrder in the Orders API using the order_id in the invoice.

To retrieve an invoice by ID, call GetInvoice.

Get Invoice
  • 1
  • 2
  • 3
  • 4
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:

  • 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.

List Invoices
  • 1
  • 2
  • 3
  • 4
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:

  • 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:

List Invoices
  • 1
  • 2
  • 3
  • 4
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.

Search Invoices
  • 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:

The following example request filters by a specific customer and location and sorts the results in order from oldest to newest:

Search Invoices
  • 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.