--- title: "ListInvoices" method: GET path: "/v2/invoices" tags: ["Invoices"] --- # ListInvoices `GET /v2/invoices` Returns a list of invoices for a given location. 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. ## Query parameters - `location_id` string, required - `cursor` string - `limit` integer ## Response `200` Success - ListInvoicesResponse — Describes a `ListInvoice` response. - `cursor` string — When a response is truncated, it includes a cursor that you can use in a subsequent request to retrieve the next set of invoices. If empty, this is the final response. For more information, see [Pagination](https://developer.squareup.com/docs/working-with-apis/pagination). - `errors` Error[] — Information about errors encountered during the request. - `category` string, required — The high-level category for the error. - `code` string, required — The specific code of the error. - `detail` string — A human-readable description of the error for debugging purposes. - `field` string — The name of the field provided in the original request (if any) that the error pertains to. - `invoices` Invoice[] — The invoices retrieved. - `accepted_payment_methods` InvoiceAcceptedPaymentMethods — The payment methods that customers can use to pay an invoice on the Square-hosted invoice page. - `bank_account` boolean — Indicates whether bank transfer payments are accepted. The default value is `false`. This option is allowed only for invoices that have a single payment request of type `BALANCE`. - `card` boolean — Indicates whether credit card or debit card payments are accepted. The default value is `false`. - `square_gift_card` boolean — Indicates whether Square gift card payments are accepted. The default value is `false`. - `created_at` string — The timestamp when the invoice was created, in RFC 3339 format. - `custom_fields` InvoiceCustomField[] — Additional seller-defined fields to render on the invoice. These fields are visible to sellers and buyers on the Square-hosted invoice page and in emailed or PDF copies of invoices. For more information, see [Custom fields](https://developer.squareup.com/docs/invoices-api/overview#custom-fields). Adding custom fields to an invoice requires an [Invoices Plus subscription](https://developer.squareup.com/docs/invoices-api/overview#invoices-plus-subscription). Max: 2 custom fields - `label` string — The label or title of the custom field. This field is required for a custom field. - `placement` string — The location of the custom field on the invoice. This field is required for a custom field. - `value` string — The text of the custom field. If omitted, only the label is rendered. - `delivery_method` unknown - `description` string — The description of the invoice. This is visible to the customer receiving the invoice. - `id` string — The Square-assigned ID of the invoice. - `invoice_number` string — A user-friendly invoice number. The value is unique within a location. If not provided when creating an invoice, Square assigns a value. It increments from 1 and padded with zeros making it 7 characters long (for example, 0000001 and 0000002). - `location_id` string — The ID of the location that this invoice is associated with. If specified in a `CreateInvoice` request, the value must match the `location_id` of the associated order. - `next_payment_amount_money` Money — Represents an amount of money. `Money` fields can be signed or unsigned. Fields that do not explicitly define whether they are signed or unsigned are considered unsigned and can only hold positive amounts. For signed fields, the sign of the value indicates the purpose of the money transfer. See [Working with Monetary Amounts](https://developer.squareup.com/docs/build-basics/working-with-monetary-amounts) for more information. - `amount` integer — The amount of money, in the smallest denomination of the currency indicated by `currency`. For example, when `currency` is `USD`, `amount` is in cents. Monetary amounts can be positive or negative. See the specific field description to determine the meaning of the sign in a particular case. - `currency` string — The type of currency, in __ISO 4217 format__. For example, the currency code for US dollars is `USD`. See [Currency](https://developer.squareup.com/reference/square_2021-08-18/enums/Currency) for possible values. - `order_id` string — The ID of the [order](https://developer.squareup.com/reference/square_2021-08-18/objects/Order) for which the invoice is created. This field is required when creating an invoice, and the order must be in the `OPEN` state. To view the line items and other information for the associated order, call the [RetrieveOrder](https://developer.squareup.com/reference/square_2021-08-18/orders-api/retrieve-order) endpoint using the order ID. - `payment_requests` InvoicePaymentRequest[] — The payment schedule for the invoice, represented by one or more payment requests that define payment settings, such as amount due and due date. An invoice supports the following payment request combinations: - One balance - One deposit with one balance - 2–12 installments - One deposit with 2–12 installments This field is required when creating an invoice. It must contain at least one payment request. All payment requests for the invoice must equal the total order amount. For more information, see [Payment requests](https://developer.squareup.com/docs/invoices-api/overview#payment-requests). Adding `INSTALLMENT` payment requests to an invoice requires an [Invoices Plus subscription](https://developer.squareup.com/docs/invoices-api/overview#invoices-plus-subscription). - `automatic_payment_source` string — The payment method for an automatic payment. The default value is `NONE`. - `card_id` string — The ID of the credit or debit card on file to charge for the payment request. To get the cards on file for a customer, call [ListCards](https://developer.squareup.com/reference/square_2021-08-18/cards-api/list-cards) and include the `customer_id` of the invoice recipient. - `computed_amount_money` Money — Represents an amount of money. `Money` fields can be signed or unsigned. Fields that do not explicitly define whether they are signed or unsigned are considered unsigned and can only hold positive amounts. For signed fields, the sign of the value indicates the purpose of the money transfer. See [Working with Monetary Amounts](https://developer.squareup.com/docs/build-basics/working-with-monetary-amounts) for more information. - `amount` integer — The amount of money, in the smallest denomination of the currency indicated by `currency`. For example, when `currency` is `USD`, `amount` is in cents. Monetary amounts can be positive or negative. See the specific field description to determine the meaning of the sign in a particular case. - `currency` string — The type of currency, in __ISO 4217 format__. For example, the currency code for US dollars is `USD`. See [Currency](https://developer.squareup.com/reference/square_2021-08-18/enums/Currency) for possible values. - `due_date` string — The due date (in the invoice's time zone) for the payment request, in `YYYY-MM-DD` format. This field is required to create a payment request. After this date, the invoice becomes overdue. For example, a payment `due_date` of 2021-03-09 with a `timezone` of America/Los\_Angeles becomes overdue at midnight on March 9 in America/Los\_Angeles (which equals a UTC timestamp of 2021-03-10T08:00:00Z). - `fixed_amount_requested_money` Money — Represents an amount of money. `Money` fields can be signed or unsigned. Fields that do not explicitly define whether they are signed or unsigned are considered unsigned and can only hold positive amounts. For signed fields, the sign of the value indicates the purpose of the money transfer. See [Working with Monetary Amounts](https://developer.squareup.com/docs/build-basics/working-with-monetary-amounts) for more information. - `amount` integer — The amount of money, in the smallest denomination of the currency indicated by `currency`. For example, when `currency` is `USD`, `amount` is in cents. Monetary amounts can be positive or negative. See the specific field description to determine the meaning of the sign in a particular case. - `currency` string — The type of currency, in __ISO 4217 format__. For example, the currency code for US dollars is `USD`. See [Currency](https://developer.squareup.com/reference/square_2021-08-18/enums/Currency) for possible values. - `percentage_requested` string — Specifies the amount for the payment request in percentage: - When the payment `request_type` is `DEPOSIT`, it is the percentage of the order's total amount. - When the payment `request_type` is `INSTALLMENT`, it is the percentage of the order's total less the deposit, if requested. The sum of the `percentage_requested` in all installment payment requests must be equal to 100. You cannot specify this when the payment `request_type` is `BALANCE` or when the payment request specifies the `fixed_amount_requested_money` field. - `reminders` InvoicePaymentReminder[] — A list of one or more reminders to send for the payment request. - `message` string — The reminder message. - `relative_scheduled_days` integer — The number of days before (a negative number) or after (a positive number) the payment request `due_date` when the reminder is sent. For example, -3 indicates that the reminder should be sent 3 days before the payment request `due_date`. - `sent_at` string — If sent, the timestamp when the reminder was sent, in RFC 3339 format. - `status` string — The status of the reminder. - `uid` string — A Square-assigned ID that uniquely identifies the reminder within the `InvoicePaymentRequest`. - `request_method` string — Indicates how Square processes the payment request. DEPRECATED at version 2021-01-21. Replaced by the `Invoice.delivery_method` and `InvoicePaymentRequest.automatic_payment_source` fields. One of the following is required when creating an invoice: - (Recommended) The `delivery_method` field of the invoice. To configure an automatic payment, the `automatic_payment_source` field of the payment request is also required. - This `request_method` field. Note that `invoice` objects returned in responses do not include `request_method`. - `request_type` string — Identifies the payment request type. This type defines how the payment request amount is determined. This field is required to create a payment request. - `rounding_adjustment_included_money` Money — Represents an amount of money. `Money` fields can be signed or unsigned. Fields that do not explicitly define whether they are signed or unsigned are considered unsigned and can only hold positive amounts. For signed fields, the sign of the value indicates the purpose of the money transfer. See [Working with Monetary Amounts](https://developer.squareup.com/docs/build-basics/working-with-monetary-amounts) for more information. - `amount` integer — The amount of money, in the smallest denomination of the currency indicated by `currency`. For example, when `currency` is `USD`, `amount` is in cents. Monetary amounts can be positive or negative. See the specific field description to determine the meaning of the sign in a particular case. - `currency` string — The type of currency, in __ISO 4217 format__. For example, the currency code for US dollars is `USD`. See [Currency](https://developer.squareup.com/reference/square_2021-08-18/enums/Currency) for possible values. - `tipping_enabled` boolean — If set to true, the Square-hosted invoice page (the `public_url` field of the invoice) provides a place for the customer to pay a tip. This field is allowed only on the final payment request and the payment `request_type` must be `BALANCE` or `INSTALLMENT`. - `total_completed_amount_money` Money — Represents an amount of money. `Money` fields can be signed or unsigned. Fields that do not explicitly define whether they are signed or unsigned are considered unsigned and can only hold positive amounts. For signed fields, the sign of the value indicates the purpose of the money transfer. See [Working with Monetary Amounts](https://developer.squareup.com/docs/build-basics/working-with-monetary-amounts) for more information. - `amount` integer — The amount of money, in the smallest denomination of the currency indicated by `currency`. For example, when `currency` is `USD`, `amount` is in cents. Monetary amounts can be positive or negative. See the specific field description to determine the meaning of the sign in a particular case. - `currency` string — The type of currency, in __ISO 4217 format__. For example, the currency code for US dollars is `USD`. See [Currency](https://developer.squareup.com/reference/square_2021-08-18/enums/Currency) for possible values. - `uid` string — The Square-generated ID of the payment request in an [invoice](https://developer.squareup.com/reference/square_2021-08-18/objects/Invoice). - `primary_recipient` InvoiceRecipient — Provides customer data that Square uses to deliver an invoice. - `address` Address — Represents a postal address in a country. The address format is based on an [open-source library from Google](https://github.com/google/libaddressinput). For more information, see [AddressValidationMetadata](https://github.com/google/libaddressinput/wiki/AddressValidationMetadata). This format has dedicated fields for four address components: postal code, locality (city), administrative district (state, prefecture, or province), and sublocality (town or village). These components have dedicated fields in the `Address` object because software sometimes behaves differently based on them. For example, sales tax software may charge different amounts of sales tax based on the postal code, and some software is only available in certain states due to compliance reasons. For the remaining address components, the `Address` type provides the `address_line_1` and `address_line_2` fields for free-form data entry. These fields are free-form because the remaining address components have too many variations around the world and typical software does not parse these components. These fields enable users to enter anything they want. Note that, in the current implementation, all other `Address` type fields are blank. These include `address_line_3`, `sublocality_2`, `sublocality_3`, `administrative_district_level_2`, `administrative_district_level_3`, `first_name`, `last_name`, and `organization`. When it comes to localization, the seller's language preferences (see [Language preferences](https://developer.squareup.com/docs/locations-api#location-specific-and-seller-level-language-preferences)) are ignored for addresses. Even though Square products (such as Square Point of Sale and the Seller Dashboard) mostly use a seller's language preference in communication, when it comes to addresses, they will use English for a US address, Japanese for an address in Japan, and so on. - `address_line_1` string — The first line of the address. Fields that start with `address_line` provide the address's most specific details, like street number, street name, and building name. They do *not* provide less specific details like city, state/province, or country (these details are provided in other fields). - `address_line_2` string — The second line of the address, if any. - `address_line_3` string — The third line of the address, if any. - `administrative_district_level_1` string — A civil entity within the address's country. In the US, this is the state. - `administrative_district_level_2` string — A civil entity within the address's `administrative_district_level_1`. In the US, this is the county. - `administrative_district_level_3` string — A civil entity within the address's `administrative_district_level_2`, if any. - `country` string — The address's country, in ISO 3166-1-alpha-2 format. - `first_name` string — Optional first name when it's representing recipient. - `last_name` string — Optional last name when it's representing recipient. - `locality` string — The city or town of the address. - `organization` string — Optional organization name when it's representing recipient. - `postal_code` string — The address's postal code. - `sublocality` string — A civil region within the address's `locality`, if any. - `sublocality_2` string — A civil region within the address's `sublocality`, if any. - `sublocality_3` string — A civil region within the address's `sublocality_2`, if any. - `company_name` string — The name of the recipient's company. - `customer_id` string — The ID of the customer. This is the customer profile ID that you provide when creating a draft invoice. - `email_address` string — The recipient's email address. - `family_name` string — The recipient's family (that is, last) name. - `given_name` string — The recipient's given (that is, first) name. - `phone_number` string — The recipient's phone number. - `public_url` string — The URL of the Square-hosted invoice page. After you publish the invoice using the `PublishInvoice` endpoint, Square hosts the invoice page and returns the page URL in the response. - `scheduled_at` string — The timestamp when the invoice is scheduled for processing, in RFC 3339 format. After the invoice is published, Square processes the invoice on the specified date, according to the delivery method and payment request settings. If the field is not set, Square processes the invoice immediately after it is published. - `status` string — The status of the invoice. - `subscription_id` string — The ID of the [subscription](https://developer.squareup.com/reference/square_2021-08-18/objects/Subscription) associated with the invoice. This field is present only on subscription billing invoices. - `timezone` string — The time zone used to interpret calendar dates on the invoice, such as `due_date`. When an invoice is created, this field is set to the `timezone` specified for the seller location. The value cannot be changed. For example, a payment `due_date` of 2021-03-09 with a `timezone` of America/Los\_Angeles becomes overdue at midnight on March 9 in America/Los\_Angeles (which equals a UTC timestamp of 2021-03-10T08:00:00Z). - `title` string — The title of the invoice. - `updated_at` string — The timestamp when the invoice was last updated, in RFC 3339 format. - `version` integer — The Square-assigned version number, which is incremented each time an update is committed to the invoice. --- [API](https://skmtc.net/square/apis/squareup.md) · [All operations](https://skmtc.net/square/apis/squareup/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/square/squareup/revisions/8d95e3639487/schema)