Square connector for AI agents

Tools your payments agent reaches for on Square, scoped per user.

CALL ANY TOOL

118 tools for payments on Square: take, capture, and refund payments, manage orders, catalog, and inventory, book appointments, publish invoices, and run loyalty, gift cards, and subscriptions.

square_booking_cancel

Cancel booking

Cancel a Square Appointments booking. Returns the booking with a canceled status. Use this to cancel an appointment; use square_booking_update to reschedule it instead. Requires a booking_id from square_bookings_list.

Parameters

Name

Type

Required

Description

booking_id

string

Required

The ID of the Booking object representing the to-be-cancelled booking. Example: zkras0xv0xwswx

booking_version

integer

Optional

The revision number for the booking used for optimistic concurrency. Example: 1

idempotency_key

string

Optional

A unique string (for example a UUID) that identifies this request. Square uses it to make retries safe: repeating a call with the same key returns the original result instead of acting twice. Generate a new value for each distinct operation. Example: 7b0f3ec5-086a-4871-8f13-3c81b3875218

square_booking_create

Create booking

square_booking_get

Get booking

square_booking_update

Update booking

square_bookings_availability_search

Search bookings availability

square_bookings_list

List bookings

square_card_disable

Disable card

square_catalog_object_upsert

Upsert catalog object

square_customer_add_to_group

Customer add to group

square_customer_get

Get customer

square_customer_groups_list

List customer groups

square_dispute_evidence_submit

Submit dispute evidence

square_dispute_evidence_text_create

Create dispute evidence text

square_disputes_list

List disputes

square_inventory_count_get

Get inventory count

square_invoice_create

Create invoice

square_invoice_publish

Publish invoice

square_invoices_search

Search invoices

square_jobs_list

List jobs

square_location_update

Update location

square_loyalty_points_adjust

Loyalty points adjust

square_loyalty_reward_get

Get loyalty reward

square_order_create

Create order

square_orders_batch_retrieve

Orders batch retrieve

square_payment_links_list

List payment links

square_refund_get

Get refund

square_refunds_list

List refunds

List payment refunds for the connected Square seller, optionally filtered by time range, location, status, or source type. Returns refunds with id, status, amount, payment id, reason, and timestamps, plus a cursor for the next page. Use this to browse refunds; use square_refund_get for one refund by ID.

Parameters

Name

Type

Required

Description

begin_time

string

Optional

Indicates the start of the time range to retrieve each PaymentRefund for, in RFC 3339 format. The range is determined using the created_at field for each PaymentRefund. Default: The current time minus one year. Example: 2026-01-01T00:00:00Z

cursor

string

Optional

A pagination cursor returned by a previous call to this endpoint. Provide this cursor to retrieve the next set of results for the original query. Example: CAISBQoDMTIzGAE

end_time

string

Optional

Indicates the end of the time range to retrieve each PaymentRefund for, in RFC 3339 format. The range is determined using the created_at field for each PaymentRefund. Default: The current time. Example: 2026-02-01T00:00:00Z

limit

integer

Optional

The maximum number of results to be returned in a single page. It is possible to receive fewer results than the specified limit on a given page. If the supplied value is greater than 100, no more than 100 results are returned. Default: 100

location_id

string

Optional

Limit results to the location supplied. By default, results are returned for all locations associated with the seller. Example: L88917AVBK2S5

sort_field

string

Optional

The field used to sort results by. The default is CREATED_AT. Allowed values: CREATED_AT, UPDATED_AT. One of: `CREATED_AT`, `UPDATED_AT`.

sort_order

string

Optional

The order in which results are listed by PaymentRefund.created_at: ASC - Oldest to newest; DESC - Newest to oldest (default). Allowed values: ASC, DESC. One of: `ASC`, `DESC`.

source_type

string

Optional

