A reference guide for building AI agents: every method, how to authenticate, and the permissions each one needs.
The Square API is how an app or AI agent works with a Square seller account: taking a payment, refunding a charge, creating an order, updating a customer, or changing the catalog and stock. Access is granted through an OAuth access token carrying named permissions, each split into a read and a write form, so a call reaches only the areas the seller approved. Square versions its API by date, and a state change emits an event Square can deliver to a subscribed webhook URL.
How an app or AI agent connects to Square determines what it can reach. There is a route for making calls, a route for receiving events, and a hosted server that exposes Square tools to agents, and each is governed by the token behind it and the permissions that token carries.
The REST API answers at https://connect.squareup.com/v2 in production and https://connect.squareupsandbox.com/v2 in sandbox. A call authenticates with an OAuth access token as a Bearer token, sends and returns JSON, and a Square-Version header on each request selects the dated API version.
Square POSTs event notifications to an HTTPS URL subscribed to the chosen event types, like payment.created or order.updated. The receiver verifies the x-square-hmacsha256-signature header, an HMAC-SHA256 of the notification URL and the raw body computed with the subscription's signature key, to confirm the request came from Square.
Square's hosted Model Context Protocol server at https://mcp.squareup.com/sse exposes the Square API platform to AI agents, covering payments, orders, customers, items, and more. The remote server uses OAuth login for granular permissions, and a local server authenticates with an access token. It is in Beta, and its source is at github.com/square/square-mcp-server.
Square uses the OAuth 2.0 authorization-code flow. A seller is sent to the authorization page with the set of permissions the app needs, and the returned code is exchanged for an access token tied to that seller and those permissions. This is the route for an integration acting on accounts it does not own.
Each Square application provides a personal access token in the Developer Dashboard that calls the API for the developer's own account, with all of the application's permissions. It suits internal tools and testing, not access to other sellers' accounts.
The Square API is split into areas an agent can act on, like payments, orders, customers, catalog, inventory, refunds, and invoices. Each area has its own methods and its own permission, and writes in some areas move real money or change a live catalog.
List, create, retrieve, update, cancel, and complete payments.
List refunds, refund a payment, and retrieve a single refund.
Create, retrieve, update, search, clone, and pay for orders.
List, create, search, retrieve, update, and delete customer profiles.
List, upsert, retrieve, search, and delete catalog objects and items.
Retrieve stock counts, apply adjustments and counts, and read inventory history.
List, create, search, retrieve, update, delete, publish, and cancel invoices.
Filter by method, access, or permission, or search any path. Select a row for version detail, rate limits, the related webhook event, and the source.
| Method | Endpoint | What it does | Access | Permission | Version | |
|---|---|---|---|---|---|---|
PaymentsList, create, retrieve, update, cancel, and complete payments.6 | ||||||
| GET | /v2/payments | Retrieve a list of payments taken by the account making the request. | read | PAYMENTS_READ | Current | |
Read-only. Grants access to payment and refund data. Acts onpayment Permission (capability) PAYMENTS_READVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v2/payments | Create a payment using the provided payment source. | write | PAYMENTS_WRITE | Current | |
Takes a real payment. Adding additional recipients also needs PAYMENTS_WRITE_ADDITIONAL_RECIPIENTS. Acts onpayment Permission (capability) PAYMENTS_WRITEVersionAvailable since the API’s base version Webhook event payment.createdRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v2/payments/{payment_id} | Retrieve details for a specific payment. | read | PAYMENTS_READ | Current | |
Read-only. Acts onpayment Permission (capability) PAYMENTS_READVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PUT | /v2/payments/{payment_id} | Update a payment that has the APPROVED status. | write | PAYMENTS_WRITE | Current | |
Only an approved, uncaptured payment can be updated. Acts onpayment Permission (capability) PAYMENTS_WRITEVersionAvailable since the API’s base version Webhook event payment.updatedRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v2/payments/{payment_id}/cancel | Cancel (void) a payment that is in an approved, uncaptured state. | write | PAYMENTS_WRITE | Current | |
Releases the held authorization without capturing funds. Acts onpayment Permission (capability) PAYMENTS_WRITEVersionAvailable since the API’s base version Webhook event payment.updatedRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v2/payments/{payment_id}/complete | Complete (capture) a payment that was authorized with delayed capture. | write | PAYMENTS_WRITE | Current | |
Captures the held funds for an approved payment. Acts onpayment Permission (capability) PAYMENTS_WRITEVersionAvailable since the API’s base version Webhook event payment.updatedRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
RefundsList refunds, refund a payment, and retrieve a single refund.3 | ||||||
| GET | /v2/refunds | Retrieve a list of refunds for the account making the request. | read | PAYMENTS_READ | Current | |
Read-only. Refund data is covered by the payments permission. Acts onrefund Permission (capability) PAYMENTS_READVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v2/refunds | Refund a payment, fully or partially. | write | PAYMENTS_WRITE | Current | |
Returns real money. Refunding is part of the payments write permission. Acts onrefund Permission (capability) PAYMENTS_WRITEVersionAvailable since the API’s base version Webhook event refund.createdRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v2/refunds/{refund_id} | Retrieve a specific refund using its refund_id. | read | PAYMENTS_READ | Current | |
Read-only. Acts onrefund Permission (capability) PAYMENTS_READVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
OrdersCreate, retrieve, update, search, clone, and pay for orders.6 | ||||||
| POST | /v2/orders | Create a new order that can include products, taxes, and discounts. | write | ORDERS_WRITE | Current | |
A core write. Acts onorder Permission (capability) ORDERS_WRITEVersionAvailable since the API’s base version Webhook event order.createdRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v2/orders/{order_id} | Retrieve a single order by its ID. | read | ORDERS_READ | Current | |
Read-only. Acts onorder Permission (capability) ORDERS_READVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PUT | /v2/orders/{order_id} | Update an open order by adding, replacing, or deleting fields. | write | ORDERS_WRITE | Current | |
Only an open order can be updated, using a sparse update and a version for optimistic concurrency. Acts onorder Permission (capability) ORDERS_WRITEVersionAvailable since the API’s base version Webhook event order.updatedRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v2/orders/search | Search all orders for one or more locations. | read | ORDERS_READ | Current | |
Read-only. Search uses POST to carry a query body. Acts onorder Permission (capability) ORDERS_READVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v2/orders/{order_id}/pay | Pay for an order using one or more approved payments. | write | ORDERS_WRITE | Current | |
Also needs PAYMENTS_WRITE, because it captures the linked payments. Acts onorder Permission (capability) ORDERS_WRITEVersionAvailable since the API’s base version Webhook event order.updatedRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v2/orders/clone | Create a new order in the DRAFT state by duplicating an existing order. | write | ORDERS_WRITE | Current | |
The clone starts as a draft and is not yet payable. Acts onorder Permission (capability) ORDERS_WRITEVersionAvailable since the API’s base version Webhook event order.createdRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
CustomersList, create, search, retrieve, update, and delete customer profiles.6 | ||||||
| GET | /v2/customers | List customer profiles associated with a Square account. | read | CUSTOMERS_READ | Current | |
Read-only. Acts oncustomer Permission (capability) CUSTOMERS_READVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v2/customers | Create a new customer profile. | write | CUSTOMERS_WRITE | Current | |
A core write. Acts oncustomer Permission (capability) CUSTOMERS_WRITEVersionAvailable since the API’s base version Webhook event customer.createdRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v2/customers/search | Search customer profiles using one or more supported query filters. | read | CUSTOMERS_READ | Current | |
Read-only. Search uses POST to carry a query body. Acts oncustomer Permission (capability) CUSTOMERS_READVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v2/customers/{customer_id} | Return details for a single customer. | read | CUSTOMERS_READ | Current | |
Read-only. Acts oncustomer Permission (capability) CUSTOMERS_READVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PUT | /v2/customers/{customer_id} | Update an existing customer profile. | write | CUSTOMERS_WRITE | Current | |
A core write. Acts oncustomer Permission (capability) CUSTOMERS_WRITEVersionAvailable since the API’s base version Webhook event customer.updatedRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /v2/customers/{customer_id} | Delete a customer profile from a business. | write | CUSTOMERS_WRITE | Current | |
Permanently removes the profile. Acts oncustomer Permission (capability) CUSTOMERS_WRITEVersionAvailable since the API’s base version Webhook event customer.deletedRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
CatalogList, upsert, retrieve, search, and delete catalog objects and items.5 | ||||||
| GET | /v2/catalog/list | Return a list of all catalog objects of the specified types. | read | ITEMS_READ | Current | |
Read-only. Acts oncatalog object Permission (capability) ITEMS_READVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v2/catalog/object | Create a new or update a specified catalog object. | write | ITEMS_WRITE | Current | |
A core catalog write. Acts oncatalog object Permission (capability) ITEMS_WRITEVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v2/catalog/object/{object_id} | Return a single catalog object based on the provided ID. | read | ITEMS_READ | Current | |
Read-only. Acts oncatalog object Permission (capability) ITEMS_READVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v2/catalog/search | Search for catalog objects by matching query filter attributes. | read | ITEMS_READ | Current | |
Read-only. Search uses POST to carry a query body. Acts oncatalog object Permission (capability) ITEMS_READVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /v2/catalog/object/{object_id} | Delete a single catalog object based on the provided ID. | write | ITEMS_WRITE | Current | |
Deletes the object and its children, like the variations under an item. Acts oncatalog object Permission (capability) ITEMS_WRITEVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
InventoryRetrieve stock counts, apply adjustments and counts, and read inventory history.3 | ||||||
| GET | /v2/inventory/{catalog_object_id} | Retrieve the current calculated stock count for a catalog object at a set of locations. | read | INVENTORY_READ | Current | |
Read-only. Acts oninventory count Permission (capability) INVENTORY_READVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v2/inventory/changes/batch-create | Apply adjustments and counts to the provided item quantities. | write | INVENTORY_WRITE | Current | |
Changes real stock counts. Acts oninventory change Permission (capability) INVENTORY_WRITEVersionAvailable since the API’s base version Webhook event inventory.count.updatedRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v2/inventory/counts/batch-retrieve | Return current counts for the provided catalog objects at the requested locations. | read | INVENTORY_READ | Current | |
Read-only. Uses POST to carry the list of object IDs. Acts oninventory count Permission (capability) INVENTORY_READVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
InvoicesList, create, search, retrieve, update, delete, publish, and cancel invoices.6 | ||||||
| GET | /v2/invoices | Return a list of invoices for a given location. | read | INVOICES_READ | Current | |
Read-only. A location_id query parameter is required. Acts oninvoice Permission (capability) INVOICES_READVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v2/invoices | Create a draft invoice for an order created with the Orders API. | write | INVOICES_WRITE | Current | |
Starts as a draft until it is published. Acts oninvoice Permission (capability) INVOICES_WRITEVersionAvailable since the API’s base version Webhook event invoice.createdRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v2/invoices/{invoice_id} | Retrieve an invoice by its invoice ID. | read | INVOICES_READ | Current | |
Read-only. Acts oninvoice Permission (capability) INVOICES_READVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PUT | /v2/invoices/{invoice_id} | Modify an existing invoice. | write | INVOICES_WRITE | Current | |
A version is required for optimistic concurrency. Acts oninvoice Permission (capability) INVOICES_WRITEVersionAvailable since the API’s base version Webhook event invoice.updatedRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v2/invoices/{invoice_id}/publish | Publish a draft invoice, which can send it to the customer. | write | INVOICES_WRITE | Current | |
Publishing can email or charge the customer, depending on the delivery method. Acts oninvoice Permission (capability) INVOICES_WRITEVersionAvailable since the API’s base version Webhook event invoice.publishedRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v2/invoices/{invoice_id}/cancel | Cancel an invoice that is not in a terminal state. | write | INVOICES_WRITE | Current | |
Stops any further payment on the invoice. Acts oninvoice Permission (capability) INVOICES_WRITEVersionAvailable since the API’s base version Webhook event invoice.updatedRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Square can notify an app or AI agent when something happens in an account, like a payment being created or an order being updated, instead of the app repeatedly asking. Square posts the event to a notification URL that has been subscribed to the chosen event types.
| Event | What it signals | Triggered by |
|---|---|---|
payment.created | A payment was created. | /v2/payments |
payment.updated | A field on a payment was updated, including when it is canceled or completed. | /v2/payments/{payment_id}/v2/payments/{payment_id}/cancel/v2/payments/{payment_id}/complete |
refund.created | A refund was created. | /v2/refunds |
order.created | An order was created. | /v2/orders/v2/orders/clone |
order.updated | An order was updated, including when it is paid. | /v2/orders/{order_id}/v2/orders/{order_id}/pay/v2/invoices/{invoice_id}/cancel |
customer.created | A customer profile was created. | /v2/customers |
customer.updated | An attribute on a customer profile was changed. | /v2/customers/{customer_id} |
customer.deleted | A customer profile was deleted. | /v2/customers/{customer_id} |
inventory.count.updated | The stock quantity was updated for a catalog item variation. | /v2/inventory/changes/batch-create |
invoice.created | A draft invoice was created. | /v2/invoices |
invoice.published | An invoice was published. | /v2/invoices/{invoice_id}/publish |
invoice.updated | An invoice was changed. | /v2/invoices/{invoice_id} |
Square limits how fast an app or AI agent can call. It does not publish a fixed per-second number, and an app over the limit gets a RATE_LIMITED error to back off and retry.
Square limits how fast an application can call, but does not publish a fixed per-second number, and notes that different endpoints can enforce different limits. An application that sends too many requests in a short period gets a RATE_LIMITED error in the RATE_LIMIT_ERROR category, returned with HTTP 429. The documented handling is to watch for 429 responses and retry with an exponential backoff schedule plus a randomized delay, so a burst does not repeatedly hit the limit.
List and search endpoints are cursor-based. A response includes a cursor when more results remain, and that cursor is passed on the next request to fetch the following page; an absent cursor means the last page has been reached. Some endpoints take a limit parameter to set the page size.
Bodies are JSON. Batch endpoints set their own caps, such as BatchUpsertCatalogObjects creating or updating up to 10,000 objects in a single call. An idempotency key on a write makes it safe to repeat.
The status codes an agent should handle, and what to do about each.
| Status | Code | Meaning | What to do |
|---|---|---|---|
| 400 | INVALID_REQUEST_ERROR | The request was malformed: a field is missing, invalid, or in the wrong format, like VALUE_TOO_LONG or EXPECTED_INTEGER. An idempotency key reused with different data also returns this category, as IDEMPOTENCY_KEY_REUSED. | Read the category, code, detail, and field on each Error object, correct the named field, and resend. |
| 401 | AUTHENTICATION_ERROR | The access token is missing, invalid, expired, or revoked, shown by codes like UNAUTHORIZED, ACCESS_TOKEN_EXPIRED, or ACCESS_TOKEN_REVOKED. | Send a valid Bearer access token, and refresh or re-authorize through OAuth when it has expired or been revoked. |
| 403 | INSUFFICIENT_SCOPES | The token is valid but lacks a permission the request needs, or the action is forbidden. The error sits in the AUTHENTICATION_ERROR category. | Re-authorize with the required permission, like PAYMENTS_WRITE or ITEMS_WRITE, then retry. |
| 404 | NOT_FOUND | The requested object does not exist, or is not visible to this token, account, or environment. | Verify the object ID, and confirm it lives in the same account and environment, production or sandbox. |
| 409 | VERSION_MISMATCH | An optimistic-concurrency conflict: the version sent does not match the current version of an order, invoice, or other versioned object, because it changed in the meantime. | Refetch the object to read its current version, reapply the change, and resend. |
| 429 | RATE_LIMITED | Too many requests arrived in a short period, so Square temporarily stopped processing them. The error sits in the RATE_LIMIT_ERROR category. | Retry with exponential backoff and jitter, and smooth the request rate. |
| 500 | INTERNAL_SERVER_ERROR | An error on Square's side, in the API_ERROR category. It is rare. | Retry idempotently with backoff, and contact Square support if it persists. |
Square versions its API by date through the Square-Version header. The newest version is 2026-05-20, and an application is pinned to a default version that every call uses unless a request overrides it.
Square versions its API by date through the Square-Version header. The 2026-05-20 version is the newest, and an application is pinned to a default version that all of its calls use unless a request overrides it with the header. Releases ship roughly monthly through the release notes.
A dated monthly release ahead of 2026-05-20.
An integration can pin a version and move up on a schedule that suits it.
Square API release notes ↗Bollard AI sits between a team's AI agents and Square. Grant each agent exactly the access it needs, read or write, resource by resource, and every call is checked and logged.