# Square — how to use (mcp.ai)

Connect your Square account and use 122 tools for payment processing straight from your AI agent. Connect in one click, no API key needed. Square provides payment processing, POS systems, invoicing, and e-commerce tools, enabling sellers to accept card payments and manage their business.

## Option A — via MCP (recommended)
Remote MCP endpoint (HTTP, streamable): `https://api.mcp.ai/p_square?ms=1787295720000`
Add it as a custom/remote MCP connector in your client (Claude, Cursor, VS Code…), then authenticate when prompted. Once connected, ask the agent to use the server's tools (e.g. `square_accept_dispute`).

## Option B — via direct REST API
Base URL: `https://api.mcp.ai/api/square`
Auth: `Authorization: Bearer sk_live_…` — create a workspace API key at https://mcp.ai/settings/api-keys
Discover endpoints: `GET https://api.mcp.ai/api/square/_endpoints`

### Endpoints
- `POST https://api.mcp.ai/api/square/accept/dispute` — Accept a dispute and acknowledge liability, returning funds to the cardholder. When you accept a dispute, Square debits the disputed amount from your account and updates the dispute state to ACCEPTED.
  - body: { dispute_id: string }
- `POST https://api.mcp.ai/api/square/add/group/to/customer` — Tool to add a customer to a customer group. Use when you need to associate a customer with a specific group for targeted marketing, loyalty programs, or customer segmentation.
  - body: { group_id: string, customer_id: string }
- `POST https://api.mcp.ai/api/square/calculate/order` — Tool to preview order pricing without creating an order. Use when you need to calculate the total cost, taxes, discounts, and other pricing details for an order before finalizing it. Particularly usef
  - body: { order: object, proposed_rewards?: object[] }
- `POST https://api.mcp.ai/api/square/cancel/booking` — Cancels an existing Square booking, terminating the reservation. Use this action when a customer or seller needs to cancel a scheduled appointment. The booking must be in a cancellable state, and the 
  - body: { booking_id: string, booking_version?: integer, idempotency_key?: string }
- `POST https://api.mcp.ai/api/square/cancel/invoice` — Cancels a Square invoice, preventing further payments from being collected. Requirements: - Invoice must be in SCHEDULED, UNPAID, or PARTIALLY_PAID state - Cannot cancel invoices in DRAFT state or ter
  - body: { version: integer, invoice_id: string }
- `POST https://api.mcp.ai/api/square/cancel/payment` — Cancels (voids) a payment that is in APPROVED status. This is typically used in delayed capture scenarios where a payment was authorized but not yet captured, allowing you to void the authorization be
  - body: { payment_id: string }
- `POST https://api.mcp.ai/api/square/create/batch/inventory/changes` — Applies multiple inventory adjustments and physical counts in a single batch request. Returns the created changes and current inventory counts for all affected items. Use this action when you need to 
  - body: { changes: object[], idempotency_key: string, ignore_unchanged_counts?: boolean }
- `POST https://api.mcp.ai/api/square/create/bulk/customers` — Tool to create multiple customer profiles in a single request. Use when you need to efficiently create up to 100 customers at once. Each customer is identified by a unique idempotency key.
  - body: { customers: object }
- `POST https://api.mcp.ai/api/square/create/card` — Tool to create a card on file. Use when you need to securely store a customer's card for future payments. Requires a valid nonce or payment ID.
  - body: { card: object, source_id: string, idempotency_key: string, verification_token?: string }
- `POST https://api.mcp.ai/api/square/create/customer` — Tool to create a new customer profile in Square. Use when you need to add a customer to the Square account. At least one of given_name, family_name, company_name, email_address, or phone_number is req
  - body: { note?: string, address?: object, tax_ids?: object, birthday?: string, nickname?: string, given_name?: string, family_name?: string, company_name?: string, phone_number?: string, reference_id?: string, email_address?: string, idempotency_key?: string }
- `POST https://api.mcp.ai/api/square/create/customer/custom/attribute/definition` — Tool to create a customer-related custom attribute definition. Use when you need to define a new custom attribute that can be applied to customer profiles. Custom attributes allow storing additional s
  - body: { idempotency_key?: string, custom_attribute_definition: object }
- `POST https://api.mcp.ai/api/square/create/customer/group` — Tool to create a new customer group for a business. Use when you need to organize customers into groups for targeted marketing or segmentation.
  - body: { group: object, idempotency_key?: string }