If provided, only returns refunds whose payments have the indicated source type. Current values include CARD, BANK_ACCOUNT, WALLET, CASH, and EXTERNAL. For information about these payment source types, see Take Payments. Default: If omitted, refunds are returned regardless of the source type. Allowed values: CARD, BANK_ACCOUNT, WALLET, CASH, EXTERNAL. One of: `CARD`, `BANK_ACCOUNT`, `WALLET`, `CASH`, `EXTERNAL`.

status

string

Optional

If provided, only refunds with the given status are returned. For a list of refund status values, see PaymentRefund. Default: If omitted, refunds are returned regardless of their status. Allowed values: PENDING, COMPLETED, REJECTED, FAILED. Example: PAID. One of: `PENDING`, `COMPLETED`, `REJECTED`, `FAILED`.

updated_at_begin_time

string

Optional

Indicates the start of the time range to retrieve each PaymentRefund for, in RFC 3339 format. The range is determined using the updated_at field for each PaymentRefund. Default: If omitted, the time range starts at begin_time. Example: 2026-01-01T00:00:00Z

updated_at_end_time

string

Optional

Indicates the end of the time range to retrieve each PaymentRefund for, in RFC 3339 format. The range is determined using the updated_at field for each PaymentRefund. Default: The current time. Example: 2026-02-01T00:00:00Z

square_subscription_create

Create subscription

Enroll a Square customer in a subscription plan variation at a location. Returns the created subscription with id, status, start date, and charged-through date. Use this to start a subscription; use square_subscription_update to change one. Requires a plan_variation_id from square_catalog_list (type SUBSCRIPTION_PLAN_VARIATION) and a customer_id.

Parameters

Name

Type

Required

Description

customer_id

string

Required

The ID of the customer subscribing to the subscription plan variation. Example: CHFGVKYY8RSV93M5KCYTG4PN0G

location_id

string

Required

The ID of the location the subscription is associated with. Example: S8GWD5R9QB376

canceled_date

string

Optional

The YYYY-MM-DD-formatted date when the newly created subscription is scheduled for cancellation. This date overrides the cancellation date set in the plan variation configuration. If the cancellation date is earlier than the end date of a subscription cycle, the subscription stops at the canceled date and the subscriber is sent a prorated invoice at the beginning of the canceled cycle. When the subscription plan of the newly created subscription has a fixed number of cycles and the canceled_date occurs before the subscription plan completes, the specified canceled_date sets the date when the subscription stops through the end of the last cycle. Example: 2026-11-01

card_id

string

Optional

The ID of the subscriber's card to charge. If it is not specified, the subscriber receives an invoice via email with a link to pay for their subscription. Example: ccof:qy5x8hHGYsgLrp4Q4GB

idempotency_key

string

Optional

monthly_billing_anchor_date

integer

Optional

The day-of-the-month to change the billing date to. Example: 1

phases

array

Optional

array of phases for this subscription Example: [{"order_template_id":"U2NaowWxzXwpsZU697x7ZHOAnCNZY","ordinal":0}]

plan_variation_id

string

Optional

The ID of the subscription plan variation created using the Catalog API. Example: 6JHXF3B2CW3YKHDV4XEM674H

price_override_money

object

Optional

A custom price which overrides the cost of a subscription plan variation with STATIC pricing. This field does not affect itemized subscriptions with RELATIVE pricing. Instead, you should edit the Subscription's order template. 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. Example: {"amount":500,"currency":"USD"}

source

object

Optional

The origination details of the subscription. Example: {"name":"My Application"}

start_date

string

Optional

The YYYY-MM-DD-formatted date to start the subscription. If it is unspecified, the subscription starts immediately. Example: 2023-06-20

tax_percentage

string

Optional

The tax to add when billing the subscription. The percentage is expressed in decimal form, using a '.' as the decimal separator and without a '%' sign. For example, a value of 7.5 corresponds to 7.5%.

timezone

string

Optional

