Square

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. This action is irreversible - once accepted, a dispute cannot be challenged. Only use after reviewing all evidence and determining that challenging the dispute is not viable. Note: Requires DISPUTES_WRITE permission scope.

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.

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 useful for integrating rewards, discounts, and complex pricing scenarios.

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 cancellation will update the booking status accordingly. This action is irreversible - once a booking is cancelled, it cannot be restored and must be rebooked if needed. Use the booking_version parameter to ensure safe concurrent updates.

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 terminal states (PAID, REFUNDED, CANCELED, FAILED) - Requires INVOICES_WRITE and ORDERS_WRITE OAuth scopes - Version number must match the current invoice version to prevent conflicts After cancellation, the associated order status is set to CANCELED and webhook events are triggered.

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 before settlement. Important: Only payments with APPROVED status can be canceled. Attempting to cancel a payment in any other status (COMPLETED, PENDING, CANCELED, FAILED) will result in an error. Once canceled, the payment status changes to CANCELED and the card details status changes to VOIDED. Required permissions: PAYMENTS_WRITE

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 update inventory quantities for multiple items or locations at once, either through physical stock counts or adjustments (e.g., receiving stock, recording waste, or correcting discrepancies). Supports up to 100 inventory changes per request. Each change can be either a PHYSICAL_COUNT (setting absolute quantity) or an ADJUSTMENT (modifying quantity with state transitions). The ignore_unchanged_counts parameter controls whether calculated counts are returned in the response.

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.

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.

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 required.

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 structured data on customers beyond the standard fields.

Tool to create a new customer group for a business. Use when you need to organize customers into groups for targeted marketing or segmentation.

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.

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 SubmitEvidence to finalize the dispute challenge. Endpoint: POST /v2/disputes/{dispute_id}/evidence-text

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 (withdraw funds), CLEAR_BALANCE (set balance to zero), DEACTIVATE (permanently block), ADJUST_INCREMENT/ADJUST_DECREMENT (manual adjustments), REFUND (restore funds from refunds), and others. Use this action when you need to modify a gift card's balance or state. Each activity type requires specific details in the corresponding activity_details field (e.g., activate_activity_details for ACTIVATE type). Either gift_card_id or gift_card_gan must be provided to identify the target gift card. Important: DEACTIVATE and CLEAR_BALANCE are destructive operations - DEACTIVATE permanently blocks the card from future balance changes, and CLEAR_BALANCE sets the balance to zero.

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 invoices in DRAFT, SCHEDULED, UNPAID, or PARTIALLY_PAID state. Square supports up to 10 attachments per invoice with a combined maximum size of 25 MB in production (1 KB in Sandbox). Supported file formats: GIF, JPEG, PNG, TIFF, BMP, PDF. Creating an attachment increments the invoice version and triggers an invoice.updated webhook event.

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.

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.

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 will have a state of DRAFT or OPEN depending on the configuration. Each line item must have a quantity and either a catalog_object_id (for catalog items) or both name and base_price_money (for custom items). You can optionally include taxes, discounts, service charges, and fulfillment information. Use when: Creating a new order for a customer transaction, building a cart for checkout, or initiating a sales order workflow.

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. The refund amount cannot exceed the original payment total minus any prior refunds.

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 Square account. The team member can then be assigned to locations and given access to Square products like Point of Sale. Requires given_name and family_name at minimum. Optionally specify email, phone, status (ACTIVE/INACTIVE), and location assignments.

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 need to permanently remove a catalog item, category, modifier, or other catalog object from Square. This action is irreversible — the catalog object cannot be recovered once deleted. Note: Only one delete request is processed at a time per seller account.

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 object are also deleted. Use this action when you need to remove multiple catalog objects (items, categories, modifiers, etc.) at once. This action is irreversible — the catalog objects cannot be recovered once deleted.

Tool to delete a Square customer profile. Use when you need to permanently remove a customer record from Square.

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.

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.

Tool to delete a customer group by its ID. Use when you need to permanently remove a customer group from Square.

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; failed deletions include error details. Note that delete events trigger separate webhook notifications per customer.

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 evidence after it has been submitted to the bank using the SubmitEvidence endpoint. The deletion is permanent and cannot be undone. Use this when: - You need to remove evidence that was uploaded by mistake - You want to replace evidence with a better version (delete old, upload new) - The evidence is no longer relevant to the dispute case Prerequisites: - A valid dispute_id (obtain from list/retrieve disputes) - A valid evidence_id (obtain from list evidence or create evidence response) - The evidence must not have been submitted to the bank yet

Tool to delete a Square invoice (only DRAFT invoices can be deleted).

Tool to delete an attachment from a Square invoice. Endpoint: DELETE /v2/invoices/{invoice_id}/attachments/{attachment_id}

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.

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 or incorrect custom attribute definitions from your Square account.

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 attributes owned by other applications, the attribute's visibility must be set to VISIBILITY_READ_WRITE_VALUES.

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.

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 or incorrect custom attribute definitions from your Square account.

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 other applications, the attribute's visibility must be set to VISIBILITY_READ_WRITE_VALUES.

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 application-level resources and require personal access token authentication (not OAuth tokens).

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 information, and current status. Use this action when you need to view or verify booking details for a known booking ID, check appointment times, or retrieve information about services and team members assigned to the booking. Required permission: APPOINTMENTS_READ (buyer-level) or both APPOINTMENTS_ALL_READ and APPOINTMENTS_READ (seller-level).

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 settings. This is an alpha feature.

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 details like business name, status, currency, and main location.

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-defined information. Requires CUSTOMERS_READ permission.

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.

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 merchant. Requires merchant ID filter.

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 evidence was uploaded successfully - Review evidence details before submitting a dispute response Note: This returns metadata only, not the actual file content. To upload evidence, use the Create Dispute Evidence File or Create Dispute Evidence Text actions. Endpoint: GET /v2/disputes/{dispute_id}/evidence/{evidence_id}

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 balances. Returns the complete gift card object including ID, type, state, balance, and associated customer IDs.

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, attachments, and current status. Use this when you need to view or verify invoice details for a known invoice ID. Required permission: INVOICES_READ

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 expiration schedules. This action provides read-only access to loyalty program membership details.

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' as the merchant_id to retrieve the currently authenticated merchant.

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 location.

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 this action when you need to retrieve detailed information about a specific refund, such as verifying refund status, checking refund amounts, or accessing refund metadata for reconciliation or customer service purposes.

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 variation, associated customer, and scheduled actions. Returns comprehensive subscription data including payment information, invoices, phases, and configured actions. Required permission: SUBSCRIPTIONS_READ.

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 settings.

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 gift card for tracking purchases, balances, or gifting purposes.

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 maximum of 25 cards per request with pagination support.

Tool to list requested channels from Square. Use when you need to retrieve channel information for a specific reference type, reference ID, or status.

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.

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.

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 each attribute.

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.