- `POST https://api.mcp.ai/api/square/create/dispute/evidence/file` — Tool to upload a file as dispute evidence. Use when you need to attach supporting documents (PDF, image, etc.) to an existing dispute. Use after creating or retrieving a dispute.
  - body: { file: object, dispute_id: string, content_type?: string, evidence_type?: string, idempotency_key: string, inline_file_name?: string, inline_file_mimetype?: string, inline_file_content_base64?: string }
- `POST https://api.mcp.ai/api/square/create/dispute/evidence/text` — Upload text evidence for a dispute challenge. Use this to submit textual information (up to 500 characters) that supports your case in a payment dispute. After uploading all evidence, you must call Su
  - body: { dispute_id: string, evidence_text: string, evidence_type?: string, idempotency_key: string }
- `POST https://api.mcp.ai/api/square/create/gift/card/activity` — Creates a gift card activity to manage gift card balances. This action supports multiple activity types including ACTIVATE (initiate a gift card with an opening balance), LOAD (add funds), REDEEM (wit
  - body: { idempotency_key: string, gift_card_activity: object }
- `POST https://api.mcp.ai/api/square/create/invoice/attachment` — Upload and attach a file to a Square invoice. Use this action to add supplementary documents (receipts, contracts, supporting documentation) to an existing invoice. Attachments can only be added to in
  - body: { file: object, invoice_id: string, description?: string, idempotency_key?: string }
- `POST https://api.mcp.ai/api/square/create/location` — Tool to create a new business location in a Square account. Use when you need to add a new physical or mobile location for the merchant.
  - body: { location: object }
- `POST https://api.mcp.ai/api/square/create/location/custom/attribute/definition` — Tool to create a location-related custom attribute definition. Use when you need to define new custom attributes for Square location objects to store additional business-specific data.
  - body: { idempotency_key?: string, custom_attribute_definition: object }
- `POST https://api.mcp.ai/api/square/create/order` — Creates a new Square order with line items, taxes, discounts, and fulfillment details. Use this action when you need to create an order for processing payments or tracking sales. The created order wil
  - body: { order: object, idempotency_key: string }
- `POST https://api.mcp.ai/api/square/create/refund` — Refunds a Square payment in full or partially. Use this action when you need to return funds to a customer for a completed payment, such as for returned products, cancelled services, or billing errors
  - body: { reason?: string, payment_id: string, amount_money: object, app_fee_money?: object, team_member_id?: string, idempotency_key: string, payment_version_token?: string }
- `POST https://api.mcp.ai/api/square/create/team/member` — Tool to create a new team member in Square. Creates a team member profile that can be used to assign permissions and track employee data. Use when you need to add a new employee or staff member to the
  - body: { team_member: object, idempotency_key: string }
- `POST https://api.mcp.ai/api/square/delete/catalog/object` — Tool to delete a Square catalog object by ID. When an object is deleted, other objects in the graph that depend on that object will be deleted as well (cascading deletion). Use this action when you ne
  - body: { object_id: string }
- `POST https://api.mcp.ai/api/square/delete/catalog/objects/batch` — Deletes a set of CatalogObjects based on a list of target object IDs and returns a set of successfully deleted IDs in the response. Deletion is a cascading event such that all children of the targeted
  - body: { object_ids: string[] }
- `POST https://api.mcp.ai/api/square/delete/customer` — Tool to delete a Square customer profile. Use when you need to permanently remove a customer record from Square.
  - body: { version?: integer, customer_id: string }
- `POST https://api.mcp.ai/api/square/delete/customer/custom/attribute` — Tool to delete a custom attribute from a customer profile. Use when you need to remove custom data associated with a specific customer. Requires the CUSTOMERS_WRITE OAuth permission scope.
  - body: { key: string, customer_id: string }
- `POST https://api.mcp.ai/api/square/delete/customer/custom/attribute/definition` — Tool to delete a customer-related custom attribute definition. Use when you need to remove a custom attribute definition that is no longer needed. This action requires CUSTOMERS_WRITE permission.
  - body: { key: string }
- `POST https://api.mcp.ai/api/square/delete/customer/group` — Tool to delete a customer group by its ID. Use when you need to permanently remove a customer group from Square.
  - body: { group_id: string }
- `POST https://api.mcp.ai/api/square/delete/customers/bulk` — Tool to bulk delete customer profiles from Square. Use when you need to delete multiple customer profiles at once (1-100 customers per request). Each successful deletion returns an empty object; faile
  - body: { customer_ids: string[] }
- `POST https://api.mcp.ai/api/square/delete/dispute/evidence` — Removes a specific piece of evidence from a dispute. Evidence that is removed will NOT be sent to the bank. This action requires the DISPUTES_WRITE permission scope. Important: You CANNOT remove evide
  - body: { dispute_id: string, evidence_id: string }
- `POST https://api.mcp.ai/api/square/delete/invoice` — Tool to delete a Square invoice (only DRAFT invoices can be deleted).
  - body: { version?: integer, invoice_id: string }
- `POST https://api.mcp.ai/api/square/delete/invoice/attachment` — Tool to delete an attachment from a Square invoice. Endpoint: DELETE /v2/invoices/{invoice_id}/attachments/{attachment_id}
  - body: { invoice_id: string, attachment_id: string }
- `POST https://api.mcp.ai/api/square/delete/location/custom/attribute` — Tool to delete a custom attribute from a location. Use when you need to remove custom data associated with a specific business location. Requires the MERCHANT_PROFILE_WRITE OAuth permission scope.
  - body: { key: string, location_id: string }
- `POST https://api.mcp.ai/api/square/delete/location/custom/attribute/definition` — Tool to delete a location-related custom attribute definition. Once deleted, the custom attribute definition cannot be used to add custom attributes to locations. Use when you need to remove obsolete 
  - body: { key: string }
- `POST https://api.mcp.ai/api/square/delete/locations/custom/attributes/batch` — Tool to delete custom attributes from multiple locations in a single batch request. Use when you need to remove custom metadata from multiple business locations efficiently. To delete custom attribute
  - body: { values: object }
- `POST https://api.mcp.ai/api/square/delete/merchant/custom/attribute` — Tool to delete a custom attribute from a merchant profile. Use when you need to remove custom data associated with a specific merchant. Requires the MERCHANT_PROFILE_WRITE OAuth permission scope.
  - body: { key: string, merchant_id: string }
- `POST https://api.mcp.ai/api/square/delete/merchant/custom/attribute/definition` — Tool to delete a merchant-related custom attribute definition. Once deleted, the custom attribute definition cannot be used to add custom attributes to merchants. Use when you need to remove obsolete 
  - body: { key: string }
- `POST https://api.mcp.ai/api/square/delete/merchants/custom/attributes/batch` — Tool to delete custom attributes from multiple merchants in a single batch request. Use when you need to remove custom metadata from merchant profiles efficiently. To delete custom attributes owned by
  - body: { values: object }
- `POST https://api.mcp.ai/api/square/delete/webhook/subscription` — Permanently deletes a webhook subscription by its ID. Once deleted, the subscription will no longer receive event notifications. This action cannot be undone. Note: Webhook subscriptions are applicati
  - body: { subscription_id: string }
- `POST https://api.mcp.ai/api/square/get/booking` — Retrieves detailed information about a specific Square booking by its ID. Returns the complete booking object including appointment segments, customer notes, seller notes, location details, creator in
  - body: { booking_id: string }
- `POST https://api.mcp.ai/api/square/get/business/booking/profile` — Tool to retrieve the business booking profile for a Square merchant via GraphQL. Use when you need to check if bookings are enabled, view cancellation policies, or access booking configuration setting
  - body: { merchant_ids: string[] }
- `POST https://api.mcp.ai/api/square/get/current/merchant` — Tool to retrieve merchant information associated with the access token using Square's GraphQL API. Use when you need to obtain the merchant ID required for other GraphQL queries, or to get merchant de
- `POST https://api.mcp.ai/api/square/get/customer/custom/attribute` — Retrieves a custom attribute from a customer profile in Square. Use this when you need to access specific custom data associated with a customer, such as preferences, external IDs, or other merchant-d
  - body: { key: string, version?: integer, customer_id: string, with_definition?: boolean }
- `POST https://api.mcp.ai/api/square/get/customers/custom/attribute/definitions` — Tool to retrieve a customer-related custom attribute definition from Square. Use when you need to fetch the schema, visibility, or metadata of a specific custom attribute definition by its key.
  - body: { key: string, version?: integer }
- `POST https://api.mcp.ai/api/square/get/customers/graphql` — Tool to retrieve customer profiles from Square Customer Directory using GraphQL API. Use when you need to fetch customer information including name, contact details, and profile data for a specific me
  - body: { limit?: integer, merchant_id: string }
- `POST https://api.mcp.ai/api/square/get/dispute/evidence` — Retrieves detailed information about a specific piece of evidence that was uploaded for a dispute. Use this action to: - Get metadata about evidence (file details, upload time, evidence type) - Verify
  - body: { dispute_id: string, evidence_id: string }
- `POST https://api.mcp.ai/api/square/get/gift/card/from/gan` — Retrieves detailed information about a gift card by its GAN (gift card account number). Use this action when you need to look up a gift card using the GAN that buyers use to make purchases or check ba
  - body: { gan: string }
- `POST https://api.mcp.ai/api/square/get/invoice` — Retrieves detailed information about a specific Square invoice by its ID. Returns the complete invoice object including payment requests, recipient details, accepted payment methods, custom fields, at
  - body: { invoice_id: string }
- `POST https://api.mcp.ai/api/square/get/loyalty/account` — Tool to retrieve detailed information about a specific Square loyalty account by ID. Use when you need to fetch loyalty account data including balance, lifetime points, customer association, and point
  - body: { account_id: string }
- `POST https://api.mcp.ai/api/square/get/merchant` — Tool to retrieve detailed information about a specific Square merchant by ID. Use when you need to fetch merchant profile data including business name, country, currency, and main location ID. Use 'me
  - body: { merchant_id: string }
- `POST https://api.mcp.ai/api/square/get/online/checkout/location/settings` — Tool to retrieve location-level settings for Square online checkout. Use when you need to get checkout configuration including customer notes, policies, branding, and tipping options for a specific lo
  - body: { location_id: string }
- `POST https://api.mcp.ai/api/square/get/refund` — Retrieves a specific payment refund by its unique ID from Square. Returns complete refund details including amount, status, associated payment and order IDs, and refund destination information. Use th
  - body: { refund_id: string }
- `POST https://api.mcp.ai/api/square/get/subscription` — Retrieves detailed information about a specific Square customer subscription by its ID. Use this action when you need to fetch subscription details including status, billing information, plan variatio
  - body: { include?: string, subscription_id: string }
- `POST https://api.mcp.ai/api/square/get/team/member` — Tool to retrieve detailed information about a specific Square team member by ID. Use when you need to fetch team member profile data including name, contact information, location assignments, and wage
  - body: { team_member_id: string }
- `POST https://api.mcp.ai/api/square/link/customer/to/gift/card` — Tool to link a customer to a gift card in Square. Links the customer profile to the gift card, adding their ID to the gift card's customer_ids list. Use when you need to associate a customer with a gi
  - body: { customer_id: string, gift_card_id: string }
- `POST https://api.mcp.ai/api/square/list/cards` — Tool to retrieve cards on file associated with a Square account. Use when you need to list saved payment methods for a merchant or customer for payment processing or management purposes. Returns a max
  - body: { cursor?: string, sort_order?: string, customer_id?: string, reference_id?: string, include_disabled?: boolean }
- `POST https://api.mcp.ai/api/square/list/channels` — Tool to list requested channels from Square. Use when you need to retrieve channel information for a specific reference type, reference ID, or status.
  - body: { limit?: integer, cursor?: string, status?: string, reference_id?: string, reference_type?: string }
- `POST https://api.mcp.ai/api/square/list/customer/custom/attribute/definitions` — Tool to list customer-related custom attribute definitions from Square. Use when you need to discover available custom attributes that can be attached to customer profiles.
  - body: { limit?: integer, cursor?: string }
- `POST https://api.mcp.ai/api/square/list/customer/custom/attribute/definitions/graph/ql` — Tool to retrieve customer custom attribute definitions via Square's GraphQL API. Use when you need to discover available custom attributes and their metadata for customer profiles. Alpha feature.
  - body: { merchant_ids: string[] }
- `POST https://api.mcp.ai/api/square/list/customer/custom/attributes` — Tool to list custom attributes for a customer profile. Use when you need to retrieve all custom data associated with a specific customer, including optional definitions that provide metadata about eac
  - body: { limit?: integer, cursor?: string, customer_id: string, with_definitions?: boolean }
- `POST https://api.mcp.ai/api/square/list/customer/groups` — Tool to retrieve the list of customer groups of a business. Use when you need to discover customer group IDs or list all customer groups for segmentation and targeting purposes.
  - body: { limit?: integer, cursor?: string }
- `POST https://api.mcp.ai/api/square/list/customer/segments` — Tool to retrieve the list of customer segments of a business. Use when you need to discover customer segment IDs for targeting or filtering customer groups in Square.
  - body: { limit?: integer, cursor?: string }
- `POST https://api.mcp.ai/api/square/list/customers` — Tool to retrieve customer profiles associated with a Square account. Use when you need to list customers for CRM, reporting, or customer management purposes. Only returns profiles with public informat
  - body: { count?: boolean, limit?: integer, cursor?: string, sort_field?: string, sort_order?: string }
- `POST https://api.mcp.ai/api/square/list/dispute/evidence` — Tool to list evidence items associated with a given dispute. Endpoint: GET /v2/disputes/{dispute_id}/evidence
  - body: { cursor?: string, dispute_id: string }
- `POST https://api.mcp.ai/api/square/list/invoices` — Tool to list invoices for a Square location.
  - body: { limit?: integer, cursor?: string, location_id: string }
- `POST https://api.mcp.ai/api/square/list/location/custom/attribute/definitions` — Tool to list location-related custom attribute definitions from Square. Use when you need to discover available custom attributes that can be attached to location profiles.
  - body: { limit?: integer, cursor?: string, visibilityFilter?: string }
- `POST https://api.mcp.ai/api/square/list/locations` — Tool to retrieve all business locations from a Square account. Use when you need to discover available location IDs for other Square API calls that require location_id parameter (like listing invoices
- `POST https://api.mcp.ai/api/square/list/locations/custom/attributes` — Tool to list custom attributes for a specific location in Square. Use when you need to retrieve all custom attribute values associated with a particular location.
  - body: { limit?: integer, cursor?: string, location_id: string, with_definitions?: boolean, visibility_filter?: string }
- `POST https://api.mcp.ai/api/square/list/merchant/custom/attribute/definitions` — Tool to list merchant-related custom attribute definitions from Square. Use when you need to discover available custom attributes that can be attached to merchant profiles.
  - body: { limit?: integer, cursor?: string, visibility_filter?: string }
- `POST https://api.mcp.ai/api/square/list/merchants` — Tool to retrieve merchant account information associated with the access token. Use when you need to get merchant profile details including business name, country, currency, and main location ID.
  - body: { cursor?: integer }
- `POST https://api.mcp.ai/api/square/list/merchants/custom/attributes` — Tool to list custom attributes for a specific merchant in Square. Use when you need to retrieve all custom attribute values associated with a particular merchant.
  - body: { limit?: integer, cursor?: string, merchant_id: string, with_definitions?: boolean, visibility_filter?: string }
- `POST https://api.mcp.ai/api/square/list/payments` — Tool to list payments by location and time range to enable reconciliation and net sales reporting from Square POS. Use when you need to retrieve payment records for reporting, analytics, or reconcilia
  - body: { limit?: integer, total?: integer, cursor?: string, last_4?: string, end_time?: string, begin_time?: string, card_brand?: string, sort_field?: string, sort_order?: string, location_id?: string, offline_end_time?: string, is_offline_payment?: boolean, offline_begin_time?: string, updated_at_end_time?: string, updated_at_begin_time?: string }
- `POST https://api.mcp.ai/api/square/list/subscriptions` — Tool to search and list Square customer billing subscriptions. Use this action when you need to retrieve subscription information for customers, filter subscriptions by location, or view all active su
  - body: { limit?: integer, query?: object, cursor?: string, include?: string[] }
- `POST https://api.mcp.ai/api/square/list/webhook/event/types` — Tool to list available webhook event types. Use when you need to discover event types before creating or updating a webhook subscription.
  - body: { api_version?: string }
- `POST https://api.mcp.ai/api/square/list/webhook/subscriptions` — List all webhook subscriptions owned by your application. Returns webhook subscriptions with their event types, notification URLs, and status. Supports filtering by enabled/disabled status, sorting by
  - body: { limit?: integer, cursor?: string, sort_order?: string, include_disabled?: boolean }
- `POST https://api.mcp.ai/api/square/pay/order` — Pays an existing Square order by processing approved payments and completing the transaction. Use this action when you need to finalize payment on an order that has already been created and has associ
  - body: { order_id: string, payment_ids?: string[], order_version?: integer, idempotency_key: string }
- `POST https://api.mcp.ai/api/square/remove/group/from/customer` — Removes a customer from a customer group. Use this when you need to disassociate a customer from a specific group. Once removed, the customer will no longer be part of the group and won't receive grou
  - body: { group_id: string, customer_id: string }
- `POST https://api.mcp.ai/api/square/retrieve/bulk/customers` — Tool to retrieve multiple customer profiles in a single request. Use when you need to efficiently fetch up to 100 customer profiles by their IDs.
  - body: { customer_ids: string[] }
- `POST https://api.mcp.ai/api/square/retrieve/channel` — Retrieve a Square channel by its ID. Channels represent different distribution points for catalog content, including physical locations and online platforms. Use this to get detailed information about
  - body: { channel_id: string }
- `POST https://api.mcp.ai/api/square/retrieve/channels/bulk` — Tool to bulk retrieve multiple Square channels by their IDs in a single request. Use when you need to fetch specific channels by their unique identifiers rather than listing all channels.
  - body: { channel_ids: string[] }
- `POST https://api.mcp.ai/api/square/retrieve/customer` — Tool to retrieve detailed information about a specific Square customer by ID. Use when you need to fetch customer profile data including contact information, preferences, and group memberships.
  - body: { customer_id: string }
- `POST https://api.mcp.ai/api/square/retrieve/customer/group` — Tool to retrieve a specific Square customer group by ID. Use when you need to fetch details about a customer group including its name and timestamps.
  - body: { group_id: string }
- `POST https://api.mcp.ai/api/square/retrieve/customer/segment` — Tool to retrieve a specific customer segment by its ID. Use when you need to get details about a customer segment including its name and timestamps.
  - body: { segment_id: string }
- `POST https://api.mcp.ai/api/square/retrieve/dispute` — Tool to retrieve a Square dispute by ID. Endpoint: GET /v2/disputes/{dispute_id}
  - body: { dispute_id: string }
- `POST https://api.mcp.ai/api/square/retrieve/inventory/changes` — Retrieves the inventory change history for a catalog object at specified locations. Returns adjustments, physical counts, and transfers sorted by occurrence timestamp (newest first). Use this action w
  - body: { cursor?: string, location_ids?: string, catalog_object_id: string }
- `POST https://api.mcp.ai/api/square/retrieve/inventory/counts/batch` — Retrieve inventory counts for multiple catalog objects and locations in a single batch request. Use this action when you need to efficiently check inventory levels across multiple item variations, loc
  - body: { limit?: integer, cursor?: string, states?: string[], location_ids?: string[], updated_after?: string, catalog_object_ids?: string[] }
- `POST https://api.mcp.ai/api/square/retrieve/location` — Tool to retrieve detailed information about a specific Square location by ID. Use when you need to get complete details about a specific location, including address, business hours, contact informatio
  - body: { location_id: string }
- `POST https://api.mcp.ai/api/square/retrieve/location/custom/attribute` — Retrieves a custom attribute associated with a location in Square. Use this when you need to access specific custom data associated with a location, such as metadata, external IDs, or other merchant-d
  - body: { key: string, version?: integer, location_id: string, with_definition?: boolean }
- `POST https://api.mcp.ai/api/square/retrieve/location/custom/attribute/definition` — Tool to retrieve a location-related custom attribute definition. Use when you need to get the schema, visibility, and metadata for a custom attribute associated with locations.
  - body: { key: string, version?: integer }
- `POST https://api.mcp.ai/api/square/retrieve/merchant/custom/attribute` — Retrieves a custom attribute associated with a merchant in Square. Use this when you need to access specific custom data associated with a merchant, such as metadata, external IDs, or other merchant-d
  - body: { key: string, version?: integer, merchant_id: string, with_definition?: boolean }
- `POST https://api.mcp.ai/api/square/retrieve/merchant/custom/attribute/definition` — Tool to retrieve a merchant-related custom attribute definition from Square. Use when you need to fetch the schema, visibility, or metadata of a specific custom attribute definition by its key.
  - body: { key: string, version?: integer }
- `POST https://api.mcp.ai/api/square/retrieve/merchants` — Tool to retrieve merchant information including status, main location details, and capabilities using Square's GraphQL API. Use when you need to fetch merchant profile data for specific merchant IDs.
  - body: { merchant_ids: string[] }
- `POST https://api.mcp.ai/api/square/retrieve/order` — Retrieves detailed information about a specific Square order by its ID. Use this tool when you need to: - Fetch complete details of an order including line items, pricing, taxes, and discounts - Check
  - body: { order_id: string }
- `POST https://api.mcp.ai/api/square/retrieve/payment/link` — Retrieves a Square-hosted payment link by ID. Returns complete payment link details including the checkout URL, associated order ID, checkout options, pre-populated buyer data, and creation timestamps
  - body: { id: string }
- `POST https://api.mcp.ai/api/square/retrieve/token/status` — Tool to retrieve information about an OAuth access token or personal access token. Use when you need to verify token validity, check token expiration, inspect authorized scopes, or validate merchant a
- `POST https://api.mcp.ai/api/square/retrieve/webhook/subscription` — Retrieve a Square webhook subscription by its ID. Returns subscription details including name, enabled status, event types, notification URL, and signature key. Note: Requires personal access token au
  - body: { subscription_id: string }
- `POST https://api.mcp.ai/api/square/search/booking/availability` — Searches for available appointment time slots for booking services at Square locations. Use this action when you need to find open booking slots for a specific service, location, and time range. This 
  - body: { query: object }
- `POST https://api.mcp.ai/api/square/search/catalog/objects` — Searches for catalog objects (items, categories, taxes, discounts, etc.) in the Square catalog. Use this action when you need to find specific catalog items by name, SKU, category, or other attributes
  - body: { limit?: integer, query?: object, cursor?: string, begin_time?: string, object_types?: string[], include_deleted_objects?: boolean, include_related_objects?: boolean, include_category_path_to_root?: boolean }
- `POST https://api.mcp.ai/api/square/search/customers` — Tool to search customer profiles in Square Customer Directory. Use when you need to find customers by email, phone, creation date, or other filters. Returns paginated results with optional total count
  - body: { count?: boolean, limit?: integer, query?: object, cursor?: string }
- `POST https://api.mcp.ai/api/square/search/orders` — Tool to search orders across one or more Square locations with filters. Use when you need to find orders within a date range, by state, by customer, or other criteria. This is the primary way Square e
  - body: { limit?: integer, query?: object, cursor?: string, location_ids: string[], return_entries?: boolean }
- `POST https://api.mcp.ai/api/square/submit/dispute/evidence` — Submits evidence for a dispute to the cardholder's bank. IMPORTANT: You must upload evidence FIRST using CreateDisputeEvidenceText or CreateDisputeEvidenceFile before calling this endpoint. Once evide
  - body: { dispute_id: string }
- `POST https://api.mcp.ai/api/square/test/webhook/subscription` — Tests a webhook subscription by sending a test event to the configured notification URL. Use this to verify that your webhook endpoint is correctly receiving and processing Square events. The response
  - body: { event_type?: string, subscription_id: string }
- `POST https://api.mcp.ai/api/square/update/booking` — Updates an existing Square booking with new appointment details, times, notes, or team members. Use when you need to modify a booking's start time, change appointment segments, update customer or sell
  - body: { booking: object, booking_id: string, idempotency_key?: string }
- `POST https://api.mcp.ai/api/square/update/customer` — Tool to update an existing Square customer profile. Use when you need to modify customer details like name, email, address, or phone number. Supports sparse updates: only include fields you want to ch
  - body: { note?: string, address?: object, tax_ids?: object, version?: integer, birthday?: string, nickname?: string, given_name?: string, customer_id: string, family_name?: string, company_name?: string, phone_number?: string, reference_id?: string, email_address?: string }
- `POST https://api.mcp.ai/api/square/update/customer/custom/attribute/definition` — Tool to update a customer-related custom attribute definition in Square. Use when you need to modify the name, description, visibility, or schema of an existing custom attribute definition. Supports s
  - body: { key: string, name?: string, schema?: object, version?: integer, visibility?: string, description?: string }
- `POST https://api.mcp.ai/api/square/update/customer/group` — Tool to update a customer group's information by its ID. Use when you need to modify the name or other attributes of an existing customer group in Square.
  - body: { group: object, group_id: string }
- `POST https://api.mcp.ai/api/square/update/customers/bulk` — Tool to update multiple customer profiles in a single batch operation. Use when you need to efficiently update 1-100 customer profiles at once. Each update request includes the customer ID as a key an
  - body: { customers: object }
- `POST https://api.mcp.ai/api/square/update/location` — Tool to update an existing business location in a Square account. Use when you need to modify location details like name, description, address, business hours, contact information, or social media pro
  - body: { location: object, location_id: string }
- `POST https://api.mcp.ai/api/square/update/location/custom/attribute/definition` — Tool to update a location-related custom attribute definition in Square. Use when you need to modify the description, name, visibility, or schema of an existing location custom attribute definition.
  - body: { key: string, idempotency_key?: string, custom_attribute_definition: object }
- `POST https://api.mcp.ai/api/square/update/merchant/custom/attribute/definition` — Tool to update a merchant-related custom attribute definition in Square. Use when you need to modify the description, name, visibility, or schema of an existing merchant custom attribute definition.
  - body: { key: string, idempotency_key?: string, custom_attribute_definition: object }
- `POST https://api.mcp.ai/api/square/update/online/checkout/location/settings` — Tool to update location-level settings for Square online checkout. Use when you need to modify checkout configuration including customer notes, policies, branding, and tipping options for a specific l
  - body: { location_id: string, location_settings: object }
- `POST https://api.mcp.ai/api/square/update/order` — Updates an existing Square order by adding, modifying, or removing fields. Use for OPEN or DRAFT orders only (COMPLETED/CANCELED orders cannot be updated). Requires the current order version number fo
  - body: { order?: object, order_id: string, fields_to_clear?: string[], idempotency_key?: string }
- `POST https://api.mcp.ai/api/square/update/team/member` — Tool to update an existing Square team member's information. Use when you need to modify team member details like name, email, phone number, status, location assignments, or wage settings. Supports sp
  - body: { team_member: object, team_member_id: string }
- `POST https://api.mcp.ai/api/square/update/webhook/subscription` — Tool to update a Square webhook subscription. Use when you need to modify subscription settings such as name, enabled state, event types, notification URL, or API version of an existing webhook subscr
  - body: { name?: string, enabled?: boolean, api_version?: string, event_types?: string[], subscription_id: string, notification_url?: string }
- `POST https://api.mcp.ai/api/square/update/webhook/subscription/signature/key` — Tool to rotate the signature key for a webhook subscription. Use when you need to replace the current signature key for security purposes.
  - body: { idempotency_key?: string, subscription_id: string }
- `POST https://api.mcp.ai/api/square/upsert/catalog/object` — Creates or updates a catalog object in the Square catalog. Use when you need to add or modify items, variations, categories, taxes, discounts, or other catalog entities in the merchant's inventory sys
  - body: { object: object, idempotency_key: string }
- `POST https://api.mcp.ai/api/square/upsert/catalog/objects/batch` — Creates or updates multiple catalog objects in a single batch operation. Use this action when you need to efficiently manage catalog items, categories, discounts, taxes, or other catalog entities in b
  - body: { batches: object[], idempotency_key: string }
- `POST https://api.mcp.ai/api/square/upsert/customer/custom/attribute` — Tool to create or update a custom attribute for a customer profile. Use when you need to store custom data on a customer record, such as preferences, loyalty tiers, or external system IDs. The custom 
  - body: { key: string, customer_id: string, idempotency_key?: string, custom_attribute: object }
- `POST https://api.mcp.ai/api/square/upsert/customer/custom/attributes/batch` — Tool to create or update custom attributes for multiple customers in a single batch request. Use when you need to set custom data on customer profiles (e.g., preferences, loyalty tiers, tags). Support
  - body: { values: object }
- `POST https://api.mcp.ai/api/square/upsert/location/custom/attribute` — Tool to create or update a custom attribute for a location. Use when you need to store custom data on a location record, such as capacity limits, special features, or external system IDs. The custom a
  - body: { key: string, location_id: string, idempotency_key?: string, custom_attribute: object }
- `POST https://api.mcp.ai/api/square/upsert/locations/custom/attributes/batch` — Tool to create or update custom attributes for multiple locations in a single batch request. Use when you need to set custom data on location records (e.g., store ratings, delivery zones, tags). Suppo
  - body: { values: object }
- `POST https://api.mcp.ai/api/square/upsert/merchant/custom/attribute` — Tool to create or update a custom attribute for a merchant profile. Use when you need to store custom data on a merchant record, such as business notes, external system IDs, or configuration values. T
  - body: { key: string, merchant_id: string, idempotency_key?: string, custom_attribute: object }
- `POST https://api.mcp.ai/api/square/upsert/merchants/custom/attributes/batch` — Tool to create or update custom attributes for multiple merchants in a single batch request. Use when you need to set custom data on merchant profiles (e.g., business types, establishment dates, merch
  - body: { values: object }

## Example prompts
- "What can I do in Square?"
- "Show me a summary of my Square account"

## More
- Page: https://mcp.ai/square
- Agent spec (llms.txt): https://mcp.ai/square/llms.txt
- Postman collection: https://mcp.ai/square/postman.json