The timezone that is used in date calculations for the subscription. If unset, defaults to the location timezone. If a timezone is not configured for the location, defaults to "America/New_York". Format: the IANA Timezone Database identifier for the location timezone. For a list of time zones, see List of tz database time zones. Example: America/Los_Angeles

square_subscription_update

Update subscription

square_subscriptions_search

Search subscriptions

For more tools, view docs.

Build your Agent

Same auth pattern across LangChain, OpenAI, Anthropic, and Google ADK.

import { ScalekitClient } from "@scalekit-sdk/node";
import { createReactAgent } from "@langchain/langgraph/prebuilt";

const sk = new ScalekitClient(env.SCALEKIT_ENV_URL, env.SCALEKIT_CLIENT_ID, env.SCALEKIT_CLIENT_SECRET);

// Square tools scoped to this user
const { tools } = await sk.tools.listScopedTools("user_123", {
  filter: { connectionNames: ["square"], toolNames: [
    "square_payments_list",
    "square_refund_create",
    "square_orders_search"] },
  pageSize: 100,
});

const agent = createReactAgent({ llm, tools });
await agent.invoke({ messages: [{ role: "user", content: "Refund the duplicate charge on yesterday's order for Dana Lee" }] });

import OpenAI from "openai";
import { ScalekitClient } from "@scalekit-sdk/node";

const sk = new ScalekitClient(env.SCALEKIT_ENV_URL, env.SCALEKIT_CLIENT_ID, env.SCALEKIT_CLIENT_SECRET);
const openai = new OpenAI();

const { tools } = await sk.tools.listScopedTools("user_123", {
  filter: { connectionNames: ["square"] }, pageSize: 100,
});

const res = await openai.chat.completions.create({
  model: "gpt-5",
  messages: [{ role: "user", content: "Refund the duplicate charge on yesterday's order for Dana Lee" }],
  tools,
});

// Execute the tool call with the user's vaulted Square OAuth token
await sk.tools.executeTool(res.choices[0].message.tool_calls[0], "user_123");

import Anthropic from "@anthropic-ai/sdk";
import { ScalekitClient } from "@scalekit-sdk/node";

const sk = new ScalekitClient(env.SCALEKIT_ENV_URL, env.SCALEKIT_CLIENT_ID, env.SCALEKIT_CLIENT_SECRET);
const anthropic = new Anthropic();

const { tools } = await sk.tools.listScopedTools("user_123", {
  filter: { connectionNames: ["square"] }, pageSize: 100,
});

const msg = await anthropic.messages.create({
  model: "claude-sonnet-5",
  max_tokens: 1024,
  messages: [{ role: "user", content: "Refund the duplicate charge on yesterday's order for Dana Lee" }],
  tools,
});

// Tool call runs with the user's vaulted Square OAuth token
await sk.tools.executeTool(msg.content, "user_123");

import { Agent } from "@google/adk/agents";
import { ScalekitClient } from "@scalekit-sdk/node";

const sk = new ScalekitClient(env.SCALEKIT_ENV_URL, env.SCALEKIT_CLIENT_ID, env.SCALEKIT_CLIENT_SECRET);

const { tools } = await sk.tools.listScopedTools("user_123", {
  filter: { connectionNames: ["square"] }, pageSize: 100,
});

const agent = new Agent({
  name: "payments_agent",
  model: "gemini-2.5-pro",
  instruction: "Square tools scoped to this user",
  tools,
});

await agent.run("Refund the duplicate charge on yesterday's order for Dana Lee");

Try these prompts

Copy any prompt into your agent. Each maps directly to a Square tool. Click to copy, paste into your agent, done.

Payments and orders

Copy the prompt

Copied

List payments taken at the Mission Street location yesterday.

Copy the prompt

Copied

Refund $25 of yesterday's payment from Dana Lee for the damaged item.

Copy the prompt

Copied

Preview the total for an order of 2 lattes and 1 croissant with tax.

Catalog and inventory

Copy the prompt

Copied

