Development
  • Guides
  • API Reference
  • API Explorer
  • SDKs
  • Sample apps
  • System status
Support
  • Developer forums
  • Developer blog
  • YouTube
  • X
More
  • Square Home
  • Square Developer
  • App Marketplace
  • Partner with Square
  • Solutions Partner Program
  • Pricing
  • Sales

© 2026 Square, Inc.

  • Developer terms of service
  • Developer Integration and Marketing Agreement
  • Privacy policy
  • Partnerships
  • Sign In
  • Sign In

    Invoices

  • List invoices

  • Create invoice

  • Search invoices

  • Delete invoice

  • Get invoice

  • Update invoice

  • Create invoice attachment

  • Delete invoice attachment

  • Cancel invoice

  • Publish invoice

  • Webhooks

  • invoice.canceled

  • invoice.created

  • invoice.deleted

  • invoice.payment_made

  • invoice.published

  • invoice.refunded

  • invoice.scheduled_charge_failed

  • invoice.updated

<- Invoices API

Invoices API

All versions ->

List invoices

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.

Permissions:INVOICES_READ

Guide

List invoices

Try in API Explorer
Link to section

Query parameters

Example code

Link to section

location_id

string

Required

The ID of the location for which to list invoices.

Link to section

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.

Link to section

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.

Link to section

Response fields

Link to section

invoices

The invoices retrieved.

Link to section

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.

Link to section

errors

Information about errors encountered during the request.

Link to section

Examples

All versions ->

GET /v2/invoices
curl https://connect.squareup.com/v2/invoices?location_id=ES0RJRZYEC39A&limit=2 \ -H 'Square-Version: 2026-11-18' \ -H 'Authorization: Bearer ACCESS_TOKEN' \ -H 'Content-Type: application/json'

Response JSON

{ "invoices": [ { "id": "inv:0-ChCHu2mZEabLeeHahQnXDjZQECY", "version": 1, "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": "2030-01-13T17:45:13Z", "updated_at": "2030-01-13T21:24:10Z", "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, "cash_app_pay": 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, "attachments": [ { "id": "inva:0-3bB9ZuDHiziThQhuC4fwWt", "filename": "file.jpg", "description": "Service contract", "filesize": 102705, "hash": "273ee02cb6f5f8a3a8ca23604930dd53", "mime_type": "image/jpeg", "uploaded_at": "2030-01-13T21:24:10Z" } ] }, { "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/invtmp:5e22a2c2-47c1-46d6-b061-808764dfe2b9", "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, "cash_app_pay": false }, "delivery_method": "EMAIL", "sale_or_service_date": "2030-01-24", "store_payment_method_enabled": false } ], "cursor": "ChoIDhIWVm54ZVRhLXhySFBOejBBM2xJb2daUQoFCI4IGAE" }