Retrieve, List, or Search Invoices

Applies to: Invoices APIInvoices API | Orders APIOrders API | Customers APICustomers API | Payments APIPayments API | Refunds APIRefunds API | Subscriptions APISubscriptions API

Learn how to use Invoices API endpoints to retrieve, list, and search for invoices.

Use the GetInvoiceGetInvoice, ListInvoicesListInvoices, and SearchInvoicesSearchInvoices endpoints in the Invoices APIInvoices API to retrieve a specific invoice, list invoices at a specific location, and search for invoices at a specific location.

ID fields that reference other objects can be used to get itemization details and other information related to the invoice. For more information, see Get related order, payment, and other informationGet related order, payment, and other information.

To retrieve an invoice by ID, call GetInvoiceGetInvoice.

The following is an example response:

{
  "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": "Jane.Doe@example.com",
      "phone_number": "1-206-555-1234"
    },
    "invoice_number": "99846825",
    "title": "My Invoice Title",
    "public_url": "https://squareupsandbox.com/pay-invoice/invtmp:5e22a2c2-47c1-46d6-b061-808764dfe2b9",
    "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,
      "cash_app_pay": false
    },
    "delivery_method": "EMAIL",
    "sale_or_service_date": "2022-08-24",
    "store_payment_method_enabled": false
  }
}

For information about key invoice fields, see Invoice objectInvoice object.

To list invoices, call ListInvoicesListInvoices and specify the required location ID. The following example uses the limit query parameter to specify a maximum page sizepage size of three results. The default page size is 100.

The following is an excerpt of an example paged response:

{
  "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:

To search for invoices at a specified location, call SearchInvoicesSearchInvoices 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. If you need to get the customer ID, you can search customer profilessearch customer profiles by phone number, email address, or other supported attribute.

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.

The following is an excerpt of an example response:

{
  "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:

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 doesn't have a scheduled_at date, the publish date is used for sorting.

An invoice represents a payment schedule for an order and might not contain all the information needed for auditing and reporting. However, you can use invoice fields to retrieve the following related information:

• Goods, services, or pricing associated with the invoice - Call RetrieveOrderRetrieveOrder using the order_id on the invoice and then check the line_items field.

• The customer who received the invoice - Call RetrieveCustomerRetrieveCustomer using the primary_recipient.customer_id on the invoice.

  The customer_id might be different on the invoice, underlying order, and any invoice payments. The customer who created the order can be different than the customer who received the invoice. For invoice payments, Square attempts to infer the customer based on the payment information.

• The payment or refund processed for an invoice payment request - Use the payment ID from the corresponding tender on the underlying order to call GetPaymentGetPayment. To learn how, see Retrieve an invoice paymentRetrieve an invoice payment. Note that an invoice might have multiple payment requests.

  If an invoice payment is refunded, use the refund ID from the payment.refund_ids field to call GetPaymentRefundGetPaymentRefund. A payment might have multiple partial refunds.

• The subscription associated with the invoice - Call RetrieveSubscriptionRetrieveSubscription using the subscription_id on the invoice. This field is present only on recurring subscription billing invoices.

• Invoices APIInvoices API
• API Reference: Invoices APIAPI Reference: Invoices API