Search the catalog for every item in the Pastries category.

Copy the prompt

Copied

What is the current stock of the Oat Milk Latte variation at each location?

Copy the prompt

Copied

Record a physical count of 40 bags of house blend at the main location.

Customers and bookings

Copy the prompt

Copied

Find open booking slots for a haircut at the downtown location on Saturday.

Copy the prompt

Copied

Create a customer profile for Dana Lee with her email and phone.

Copy the prompt

Copied

Add 50 bonus points to Dana Lee's loyalty account.

SEE HOW AUTH WORKS

Each user signs in to Square once, and Scalekit stores and refreshes their tokens. Credentials stay vaulted, every call is scope checked, and every action is logged.

Authorize

Your user connects

Square

once. We tie it to their identity and the meetings they approved — no shared bot account, no org-wide access

Who:

user ‘A’

when:

Once per user

access:

Limited to user

Store

Their

Square

token lives in a vault scoped to them. User A's meetings are never reachable by an agent acting for user B, even on the same connection

vault:

encrypted

scope:

per-user

tokens:

auto-refreshed

Resolve

When your agent calls a

Square

tool, we fetch the right token server-side. It never touches your agent, never appears in the LLM context, never shows up in your logs

speed:

~40ms

check:

before every call

seen by:

nobody

Audit

Every

Square

tool call is logged — who triggered it, which meeting was fetched, what came back. 90 days of history, tied to the user who authorized it

history:

90 days

export:

SIEM-ready

logged:

every call

Test other agents

See the same per-user auth pattern across other payments and finance connectors.

GTM and RevOps Teams

CRM AI agent

Reads the Granola transcript after every call, extracts next steps and updates the HubSpot record, drafts the follow-up in Gmail, and confirms in Slack, all on the rep's own delegated OAuth.

GTM and RevOps Teams

Revenue forecast commentary

Pulls open pipeline from Salesforce and HubSpot, calculates coverage against quota, flags at-risk stages, posts commentary to Slack, and logs every snapshot to Google Sheets.

Why Scalekit

Secure your agent's access. Connectors ship in minutes

01.

Shared tokens break per-user analytics

A shared Square token looks fine in a demo. In production every refund and order change looks like one service account, and you cannot tell which user triggered it. Scalekit resolves the credential of the actual user who triggered the agent, never a shared bot.

// shared token
audit → bot_service_account

// scalekit
audit → user_abc ✓

02.

Authentication is not authorization

03.

Multi-tenancy is architectural

04.

Square today. Ten connectors tomorrow.

“Our agents act across Salesforce, Gong, Google Drive, and more, on behalf of every customer. Scalekit behind the scenes meant we can keep adding tools without ever rebuilding how credentials or tool calling work.”

Venu Madhav Kattagoni

Head of Engineering / Von

FAQs

Frequently Asked Questions

Does the agent access Square as the user or through a shared service account?

As the user. Each user signs in to Square once, and Scalekit stores and refreshes their tokens. Payments, refunds, and order changes the agent makes are attributed to that user in your audit trail, not a shared service account.

Where is the Square OAuth token stored?

In Scalekit's managed AES-256 token vault, namespaced per tenant. Refresh is automatic. Revocation is a single dashboard action. Credentials never appear in prompts, logs, or LLM context.

Can I limit what the agent does in Square?

Yes. Filter by tool name in listScopedTools to expose only what you want, for example the list and search tools without square_payment_create or square_refund_create, which move money. Scalekit also enforces scope checks before every API call.

What happens when a user revokes Square access?

The connection is invalidated on the next tool call. Subsequent requests for that user fail closed with a clear error. Other users in the tenant remain unaffected. The event is logged for audit.

Which Square seller account does the agent work on?

The seller account the user signed in with. square_merchant_get returns that merchant, and square_locations_list returns every business location under it. Many tools take a location ID, so the agent can keep payments, orders, and invoices to one location.