Square

What your agents can doCopy Anchor Link

Agents search Square's REST API and call it with your connected credentials. The index covers 332 operations from Square's specification for API version 2026-09-16, including payments, refunds, orders, customers, catalog, inventory, bookings, subscriptions and team management. Access depends on the seller's permissions and Square products.

Square's separate GraphQL and Reporting APIs are not indexed. GraphQL exposes its schema through authenticated introspection. Square's published OpenAPI does not include Reporting.

AuthenticationCopy Anchor Link

Personal access tokenCopy Anchor Link

Use this method for your own Square account. Open your application in the Square Developer Console, select the environment, and copy its personal access token. In Helios, choose Personal access token, select Environment (production or sandbox), and enter Personal access token.

Production uses connect.squareup.com; Sandbox uses connect.squareupsandbox.com. Tokens are specific to their environment.

Your own Square appCopy Anchor Link

Use OAuth when connecting other sellers. Create a Square application and register the OAuth callback URL shown by Helios. Choose Your own Square app, select Environment, and enter Application ID and Application secret before authorizing the seller.

Application personal access token is optional for API access and required for automatic webhook setup. Enter the personal token of the same application and environment as your OAuth credentials. Helios uses this token only to manage subscriptions. Seller API calls use the seller's OAuth token. Leaving it empty marks webhook events unavailable with a setup reason.

The POST /oauth2/revoke operation requires Your own Square app because Square authenticates it with the application secret. Other API calls use bearer tokens.

Helios refreshes OAuth tokens weekly and when needed.

Helios requests all 63 scopes. Some scopes require product access or approval; a complete scope request does not guarantee access for every app.

ADDON_CONFIGURATIONS_READ
ADDON_CONFIGURATIONS_WRITE
APPOINTMENTS_ALL_READ
APPOINTMENTS_ALL_WRITE
APPOINTMENTS_BUSINESS_SETTINGS_READ
APPOINTMENTS_READ
APPOINTMENTS_WRITE
BANK_ACCOUNTS_READ
BANK_ACCOUNTS_WRITE
CASH_DRAWER_READ
CHANNELS_CREATE
CHANNELS_READ
CHANNELS_UPDATE
CUSTOMERS_READ
CUSTOMERS_WRITE
DEVICES_READ
DEVICE_CREDENTIAL_MANAGEMENT
DISCOUNT_CODES_READ
DISCOUNT_CODES_WRITE
DISPUTES_READ
DISPUTES_WRITE
EMPLOYEES_READ
EMPLOYEES_WRITE
GIFTCARDS_READ
GIFTCARDS_WRITE
INVENTORY_READ
INVENTORY_WRITE
INVOICES_READ
INVOICES_WRITE
ITEMS_READ
ITEMS_WRITE
LOYALTY_READ
LOYALTY_WRITE
MERCHANT_PROFILE_READ
MERCHANT_PROFILE_WRITE
ONLINE_STORE_SITE_READ
ONLINE_STORE_SNIPPETS_READ
ONLINE_STORE_SNIPPETS_WRITE
ORDERS_READ
ORDERS_WRITE
PAYMENTS_READ
PAYMENTS_WRITE
PAYMENTS_WRITE_ADDITIONAL_RECIPIENTS
PAYMENTS_WRITE_IN_PERSON
PAYMENTS_WRITE_SHARED_ONFILE
PAYMENT_METHODS_READ
PAYOUTS_READ
PAYOUTS_WRITE
PERMISSION_SETS_READ
PERMISSION_SETS_WRITE
REPORTING_READ
RESERVATIONS_READ
RESERVATIONS_WRITE
RESTAURANT_CHECKS_READ
SETTLEMENTS_READ
SUBSCRIPTIONS_READ
SUBSCRIPTIONS_WRITE
TIMECARDS_READ
TIMECARDS_SETTINGS_READ
TIMECARDS_SETTINGS_WRITE
TIMECARDS_WRITE
VENDOR_READ
VENDOR_WRITE

See the permissions reference. If authorization fails with invalid_scope, check the application's access to the requested products with Square. Helios does not silently reduce its requested permissions.

TriggersCopy Anchor Link

The trigger picker contains all 149 Square events, including deprecated events.

Helios replaces dots before the final action with underscores. For example, Square's inventory.count.updated becomes inventory_count.updated, and booking.custom_attribute.visible.updated becomes booking_custom_attribute_visible.updated. Events with two parts, such as payment.created, keep their names. See the complete event catalog for every mapping and filter.

Each connection gets one subscription at its Helios webhook URL. Helios retrieves the event types Square offers for the application and API version, subscribes to every available catalog event, and reports unavailable events with a reason. An existing subscription is updated in place. If an update fails, existing subscriptions and their signing keys remain usable. With the application token present, events still delivered by those subscriptions are not reported as unavailable. Disconnecting deletes subscriptions at that connection's URL.

Subscriptions belong to the application, so each OAuth connection consumes application subscription capacity. Helios checks the signed merchant ID before dispatching an event to the connection. Square also checks seller scopes and product eligibility before sending events.

FiltersCopy Anchor Link

All filters are optional. IDs and states accept patterns such as location-*; customer email patterns ignore case. Name and title filters match text without case sensitivity. Empty filters accept every value; selected filters do not match missing fields.

Inventory count and fulfillment filters inspect every member of their payload arrays while keeping the delivery as one event.

Prefer visible custom-attribute events for broad tracking; they include owned changes. Prefer labor_timecard.* over deprecated labor_shift.*, and dispute_state.updated over dispute_state.changed. Subscribing to overlapping event types can start separate runs because Square assigns them different event IDs.

Event catalogCopy Anchor Link

Bank accountsCopy Anchor Link

BookingsCopy Anchor Link

CardsCopy Anchor Link

CatalogCopy Anchor Link

CustomersCopy Anchor Link

DevicesCopy Anchor Link

DisputesCopy Anchor Link

Gift cardsCopy Anchor Link

InventoryCopy Anchor Link

InvoicesCopy Anchor Link

JobsCopy Anchor Link

LaborCopy Anchor Link

LocationsCopy Anchor Link

Online checkoutCopy Anchor Link

LoyaltyCopy Anchor Link

MerchantsCopy Anchor Link

OAuthCopy Anchor Link

OrdersCopy Anchor Link

PaymentsCopy Anchor Link

PayoutsCopy Anchor Link

RefundsCopy Anchor Link

SubscriptionsCopy Anchor Link

Team membersCopy Anchor Link

TerminalCopy Anchor Link

Transfer ordersCopy Anchor Link

VendorsCopy Anchor Link

Delivery, errors and limitsCopy Anchor Link

Helios verifies Square's Base64 HMAC-SHA256 signature over the exact notification URL and raw body, using the subscription's signing key. Square retries deliveries for up to 24 hours. See signature validation and delivery behavior.

Square does not guarantee event order. Test notifications can start real workflows. An OAuth revocation event can start a workflow. A revoked token fails its next API call, and authentication failure handling marks the connection disconnected.

A failed subscription listing fails setup. API UNAUTHORIZED errors can mean that the token belongs to the other environment. Square publishes no single REST rate limit. Helios retries rate-limited and transient server errors.

Square does not document a current universal subscription quota or maximum event-type count. Its older support guidance mentions three subscriptions per application, so check capacity before connecting many sellers. File operations remain in the API index; agents use curl for returned file URLs.