Square
Your Toolhouse AI Worker can connect to Square using 96 specialized tools.
Auth Connection
This service requires an auth connection to use its tools. You can set this up in your Toolhouse dashboard under Auth Connections.
Tools (96)
Square Accept Dispute
Square Accept DisputeIntegration name: 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. 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.
Parameters
Your Toolhouse AI worker will automatically pass these parameters as input when the tool is called.
dispute_id
string
✅
"bVuPw2Du5akQzRtCEupon3GB"
The Square-generated unique ID of the dispute to accept. Accepting a dispute acknowledges liability and cannot be reversed.
Square Add Group To Customer
Square Add Group To CustomerIntegration name: 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.
Parameters
Your Toolhouse AI worker will automatically pass these parameters as input when the tool is called.
group_id
string
✅
"1DGFASHZ4A66X3YD4SFV3NTBNJ"
The ID of the customer group to add the customer to. This is the unique Square-generated group identifier.
customer_id
string
✅
"CEH5ANS6J5N3VSZDM5CJCDY428"
The ID of the customer to add to a group. This is the unique Square-generated customer identifier.
Square Calculate Order
Square Calculate OrderIntegration name: 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 useful for integrating rewards, discounts, and complex pricing scenarios.
Parameters
Your Toolhouse AI worker will automatically pass these parameters as input when the tool is called.
order
object
✅
—
The order to be calculated. Expects the entire order, not a sparse update. Must include location_id and line_items with pricing information.
proposed_rewards
array
—
Identifies one or more loyalty reward tiers to apply during the order calculation. These are preview-only; no actual redemptions occur.
Square Cancel Invoice
Square Cancel InvoiceIntegration name: 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 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.
Parameters
Your Toolhouse AI worker will automatically pass these parameters as input when the tool is called.
version
integer
✅
2
The current version number of the invoice. This must exactly match the invoice's current version on the server to prevent race conditions. Obtain the version from GET_INVOICE or LIST_INVOICES actions.
invoice_id
string
✅
"inv_1a2b3c4d5e6f"
The Square-assigned ID of the invoice to cancel. Obtain this from GET_INVOICE or LIST_INVOICES actions.
Square Cancel Payment
Square Cancel PaymentIntegration name: 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 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
Parameters
Your Toolhouse AI worker will automatically pass these parameters as input when the tool is called.
payment_id
string
✅
"KkAkhdMsgzn59SM8A89WgKwekxLZY"
The unique ID of the payment to cancel. The payment must be in APPROVED status. You can obtain payment IDs from the List Payments endpoint or from payment creation responses.
Square Create Bulk Customers
Square Create Bulk CustomersIntegration name: 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.
Parameters
Your Toolhouse AI worker will automatically pass these parameters as input when the tool is called.
customers
object
✅
{"test-key-001":{"given_name":"John","family_name":"Doe","email_address":"john.doe@example.com"}}
A map containing 1 to 100 individual customer creation requests. Each entry uses an idempotency key as the key and customer data as the value. Each customer must include at least one of: given_name, family_name, company_name, email_address, or phone_number.
Square Create Card
Square Create CardIntegration name: 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.
Parameters
Your Toolhouse AI worker will automatically pass these parameters as input when the tool is called.
card
object
✅
—
Details of the card and customer to store on file.
source_id
string
✅
—
Card nonce or payment ID used as the source of card data.
idempotency_key
string
✅
—
Unique key for this CreateCard request (1–45 characters).
verification_token
string
—
Token from Payments.verifyBuyer() for SCA/3-D Secure verification.
Square Create Customer
Square Create CustomerIntegration name: 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 required.
Parameters
Your Toolhouse AI worker will automatically pass these parameters as input when the tool is called.
note
string
—
A custom note associated with the customer profile.
address
object
—
Represents a physical postal address.
tax_ids
object
—
Tax ID information for EU/UK sellers.
birthday
string
—
The birthday associated with the customer profile. Format: YYYY-MM-DD or MM-DD. Returns as YYYY-MM-DD.
nickname
string
—
A nickname for the customer profile.
given_name
string
—
The given name (first name) associated with the customer profile. At least one of given_name, family_name, company_name, email_address, or phone_number is required.
family_name
string
—
The family name (last name) associated with the customer profile. At least one of given_name, family_name, company_name, email_address, or phone_number is required.
company_name
string
—
A business name associated with the customer profile. At least one of given_name, family_name, company_name, email_address, or phone_number is required.
phone_number
string
—
The phone number associated with the customer profile. Should be 9-16 digits, with optional '+' prefix. At least one of given_name, family_name, company_name, email_address, or phone_number is required.
reference_id
string
—
An optional second ID used to associate the customer profile with an entity in another system.
email_address
string
—
The email address associated with the customer profile. Must be a valid email format. At least one of given_name, family_name, company_name, email_address, or phone_number is required.
idempotency_key
string
—
A unique key to ensure idempotent request processing. Recommended for all create operations.
Square Create Customer Custom Attribute Definition
Square Create Customer Custom Attribute DefinitionIntegration name: 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 structured data on customers beyond the standard fields.
Parameters
Your Toolhouse AI worker will automatically pass these parameters as input when the tool is called.
idempotency_key
string
"idempotency-20260216-143025"
Unique key for this request to ensure idempotency. Prevents duplicate definitions from being created if the request is retried.
custom_attribute_definition
object
✅
—
The custom attribute definition to create for customers.
Square Create Customer Group
Square Create Customer GroupIntegration name: 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.
Parameters
Your Toolhouse AI worker will automatically pass these parameters as input when the tool is called.
group
object
✅
—
The customer group object containing the name and other properties.
idempotency_key
string
"a1b2c3d4-e5f6-7890-abcd-ef1234567890"
A unique identifier for this request to ensure idempotent behavior. If the same idempotency key is reused, Square returns the cached response from the original request.
Square Create Dispute Evidence File
Square Create Dispute Evidence FileIntegration name: 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.
Parameters
Your Toolhouse AI worker will automatically pass these parameters as input when the tool is called.
file
object
✅
—
The file to upload as dispute evidence (max 5 MB).
dispute_id
string
✅
"DISPUTE_ID_123"
The ID of the dispute to upload evidence for.
content_type
string
"image/jpeg"
Optional MIME type of the uploaded file. Must be one of image/heic, image/heif, image/jpeg, application/pdf, image/png, image/tiff.
evidence_type
string
null
Optional type of evidence. Allowed values include GENERIC_EVIDENCE, ONLINE_OR_APP_ACCESS_LOG, AUTHORIZATION_DOCUMENTATION, CANCELLATION_OR_REFUND_DOCUMENTATION, CARDHOLDER_COMMUNICATION, CARDHOLDER_INFORMATION, PURCHASE_ACKNOWLEDGEMENT, DUPLICATE_CHARGE_DOCUMENTATION, PRODUCT_OR_SERVICE_DESCRIPTION, RECEIPT, SERVICE_RECEIVED_DOCUMENTATION, PROOF_OF_DELIVERY_DOCUMENTATION, RELATED_TRANSACTION_DOCUMENTATION, REBUTTAL_EXPLANATION, TRACKING_NUMBER.
idempotency_key
string
✅
"IDEMPOTENCY_KEY_ABC123"
A unique key for this upload to ensure idempotency (max 45 characters).
inline_file_name
string
"evidence.png"
Optional filename for inline file content. Defaults to the original filename.
inline_file_mimetype
string
"image/png"
Optional MIME type for inline file content. Defaults to the FileUploadable mimetype or application/octet-stream.
inline_file_content_base64
string
"iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mP8/x8AAwMBAQF9oJwAAAAASUVORK5CYII="
Optional base64-encoded file content. When provided, the file will be uploaded from this inline content instead of fetching from FileUploadable storage.
Square Create Dispute Evidence Text
Square Create Dispute Evidence TextIntegration name: 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 SubmitEvidence to finalize the dispute challenge. Endpoint: POST /v2/disputes/{dispute_id}/evidence-text
Parameters
Your Toolhouse AI worker will automatically pass these parameters as input when the tool is called.
dispute_id
string
✅
"DISPUTE_ID_123"
The ID of the dispute to upload text evidence for.
evidence_text
string
✅
"Customer acknowledged receipt via email on 2024-10-01."
The text string to upload as evidence (max 500 characters).
evidence_type
string
null
Optional type of evidence. If not provided, defaults to GENERIC_EVIDENCE. Allowed values: GENERIC_EVIDENCE, ONLINE_OR_APP_ACCESS_LOG, AUTHORIZATION_DOCUMENTATION, CANCELLATION_OR_REFUND_DOCUMENTATION, CARDHOLDER_COMMUNICATION, CARDHOLDER_INFORMATION, PURCHASE_ACKNOWLEDGEMENT, DUPLICATE_CHARGE_DOCUMENTATION, PRODUCT_OR_SERVICE_DESCRIPTION, RECEIPT, SERVICE_RECEIVED_DOCUMENTATION, PROOF_OF_DELIVERY_DOCUMENTATION, RELATED_TRANSACTION_DOCUMENTATION, REBUTTAL_EXPLANATION, TRACKING_NUMBER.
idempotency_key
string
✅
"IDEMPOTENCY_KEY_ABC123"
A unique key identifying the request (max 45 characters).
Square Create Invoice Attachment
Square Create Invoice AttachmentIntegration name: 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 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.
Parameters
Your Toolhouse AI worker will automatically pass these parameters as input when the tool is called.
file
object
✅
—
File to upload and attach to the invoice. Supported formats: GIF, JPEG, PNG, TIFF, BMP, or PDF.
invoice_id
string
✅
"inv:0-ChCHu2mZEabLeeHahQnXDjZQECY"
The ID of the invoice to attach the file to. The invoice must be in DRAFT, SCHEDULED, UNPAID, or PARTIALLY_PAID state.
description
string
"Purchase receipt"
Description text for the attachment that will be displayed on the invoice. Maximum 128 characters.
idempotency_key
string
"create-attachment-2024-01-15-001"
A unique string to ensure idempotency for this request. Prevents duplicate attachments if the same request is sent multiple times. Maximum 128 characters.
Square Create Location
Square Create LocationIntegration name: 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.
Parameters
Your Toolhouse AI worker will automatically pass these parameters as input when the tool is called.
location
object
✅
—
Details of the location to create.
Square Create Location Custom Attribute Definition
Square Create Location Custom Attribute DefinitionIntegration name: 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.
Parameters
Your Toolhouse AI worker will automatically pass these parameters as input when the tool is called.
idempotency_key
string
"test-idempotency-1739678400-abc123"
Unique string ensuring idempotency for safe request retry (maximum 45 characters).
custom_attribute_definition
object
✅
—
The custom attribute definition to create for locations.
Square Delete Customer
Square Delete CustomerIntegration name: SQUARE_DELETE_CUSTOMER
Tool to delete a Square customer profile. Use when you need to permanently remove a customer record from Square.
Parameters
Your Toolhouse AI worker will automatically pass these parameters as input when the tool is called.
version
integer
0
The current version of the customer profile. As a best practice, you should include this parameter to enable optimistic concurrency control. For more information, see Delete a customer profile documentation.
customer_id
string
✅
"BRQX2Y5QPCEW8MRS6X661CW80C"
The ID of the customer to delete.
Square Delete Customer Custom Attribute
Square Delete Customer Custom AttributeIntegration name: 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.
Parameters
Your Toolhouse AI worker will automatically pass these parameters as input when the tool is called.
key
string
✅
"test_curl_attr"
The key of the custom attribute to delete. This key must match the key of a custom attribute definition in the Square seller account. If the requesting application is not the definition owner, you must use the qualified key.
customer_id
string
✅
"CEH5ANS6J5N3VSZDM5CJCDY428"
The ID of the target customer profile. You can obtain this from listing customers or from a specific customer retrieval.
Square Delete Customer Custom Attribute Definition
Square Delete Customer Custom Attribute DefinitionIntegration name: 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.
Parameters
Your Toolhouse AI worker will automatically pass these parameters as input when the tool is called.
key
string
✅
"customer_loyalty_tier_20260216"
The key of the custom attribute definition to delete.
Square Delete Customer Group
Square Delete Customer GroupIntegration name: 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.
Parameters
Your Toolhouse AI worker will automatically pass these parameters as input when the tool is called.
group_id
string
✅
"3SJ1AQ3YZVFV5SB2WQJ8R0PNYT"
The ID of the customer group to delete.
Square Delete Customers Bulk
Square Delete Customers BulkIntegration name: 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; failed deletions include error details. Note that delete events trigger separate webhook notifications per customer.
Parameters
Your Toolhouse AI worker will automatically pass these parameters as input when the tool is called.
customer_ids
array
✅
["102Z0AA3E9BMN2WHAMR5WP3E4C","JDKYHBWT1D4F8MFH63DBMEN8Y4"]
An array containing the IDs of the customer profiles to delete. Minimum 1 and maximum 100 customer IDs.
Square Delete Dispute Evidence
Square Delete Dispute EvidenceIntegration name: 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 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
Parameters
Your Toolhouse AI worker will automatically pass these parameters as input when the tool is called.
dispute_id
string
✅
"bVTprrwk0gygTLZ96VX1oB"
The unique ID of the dispute from which to remove evidence. You can obtain this from listing disputes or from a specific dispute retrieval.
evidence_id
string
✅
"CpfnkwGselCwS8QFvxN6"
The unique ID of the evidence item to delete. You can obtain this from the list dispute evidence endpoint or from the response when creating evidence.
Square Delete Invoice
Square Delete InvoiceIntegration name: SQUARE_DELETE_INVOICE
Tool to delete a Square invoice (only DRAFT invoices can be deleted).
Parameters
Your Toolhouse AI worker will automatically pass these parameters as input when the tool is called.
version
integer
1
The version of the invoice to delete. If you do not know the version, retrieve the invoice first via Get Invoice or List Invoices.
invoice_id
string
✅
"inv:0-ChCHu2mZEabLeeHahQnXDjZQECY"
The Square-assigned ID of the invoice to delete. Format: 'inv:0-' followed by an alphanumeric string.
Square Delete Invoice Attachment
Square Delete Invoice AttachmentIntegration name: SQUARE_DELETE_INVOICE_ATTACHMENT
Tool to delete an attachment from a Square invoice. Endpoint: DELETE /v2/invoices/{invoice_id}/attachments/{attachment_id}
Parameters
Your Toolhouse AI worker will automatically pass these parameters as input when the tool is called.
invoice_id
string
✅
"inv:0-ChCHu2mZEabLeeHahQnXDjZQECY"
The Square-assigned ID of the invoice to delete the attachment from. Format: 'inv:0-' followed by an alphanumeric string.
attachment_id
string
✅
"ATTACHMENT_ID_456"
The ID of the attachment to delete.
Square Delete Location Custom Attribute
Square Delete Location Custom AttributeIntegration name: 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.
Parameters
Your Toolhouse AI worker will automatically pass these parameters as input when the tool is called.
key
string
✅
"test-attribute-1739678400"
The key of the custom attribute to delete. This key must match the key of a custom attribute definition in the Square seller account. If the requesting application is not the definition owner, you must use the qualified key.
location_id
string
✅
"L9YZVY8XPTC15"
The ID of the target location. You can obtain this from the List Locations endpoint.
Square Delete Location Custom Attribute Definition
Square Delete Location Custom Attribute DefinitionIntegration name: 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 or incorrect custom attribute definitions from your Square account.
Parameters
Your Toolhouse AI worker will automatically pass these parameters as input when the tool is called.
key
string
✅
"test_delete_attr_20260216"
The key of the custom attribute definition to delete.
Square Delete Locations Custom Attributes Batch
Square Delete Locations Custom Attributes BatchIntegration name: 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 attributes owned by other applications, the attribute's visibility must be set to VISIBILITY_READ_WRITE_VALUES.
Parameters
Your Toolhouse AI worker will automatically pass these parameters as input when the tool is called.
values
object
✅
{"id1":{"key":"bestseller","location_id":"L0TBCBTB7P8RQ"},"id2":{"key":"test-attribute","location_id":"L9XMD04V3STJX"}}
A map of unique identifiers to delete request objects. Each key is a unique identifier for mapping the request to the response. Each value contains location_id and key fields for the custom attribute to delete.
Square Delete Merchant Custom Attribute
Square Delete Merchant Custom AttributeIntegration name: 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.
Parameters
Your Toolhouse AI worker will automatically pass these parameters as input when the tool is called.
key
string
✅
"test-attr-delete"
The key of the custom attribute to delete. This key must match the key of a custom attribute definition in the Square seller account. If the requesting application is not the definition owner, you must use the qualified key.
merchant_id
string
✅
"MLBN7K732KMAD"
The ID of the target merchant. You can obtain this from the List Merchants endpoint or from your Square dashboard.
Square Delete Merchant Custom Attribute Definition
Square Delete Merchant Custom Attribute DefinitionIntegration name: 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 or incorrect custom attribute definitions from your Square account.
Parameters
Your Toolhouse AI worker will automatically pass these parameters as input when the tool is called.
key
string
✅
"test_delete_attr_1739679600"
The key of the custom attribute definition to delete.
Square Delete Merchants Custom Attributes Batch
Square Delete Merchants Custom Attributes BatchIntegration name: 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 other applications, the attribute's visibility must be set to VISIBILITY_READ_WRITE_VALUES.
Parameters
Your Toolhouse AI worker will automatically pass these parameters as input when the tool is called.
values
object
✅
{"delete-request-1":{"key":"test_delete_attr","merchant_id":"MLBN7K732KMAD"},"delete-request-2":{"key":"merchant-attribute","merchant_id":"MLBN7K732KMAD"}}
A map of unique identifiers to delete request objects. Each key is a unique identifier for mapping the request to the response. Each value contains merchant_id and key fields for the custom attribute to delete.
Square Delete Webhook Subscription
Square Delete Webhook SubscriptionIntegration name: 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 application-level resources and require personal access token authentication (not OAuth tokens).
Parameters
Your Toolhouse AI worker will automatically pass these parameters as input when the tool is called.
subscription_id
string
✅
"sub_123456789"
ID of the webhook subscription to delete.
Square Get Business Booking Profile
Square Get Business Booking ProfileIntegration name: 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 settings. This is an alpha feature.
Parameters
Your Toolhouse AI worker will automatically pass these parameters as input when the tool is called.
merchant_ids
array
✅
["MLBN7K732KMAD"]
List of merchant IDs to query booking profiles for. Use the merchant ID from your Square account (e.g., 'MLBN7K732KMAD'). At least one merchant ID is required.
Square Get Current Merchant
Square Get Current MerchantIntegration name: 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 details like business name, status, currency, and main location.
Parameters
Your Toolhouse AI worker will automatically pass these parameters as input when the tool is called.
No parameters required.
Square Get Customer Custom Attribute
Square Get Customer Custom AttributeIntegration name: 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-defined information. Requires CUSTOMERS_READ permission.
Parameters
Your Toolhouse AI worker will automatically pass these parameters as input when the tool is called.
key
string
✅
"favoritemovie"
The key of the custom attribute to retrieve. This key must match the key of a custom attribute definition in the Square seller account. If the requesting application is not the definition owner, you must use the qualified key.
version
integer
—
The current version of the custom attribute, which is used for strongly consistent reads to guarantee that you receive the most up-to-date data. When included in the request, Square returns the specified version or a higher version if one exists. If the specified version is higher than the current version, Square returns a BAD_REQUEST error.
customer_id
string
✅
"CEH5ANS6J5N3VSZDM5CJCDY428"
The ID of the target customer profile. This is the unique Square-assigned ID that identifies the customer.
with_definition
boolean
—
Indicates whether to return the custom attribute definition in the definition field of the custom attribute. Set this parameter to true to get the name and description of the custom attribute, information about the data type, or other definition details. The default value is false.
Square Get Customers Custom Attribute Definitions
Square Get Customers Custom Attribute DefinitionsIntegration name: 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.
Parameters
Your Toolhouse AI worker will automatically pass these parameters as input when the tool is called.
key
string
✅
"favoritemovie"
The key of the custom attribute definition to retrieve. If the requesting application is not the definition owner, you must use the qualified key.
version
integer
—
The current version of the custom attribute definition, which is used for strongly consistent reads to guarantee that you receive the most up-to-date data. When included in the request, Square returns the specified version or a higher version if one exists. If the specified version is higher than the current version, Square returns a BAD_REQUEST error.
Square Get Customers Graphql
Square Get Customers GraphqlIntegration name: 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 merchant. Requires merchant ID filter.
Parameters
Your Toolhouse AI worker will automatically pass these parameters as input when the tool is called.
limit
integer
50
Maximum number of customer records to return in a single request (1-100). If not specified, the API default applies.
merchant_id
string
✅
"MLBN7K732KMAD"
The merchant ID to filter customers. Required to retrieve customers from the Customer Directory. This is the Square location or business identifier.
Square Get Dispute Evidence
Square Get Dispute EvidenceIntegration name: 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 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}
Parameters
Your Toolhouse AI worker will automatically pass these parameters as input when the tool is called.
dispute_id
string
✅
"bVTprrwk0gygTLZ96VX1oB"
The ID of the dispute for which to retrieve evidence. You can obtain dispute IDs by listing disputes or from dispute webhooks.
evidence_id
string
✅
"zvW7kMPLh5QxN2RnD8VjJx"
The ID of the specific evidence item to retrieve. You can obtain evidence IDs by listing evidence for a dispute or from the response when creating evidence.
Square Get Invoice
Square Get InvoiceIntegration name: 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, attachments, and current status. Use this when you need to view or verify invoice details for a known invoice ID. Required permission: INVOICES_READ
Parameters
Your Toolhouse AI worker will automatically pass these parameters as input when the tool is called.
invoice_id
string
✅
"inv:0-ChCHu2mZEabLeeHahQnXDjZQECY"
The Square-assigned ID of the invoice to retrieve. Format: 'inv:0-' followed by an alphanumeric string.
Square Get Merchant
Square Get MerchantIntegration name: 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' as the merchant_id to retrieve the currently authenticated merchant.
Parameters
Your Toolhouse AI worker will automatically pass these parameters as input when the tool is called.
merchant_id
string
✅
"DM7VKY8Q63GNP"
The ID of the merchant to retrieve. Use 'me' to retrieve the merchant that is currently accessible to this call.
Square Get Online Checkout Location Settings
Square Get Online Checkout Location SettingsIntegration name: 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 location.
Parameters
Your Toolhouse AI worker will automatically pass these parameters as input when the tool is called.
location_id
string
✅
"L9YZVY8XPTC15"
The ID of the location for which to retrieve online checkout settings. This is the unique Square-generated identifier for the location.
Square List Channels
Square List ChannelsIntegration name: 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.
Parameters
Your Toolhouse AI worker will automatically pass these parameters as input when the tool is called.
limit
integer
50
Maximum number of results to return. When not provided the returned results will be capped at 100 channels.
cursor
string
"Y3Vyc29yOnRocmVlLDE="
Cursor to fetch the next result. Pagination cursor returned by a previous call to this endpoint.
status
string
"ACTIVE"
Status of channel. Filter channels by their status (e.g., ACTIVE, INACTIVE).
reference_id
string
"L3HB3M4X4G76H"
ID of reference associated to channel. Filter channels by the reference ID.
reference_type
string
"LOCATION"
Type of reference associated to channel. Filter channels by the reference type.
Square List Customer Custom Attribute Definitions
Square List Customer Custom Attribute DefinitionsIntegration name: 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.
Parameters
Your Toolhouse AI worker will automatically pass these parameters as input when the tool is called.
limit
integer
20
The maximum number of results to return in a single paged response. This limit is advisory. The response might contain more or fewer results. The minimum value is 1 and the maximum value is 100. The default value is 20. For more information, see Pagination.
cursor
string
"Y3Vyc29yOnRocmVlLDE="
The cursor returned in the paged response from the previous call to this endpoint. Provide this cursor to retrieve the next page of results for your original request. For more information, see Pagination.
Square List Customer Custom Attribute Definitions Graph Ql
Square List Customer Custom Attribute Definitions Graph QlIntegration name: 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.
Parameters
Your Toolhouse AI worker will automatically pass these parameters as input when the tool is called.
merchant_ids
array
✅
["MLBN7K732KMAD"]
List of merchant IDs to filter custom attribute definitions. Only definitions associated with these merchant IDs will be returned.
Square List Customer Custom Attributes
Square List Customer Custom AttributesIntegration name: 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 each attribute.
Parameters
Your Toolhouse AI worker will automatically pass these parameters as input when the tool is called.
limit
integer
20
The maximum number of results to return in a single paged response. This limit is advisory. The response might contain more or fewer results. The minimum value is 1 and the maximum value is 100. The default value is 20.
cursor
string
—
The cursor returned in the paged response from the previous call to this endpoint. Provide this cursor to retrieve the next page of results for your original request.
customer_id
string
✅
"CEH5ANS6J5N3VSZDM5CJCDY428"
The ID of the target customer profile. You can obtain this from listing customers or from a specific customer retrieval.
with_definitions
boolean
true
Indicates whether to return the custom attribute definition in the definition field of each custom attribute. Set this parameter to true to get the name and description of each custom attribute, information about the data type, or other definition details. The default value is false.
Square List Customer Groups
Square List Customer GroupsIntegration name: 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.
Parameters
Your Toolhouse AI worker will automatically pass these parameters as input when the tool is called.
limit
integer
50
The maximum number of results to return in a single page. This limit is advisory. The response might contain more or fewer results. If the limit is less than 1 or greater than 50, Square returns a 400 VALUE_TOO_LOW or 400 VALUE_TOO_HIGH error. The default value is 50.
cursor
string
"PNEhVUKBuTOuRIZoUcX5VQ"
A pagination cursor returned by a previous call to this endpoint. Provide this cursor to retrieve the next set of results for your original query. For more information, see Pagination.
Square List Customers
Square List CustomersIntegration name: 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 information (given_name, family_name, company_name, email_address, or phone_number).
Parameters
Your Toolhouse AI worker will automatically pass these parameters as input when the tool is called.
count
boolean
false
Indicates whether to return the total count of customers in the count field of the response. The default value is false.
limit
integer
50
The maximum number of results to return in a single page (1-100). If the specified limit is less than 1 or greater than 100, Square returns a 400 VALUE_TOO_LOW or 400 VALUE_TOO_HIGH error. The default value is 100.
cursor
string
"Y3Vyc29yOnRocmVlLDE="
A pagination cursor returned by a previous call to this endpoint. Provide this cursor to retrieve the next set of results for your original query.
sort_field
string
"DEFAULT"
Enum for customer sort field options.
sort_order
string
"ASC"
Enum for sort order options.
Square List Customer Segments
Square List Customer SegmentsIntegration name: 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.
Parameters
Your Toolhouse AI worker will automatically pass these parameters as input when the tool is called.
limit
integer
50
The maximum number of results to return in a single page. This limit is advisory. The response might contain more or fewer results. If the specified limit is less than 1 or greater than 50, Square returns a 400 VALUE_TOO_LOW or 400 VALUE_TOO_HIGH error. The default value is 50. For more information, see Pagination (https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination).
cursor
string
"PNEhVUKBuTOuRIZoUcX5VQ"
A pagination cursor returned by previous calls to ListCustomerSegments. This cursor is used to retrieve the next set of query results. For more information, see Pagination (https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination).
Square List Dispute Evidence
Square List Dispute EvidenceIntegration name: SQUARE_LIST_DISPUTE_EVIDENCE
Tool to list evidence items associated with a given dispute. Endpoint: GET /v2/disputes/{dispute_id}/evidence
Parameters
Your Toolhouse AI worker will automatically pass these parameters as input when the tool is called.
cursor
string
null
A pagination cursor returned by a previous call to this endpoint. Provide this to retrieve the next set of results.
dispute_id
string
✅
"DISPUTE_ID_123"
ID of the dispute to list evidence for.
Square List Invoices
Square List InvoicesIntegration name: SQUARE_LIST_INVOICES
Tool to list invoices for a Square location.
Parameters
Your Toolhouse AI worker will automatically pass these parameters as input when the tool is called.
limit
integer
50
Maximum number of invoices to return (1-200). Defaults to Square's default if unset.
cursor
string
"Y3Vyc29yOnRocmVlLDE="
Pagination cursor from a previous ListInvoices call; use to fetch the next page.
location_id
string
✅
"L3HB3M4X4G76H"
The Square location ID for which to list invoices.
Square List Location Custom Attribute Definitions
Square List Location Custom Attribute DefinitionsIntegration name: 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.
Parameters
Your Toolhouse AI worker will automatically pass these parameters as input when the tool is called.
limit
integer
20
The maximum number of results to return in a single paged response. This limit is advisory. The response might contain more or fewer results. The minimum value is 1 and the maximum value is 100. The default value is 20. For more information, see Pagination.
cursor
string
"Y3Vyc29yOnRocmVlLDE="
The cursor returned in the paged response from the previous call to this endpoint. Provide this cursor to retrieve the next page of results for your original request. For more information, see Pagination.
visibilityFilter
string
"VISIBILITY_READ_ONLY"
Filters the CustomAttributeDefinition results by their visibility values.
Square List Locations
Square List LocationsIntegration name: 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 or payments).
Parameters
Your Toolhouse AI worker will automatically pass these parameters as input when the tool is called.
No parameters required.
Square List Locations Custom Attributes
Square List Locations Custom AttributesIntegration name: 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.
Parameters
Your Toolhouse AI worker will automatically pass these parameters as input when the tool is called.
limit
integer
20
The maximum number of results to return in a single paged response. This limit is advisory. The response might contain more or fewer results. The minimum value is 1 and the maximum value is 100. The default value is 20. For more information, see Pagination.
cursor
string
"Y3Vyc29yOnRocmVlLDE="
The cursor returned in the paged response from the previous call to this endpoint. Provide this cursor to retrieve the next page of results for your original request. For more information, see Pagination.
location_id
string
✅
"L9YZVY8XPTC15"
The ID of the target location. This is the unique Square-assigned ID that identifies the location.
with_definitions
boolean
true
Indicates whether to return the custom attribute definition in the definition field of each custom attribute. Set this parameter to true to get the name and description of each custom attribute, information about the data type, or other definition details. The default value is false.
visibility_filter
string
"VISIBILITY_READ_ONLY"
Filters the CustomAttributeDefinition results by their visibility values. Possible values include VISIBILITY_READ_ONLY, VISIBILITY_READ_WRITE_VALUES, and VISIBILITY_HIDDEN.
Square List Merchant Custom Attribute Definitions
Square List Merchant Custom Attribute DefinitionsIntegration name: 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.
Parameters
Your Toolhouse AI worker will automatically pass these parameters as input when the tool is called.
limit
integer
20
The maximum number of results to return in a single paged response. This limit is advisory. The response might contain more or fewer results. The minimum value is 1 and the maximum value is 100. The default value is 20. For more information, see Pagination.
cursor
string
"Y3Vyc29yOnRocmVlLDE="
The cursor returned in the paged response from the previous call to this endpoint. Provide this cursor to retrieve the next page of results for your original request. For more information, see Pagination.
visibility_filter
string
"VISIBILITY_READ_ONLY"
Filters the CustomAttributeDefinition results by their visibility values.
Square List Merchants
Square List MerchantsIntegration name: 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.
Parameters
Your Toolhouse AI worker will automatically pass these parameters as input when the tool is called.
cursor
integer
123456
The cursor generated by the previous response. Provide this cursor to retrieve the next set of results.
Square List Merchants Custom Attributes
Square List Merchants Custom AttributesIntegration name: 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.
Parameters
Your Toolhouse AI worker will automatically pass these parameters as input when the tool is called.
limit
integer
20
The maximum number of results to return in a single paged response. This limit is advisory. The response might contain more or fewer results. The minimum value is 1 and the maximum value is 100. The default value is 20. For more information, see Pagination.
cursor
string
"Y3Vyc29yOnRocmVlLDE="
The cursor returned in the paged response from the previous call to this endpoint. Provide this cursor to retrieve the next page of results for your original request. For more information, see Pagination.
merchant_id
string
✅
"MLBN7K732KMAD"
The ID of the target merchant. This is the unique Square-assigned ID that identifies the merchant.
with_definitions
boolean
true
Indicates whether to return the custom attribute definition in the definition field of each custom attribute. Set this parameter to true to get the name and description of each custom attribute, information about the data type, or other definition details. The default value is false.
visibility_filter
string
"VISIBILITY_READ_ONLY"
Filters the CustomAttributeDefinition results by their visibility values. Possible values include VISIBILITY_READ_ONLY, VISIBILITY_READ_WRITE_VALUES, and VISIBILITY_HIDDEN.
Square List Payments
Square List PaymentsIntegration name: 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 reconciliation purposes.
Parameters
Your Toolhouse AI worker will automatically pass these parameters as input when the tool is called.
limit
integer
50
Maximum number of payments to return per page (1-100). Defaults to 100.
total
integer
10000
Filter by exact amount in the smallest currency unit (e.g., cents for USD) in total_money for a payment.
cursor
string
"Y3Vyc29yOnRocmVlLDE="
Pagination cursor returned by a previous call to this endpoint. Use to fetch the next page of results.
last_4
string
"1234"
Filter by the last four digits of a payment card.
end_time
string
"2024-12-31T23:59:59Z"
Indicates the end of the time range to retrieve payments for, in RFC 3339 format (e.g., '2024-12-31T23:59:59Z'). Defaults to current time if not provided.
begin_time
string
"2024-01-01T00:00:00Z"
Indicates the start of the time range to retrieve payments for, in RFC 3339 format (e.g., '2024-01-01T00:00:00Z'). Defaults to one year prior to current time if not provided.
card_brand
string
"VISA"
Filter by brand of the payment card (e.g., 'VISA', 'MASTERCARD', 'AMEX').
sort_field
string
"CREATED_AT"
Field to use for sorting results (e.g., 'CREATED_AT'). Defaults to CREATED_AT.
sort_order
string
"DESC"
Sort direction for results: 'ASC' (oldest first) or 'DESC' (newest first). Defaults to DESC.
location_id
string
"L3HB3M4X4G76H"
Limit results to the location supplied. If not provided, defaults to the main location.
offline_end_time
string
"2024-12-31T23:59:59Z"
End of the time range for offline payments, in RFC 3339 format.
is_offline_payment
boolean
false
Whether the payment was taken offline or not.
offline_begin_time
string
"2024-01-01T00:00:00Z"
Start of the time range for offline payments, in RFC 3339 format.
updated_at_end_time
string
"2024-12-31T23:59:59Z"
End of the time range to retrieve payments for based on updated_at field, in RFC 3339 format.
updated_at_begin_time
string
"2024-01-01T00:00:00Z"
Start of the time range to retrieve payments for based on updated_at field, in RFC 3339 format.
Square List Webhook Event Types
Square List Webhook Event TypesIntegration name: 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.
Parameters
Your Toolhouse AI worker will automatically pass these parameters as input when the tool is called.
api_version
string
"2024-08-21"
Overrides the application default API version (YYYY-MM-DD) for listing event types.
Square List Webhook Subscriptions
Square List Webhook SubscriptionsIntegration name: 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 creation date, and pagination for large result sets. Note: Webhook subscriptions are application-level resources and require personal access token authentication (not OAuth tokens).
Parameters
Your Toolhouse AI worker will automatically pass these parameters as input when the tool is called.
limit
integer
20
Maximum number of subscriptions to return (1-100). Defaults to Square's default if unset.
cursor
string
"CURSOR_123"
Pagination cursor from a previous call; use to fetch the next page.
sort_order
string
"ASC"
Sort order by creation time. Allowed values: 'ASC' or 'DESC'.
include_disabled
boolean
true
If true, include disabled subscriptions in the response. Defaults to false.
Square Remove Group From Customer
Square Remove Group From CustomerIntegration name: 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 group-specific benefits or targeting.
Parameters
Your Toolhouse AI worker will automatically pass these parameters as input when the tool is called.
group_id
string
✅
"1DGFASHZ4A66X3YD4SFV3NTBNJ"
The ID of the customer group to remove the customer from.
customer_id
string
✅
"CEH5ANS6J5N3VSZDM5CJCDY428"
The ID of the customer to remove from the group.
Square Retrieve Bulk Customers
Square Retrieve Bulk CustomersIntegration name: 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.
Parameters
Your Toolhouse AI worker will automatically pass these parameters as input when the tool is called.
customer_ids
array
✅
["CEH5ANS6J5N3VSZDM5CJCDY428","SE5FJ5Z5MSAPZGVX13916RJX04"]
The IDs of the customer profiles to retrieve. Must contain between 1 and 100 customer IDs. Provide the Square-assigned unique identifiers for each customer you want to retrieve.
Square Retrieve Channel
Square Retrieve ChannelIntegration name: 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 a specific channel, including its status, associated references, and metadata.
Parameters
Your Toolhouse AI worker will automatically pass these parameters as input when the tool is called.
channel_id
string
✅
"CH_6RMv8wKc6TGsx9yuIG1eIUxR2ZKkGBeBuirfYRlQuYC"
The unique Square-generated ID of the channel to retrieve. This is typically an alphanumeric string starting with 'CH_' (e.g., 'CH_6RMv8wKc6TGsx9yuIG1eIUxR2ZKkGBeBuirfYRlQuYC').
Square Retrieve Channels Bulk
Square Retrieve Channels BulkIntegration name: 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.
Parameters
Your Toolhouse AI worker will automatically pass these parameters as input when the tool is called.
channel_ids
array
✅
["CH_6RMv8wKc6TGsx9yuIG1eIUxR2ZKkGBeBuirfYRlQuYC","CH_7azrBwlEeOXvRvl0zG1eIUxR2ZKkGBeBuirfYRlQuYC"]
Array of channel IDs to retrieve in bulk. Each ID uniquely identifies a channel to fetch.
Square Retrieve Customer
Square Retrieve CustomerIntegration name: 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.
Parameters
Your Toolhouse AI worker will automatically pass these parameters as input when the tool is called.
customer_id
string
✅
"CEH5ANS6J5N3VSZDM5CJCDY428"
The ID of the customer to retrieve. This is the unique Square-generated customer identifier.
Square Retrieve Customer Group
Square Retrieve Customer GroupIntegration name: 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.
Parameters
Your Toolhouse AI worker will automatically pass these parameters as input when the tool is called.
group_id
string
✅
"28R7XKNSSCTJ9BEM9P09MJT9K7"
The ID of the customer group to retrieve. This is a unique Square-assigned identifier.
Square Retrieve Customer Segment
Square Retrieve Customer SegmentIntegration name: 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.
Parameters
Your Toolhouse AI worker will automatically pass these parameters as input when the tool is called.
segment_id
string
✅
"MLBN7K732KMAD.CARDS_ON_FILE"
The Square-issued ID of the customer segment to retrieve. This is a unique identifier for the segment (e.g., 'MLBN7K732KMAD.CARDS_ON_FILE'). You can obtain segment IDs from the List Customer Segments endpoint.
Square Retrieve Dispute
Square Retrieve DisputeIntegration name: SQUARE_RETRIEVE_DISPUTE
Tool to retrieve a Square dispute by ID. Endpoint: GET /v2/disputes/{dispute_id}
Parameters
Your Toolhouse AI worker will automatically pass these parameters as input when the tool is called.
dispute_id
string
✅
"DISPUTE_ID_123"
ID of the dispute to retrieve.
Square Retrieve Location
Square Retrieve LocationIntegration name: 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 information, and capabilities.
Parameters
Your Toolhouse AI worker will automatically pass these parameters as input when the tool is called.
location_id
string
✅
"main"
The ID of the location to retrieve. Specify the string 'main' to return the main location, or provide a specific location ID obtained from the List Locations endpoint.
Square Retrieve Location Custom Attribute
Square Retrieve Location Custom AttributeIntegration name: 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-defined information.
Parameters
Your Toolhouse AI worker will automatically pass these parameters as input when the tool is called.
key
string
✅
"general-manager"
The key of the custom attribute to retrieve. This key must match the key of a custom attribute definition in the Square seller account. If the requesting application is not the definition owner, you must use the qualified key.
version
integer
—
The current version of the custom attribute, which is used for strongly consistent reads to guarantee that you receive the most up-to-date data. When included in the request, Square returns the specified version or a higher version if one exists. If the specified version is higher than the current version, Square returns a BAD_REQUEST error.
location_id
string
✅
"L9YZVY8XPTC15"
The ID of the target location. You can obtain this from the List Locations endpoint.
with_definition
boolean
—
Indicates whether to return the custom attribute definition in the definition field of the custom attribute. Set this parameter to true to get the name and description of the custom attribute, information about the data type, or other definition details. The default value is false.
Square Retrieve Location Custom Attribute Definition
Square Retrieve Location Custom Attribute DefinitionIntegration name: 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.
Parameters
Your Toolhouse AI worker will automatically pass these parameters as input when the tool is called.
key
string
✅
"bestseller"
The key of the custom attribute definition to retrieve. If the requesting application is not the definition owner, you must use the qualified key.
version
integer
1
The current version of the custom attribute definition, which is used for strongly consistent reads to guarantee that you receive the most up-to-date data. When included in the request, Square returns the specified version or a higher version if one exists. If the specified version is higher than the current version, Square returns a BAD_REQUEST error.
Square Retrieve Merchant Custom Attribute
Square Retrieve Merchant Custom AttributeIntegration name: 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-defined information.
Parameters
Your Toolhouse AI worker will automatically pass these parameters as input when the tool is called.
key
string
✅
"test_attribute_composio"
The key of the custom attribute to retrieve. This key must match the key of a custom attribute definition in the Square seller account. If the requesting application is not the definition owner, you must use the qualified key.
version
integer
—
The current version of the custom attribute, which is used for strongly consistent reads to guarantee that you receive the most up-to-date data. When included in the request, Square returns the specified version or a higher version if one exists. If the specified version is higher than the current version, Square returns a BAD_REQUEST error.
merchant_id
string
✅
"MLBN7K732KMAD"
The ID of the target merchant. This is the unique Square-assigned ID that identifies the merchant.
with_definition
boolean
—
Indicates whether to return the custom attribute definition in the definition field of the custom attribute. Set this parameter to true to get the name and description of the custom attribute, information about the data type, or other definition details. The default value is false.
Square Retrieve Merchant Custom Attribute Definition
Square Retrieve Merchant Custom Attribute DefinitionIntegration name: 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.
Parameters
Your Toolhouse AI worker will automatically pass these parameters as input when the tool is called.
key
string
✅
"sq0idp-UYDThC1sE61O20bBQyc4lQ:merchant-global.fiscal_year_end_month"
The key of the custom attribute definition to retrieve. If the requesting application is not the definition owner, you must use the qualified key.
version
integer
—
The current version of the custom attribute definition, which is used for strongly consistent reads to guarantee that you receive the most up-to-date data. When included in the request, Square returns the specified version or a higher version if one exists. If the specified version is higher than the current version, Square returns a BAD_REQUEST error.
Square Retrieve Merchants
Square Retrieve MerchantsIntegration name: 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.
Parameters
Your Toolhouse AI worker will automatically pass these parameters as input when the tool is called.
merchant_ids
array
✅
["MLBN7K732KMAD"]
List of merchant IDs to retrieve information for. Each ID must be a valid Square merchant identifier.
Square Retrieve Order
Square Retrieve OrderIntegration name: 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 order status and fulfillment information - View payment tenders and refunds associated with an order - Access order metadata and timestamps Requires: ORDERS_READ permission scope.
Parameters
Your Toolhouse AI worker will automatically pass these parameters as input when the tool is called.
order_id
string
✅
"CAISENgvlJ6jLWAzERDzjyHVybY"
The unique Square-generated ID of the order to retrieve. This is typically a long alphanumeric string (e.g., 'CAISENgvlJ6jLWAzERDzjyHVybY'). You can obtain order IDs from the Search Orders endpoint or from webhook notifications.
Square Retrieve Payment Link
Square Retrieve Payment LinkIntegration name: 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. Requires ORDERS_READ permission.
Parameters
Your Toolhouse AI worker will automatically pass these parameters as input when the tool is called.
id
string
✅
"PAY_LINK_ID_123"
The Square-assigned ID of the payment link to retrieve.
Square Retrieve Token Status
Square Retrieve Token StatusIntegration name: 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 association before making API calls.
Parameters
Your Toolhouse AI worker will automatically pass these parameters as input when the tool is called.
No parameters required.
Square Retrieve Webhook Subscription
Square Retrieve Webhook SubscriptionIntegration name: 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 authentication with DEVELOPER_APPLICATION_WEBHOOKS_READ scope (OAuth tokens are not supported for webhook subscriptions).
Parameters
Your Toolhouse AI worker will automatically pass these parameters as input when the tool is called.
subscription_id
string
✅
"wbhk_b35f6b3145074cf9ad513610786c19d5"
ID of the webhook subscription to retrieve. Square webhook subscription IDs typically start with 'wbhk_'.
Square Search Customers
Square Search CustomersIntegration name: 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.
Parameters
Your Toolhouse AI worker will automatically pass these parameters as input when the tool is called.
count
boolean
—
Whether to return the total count of matching customers in the response. Default: false.
limit
integer
50
Maximum number of results to return per page (1-100). Default: 100.
query
object
—
Query parameters for filtering and sorting customers.
cursor
string
—
Pagination cursor returned by a previous call. Use to retrieve the next set of results.
Square Search Orders
Square Search OrdersIntegration name: 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 exposes 'list orders for a date range' functionality.
Parameters
Your Toolhouse AI worker will automatically pass these parameters as input when the tool is called.
limit
integer
100
Maximum number of results to return per page. Default: 500, Maximum: 1000.
query
object
—
Query parameters for filtering and sorting orders.
cursor
string
—
A pagination cursor returned by a previous call to this endpoint. Provide this cursor to retrieve the next set of results for your original query.
location_ids
array
✅
["L3HB3M4X4G76H"]
The location IDs for the orders to query. All locations must belong to the same merchant. Maximum: 10 location IDs.
return_entries
boolean
—
Controls the format of the search results. If true, returns OrderEntry objects (lightweight with just order_id, location_id, version). If false, returns complete Order objects with full details. Default: false.
Square Submit Dispute Evidence
Square Submit Dispute EvidenceIntegration name: 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 evidence is submitted, it cannot be modified or removed. The dispute state will change to PROCESSING after successful submission. Use this when: (1) You have uploaded all evidence files/text, (2) The dispute is in EVIDENCE_REQUIRED state, and (3) You are ready to finalize and send evidence to the bank before the due date.
Parameters
Your Toolhouse AI worker will automatically pass these parameters as input when the tool is called.
dispute_id
string
✅
"bESrpVKyW5LlbNvTFZwYgAAA"
The ID of the dispute to submit evidence for. Get this from ListDisputes or RetrieveDispute endpoints. Must be a dispute in EVIDENCE_REQUIRED or INQUIRY_EVIDENCE_REQUIRED state.
Square Test Webhook Subscription
Square Test Webhook SubscriptionIntegration name: 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 includes the HTTP status code returned by your endpoint and the test payload that was sent. Useful after creating or updating a subscription to confirm proper integration.
Parameters
Your Toolhouse AI worker will automatically pass these parameters as input when the tool is called.
event_type
string
"payment.created"
The event type to use for testing (e.g., 'payment.created', 'order.updated'). Must match one of the subscription's configured event_types. If omitted, Square uses the first event type from the subscription's event_types list.
subscription_id
string
✅
"sub_123456789"
The ID of the webhook subscription to test. Obtain this from the List Webhook Subscriptions or Create Webhook Subscription endpoints.
Square Update Customer
Square Update CustomerIntegration name: 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 change, null values will remove fields. Include the version field for optimistic concurrency control.
Parameters
Your Toolhouse AI worker will automatically pass these parameters as input when the tool is called.
note
string
—
A custom note associated with the customer profile.
address
object
—
Physical address with sparse update support.
tax_ids
object
—
Tax ID for EU/UK sellers only.
version
integer
—
Current customer profile version for optimistic concurrency control. Get this from a previous retrieve/search customer call.
birthday
string
"1990-05-15"
Birthday in date format: YYYY-MM-DD or MM-DD.
nickname
string
—
A nickname for the customer profile. Max 100 characters.
given_name
string
—
The given name (first name) associated with the customer profile. Max 300 characters.
customer_id
string
✅
"CEH5ANS6J5N3VSZDM5CJCDY428"
The ID of the customer to update.
family_name
string
—
The family name (last name) associated with the customer profile. Max 300 characters.
company_name
string
—
A business name associated with the customer profile. Max 500 characters.
phone_number
string
—
Phone number requiring 9-16 digits, optional + prefix, and country code.
reference_id
string
—
An optional second ID used to associate the customer profile with an entity in another system. Max 100 characters.
email_address
string
—
The email address associated with the customer profile. Max 254 characters.
Square Update Customer Custom Attribute Definition
Square Update Customer Custom Attribute DefinitionIntegration name: 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 sparse updates: only include fields you want to change. Use the version parameter for optimistic concurrency control to prevent conflicting updates.
Parameters
Your Toolhouse AI worker will automatically pass these parameters as input when the tool is called.
key
string
✅
"favorite-color"
The key of the custom attribute definition to update.
name
string
"Favorite Color"
Updated display name for the custom attribute definition.
schema
object
{"type":"array","items":{"enum":["uuid-1","uuid-2","uuid-3"],"names":["red","blue","green"]},"$schema":"https://developer-production-s.squarecdn.com/meta-schemas/v1/selection.json","maxItems":1,"uniqueItems":true}
Updated schema definition for the custom attribute. Required when the attribute type is Selection. Use JSON schema format to define allowed values and constraints.
version
integer
1
Current version number for optimistic concurrency control. When provided, the update only succeeds if this version matches the current version on the server. Retrieve the current version first using the retrieve or list endpoints.
visibility
string
"VISIBILITY_HIDDEN"
Updated visibility setting for the custom attribute. Valid values: VISIBILITY_HIDDEN (only accessible by the owner), VISIBILITY_READ_ONLY (readable by others), VISIBILITY_READ_WRITE_VALUES (values readable/writable by others).
description
string
"Customer's preferred color"
Updated description of the custom attribute definition.
Square Update Customer Group
Square Update Customer GroupIntegration name: 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.
Parameters
Your Toolhouse AI worker will automatically pass these parameters as input when the tool is called.
group
object
✅
—
The CustomerGroup object including all the updates you want to make.
group_id
string
✅
"3SJ1AQ3YZVFV5SB2WQJ8R0PNYT"
The ID of the customer group to update. This is the unique identifier for the group that will be modified.
Square Update Customers Bulk
Square Update Customers BulkIntegration name: 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 and the customer data to update as the value. Only modified fields need to be provided, and fields can be removed by setting them to null. Requires version number for optimistic concurrency control.
Parameters
Your Toolhouse AI worker will automatically pass these parameters as input when the tool is called.
customers
object
✅
—
Map of customer IDs to BulkUpdateCustomerData objects. Each key is a customer profile ID to update, and each value contains the updated customer data. Supports 1-100 individual update requests.
Square Update Location
Square Update LocationIntegration name: 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 profiles.
Parameters
Your Toolhouse AI worker will automatically pass these parameters as input when the tool is called.
location
object
✅
—
The location object with only the fields to update. All fields are optional.
location_id
string
✅
"L9YZVY8XPTC15"
The ID of the location to update.
Square Update Location Custom Attribute Definition
Square Update Location Custom Attribute DefinitionIntegration name: 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.
Parameters
Your Toolhouse AI worker will automatically pass these parameters as input when the tool is called.
key
string
✅
"test-attribute-1739678400"
The key of the custom attribute definition to update. This is the unique identifier for the custom attribute definition.
idempotency_key
string
"curl-test-update-23456789012345678901"
A unique identifier to ensure idempotent request handling. If you retry a request with the same idempotency key, Square returns the same response without re-executing the update.
custom_attribute_definition
object
✅
—
The custom attribute definition fields to update. Only the provided fields will be updated; omitted fields remain unchanged.
Square Update Merchant Custom Attribute Definition
Square Update Merchant Custom Attribute DefinitionIntegration name: 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.
Parameters
Your Toolhouse AI worker will automatically pass these parameters as input when the tool is called.
key
string
✅
"test-merchant-attribute-20260216"
The key of the custom attribute definition to update. This is the unique identifier for the custom attribute definition.
idempotency_key
string
"merchant-update-idempotency-key-123"
A unique identifier to ensure idempotent request handling. If you retry a request with the same idempotency key, Square returns the same response without re-executing the update.
custom_attribute_definition
object
✅
—
The custom attribute definition fields to update. Only the provided fields will be updated; omitted fields remain unchanged.
Square Update Online Checkout Location Settings
Square Update Online Checkout Location SettingsIntegration name: 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 location. Supports sparse updates: only include fields you want to change.
Parameters
Your Toolhouse AI worker will automatically pass these parameters as input when the tool is called.
location_id
string
✅
"L9YZVY8XPTC15"
The ID of the location for which to update online checkout settings. This is the unique Square-generated identifier for the location.
location_settings
object
✅
—
The location settings to update. Only include the fields that you want to change.
Square Update Order
Square Update OrderIntegration name: 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 for optimistic concurrency control - get this from retrieve/search order first. Supports sparse updates: only include fields you want to change. To remove fields, use fields_to_clear array with dot notation paths. Common use cases: adding line items, updating quantities, applying discounts/taxes, modifying fulfillment details, updating metadata.
Parameters
Your Toolhouse AI worker will automatically pass these parameters as input when the tool is called.
order
object
—
Partial Order object with fields to add/update. Use 'sparse' requests by including only changed fields. REQUIRED field: 'version' (integer) - current order version for optimistic concurrency control. Common fields: 'location_id', 'line_items', 'taxes', 'discounts', 'service_charges', 'fulfillments', 'metadata'. Example: {'version': 1, 'line_items': [...]} to update line items on version 1 of the order.
order_id
string
✅
"ORDER_ID_123"
ID of the order to update.
fields_to_clear
array
—
List of dot-notation paths of fields to clear/delete in the order, e.g., ['line_items[uid].note']. Only used when removing fields.
idempotency_key
string
"a1b2c3d4-unique-key-5678"
A unique key to ensure idempotency. Generate a new key per update.
Square Update Webhook Subscription
Square Update Webhook SubscriptionIntegration name: 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 subscription.
Parameters
Your Toolhouse AI worker will automatically pass these parameters as input when the tool is called.
name
string
"My Webhook Subscription"
New display name for the subscription (max 64 characters).
enabled
boolean
true
Whether the subscription should be active.
api_version
string
"2021-06-16"
Webhook API version to use for this subscription, e.g., '2021-06-16'.
event_types
array
["payment.created","order.updated"]
List of event types to subscribe to, e.g., ['payment.created'].
subscription_id
string
✅
"sub_123456789"
ID of the webhook subscription to update.
notification_url
string
"https://example.com/webhook"
Destination URL for webhook notifications.
Square Update Webhook Subscription Signature Key
Square Update Webhook Subscription Signature KeyIntegration name: 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.
Parameters
Your Toolhouse AI worker will automatically pass these parameters as input when the tool is called.
idempotency_key
string
"unique-idempotency-key"
A unique string to make this request idempotent. Max 45 characters.
subscription_id
string
✅
"sub_123456789"
The ID of the webhook subscription to rotate the signature key for.
Square Upsert Customer Custom Attribute
Square Upsert Customer Custom AttributeIntegration name: 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 attribute key must match an existing custom attribute definition in the Square account.
Parameters
Your Toolhouse AI worker will automatically pass these parameters as input when the tool is called.
key
string
✅
"favorite_color"
The key of the custom attribute to create or update. This key must match the key of a custom attribute definition in the Square seller account. If the requesting application is not the definition owner, you must use the qualified key (e.g., 'app_id:attribute_key').
customer_id
string
✅
"CEH5ANS6J5N3VSZDM5CJCDY428"
The ID of the target customer profile. You can retrieve customer IDs from the List Customers endpoint or when creating a customer.
idempotency_key
string
—
Optional unique identifier for this request to ensure idempotency. Use this to prevent duplicate requests from creating multiple custom attributes if the request is retried.
custom_attribute
object
✅
—
The custom attribute object containing the value and optional version number.
Square Upsert Customer Custom Attributes Batch
Square Upsert Customer Custom Attributes BatchIntegration name: 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). Supports 1 to 25 upsert operations per request. Before using this action, ensure the custom attribute definitions exist in your Square seller account. The custom attribute keys must match existing definitions. Use optimistic concurrency (version field) to prevent overwriting concurrent updates. Required permissions: CUSTOMERS_WRITE
Parameters
Your Toolhouse AI worker will automatically pass these parameters as input when the tool is called.
values
object
✅
{"request1":{"customer_id":"CEH5ANS6J5N3VSZDM5CJCDY428","custom_attribute":{"key":"favorite_color","value":"blue"}},"request2":{"customer_id":"JDKYHBWT1D4F8MFH63DBMEN8Y4","custom_attribute":{"key":"loyalty_tier","value":"gold"}}}
A map of 1 to 25 individual upsert requests. Each key in the map is a unique identifier (request ID) that you define to track the request. The value is an object containing the customer_id and custom_attribute to upsert. Request IDs are case-sensitive and must be unique within the batch.
Square Upsert Location Custom Attribute
Square Upsert Location Custom AttributeIntegration name: 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 attribute key must match an existing custom attribute definition in the Square account.
Parameters
Your Toolhouse AI worker will automatically pass these parameters as input when the tool is called.
key
string
✅
"store_capacity"
The key of the custom attribute to create or update. This key must match the key of a custom attribute definition in the Square seller account. If the requesting application is not the definition owner, you must use the qualified key (e.g., 'app_id:attribute_key').
location_id
string
✅
"L9YZVY8XPTC15"
The ID of the target location. You can retrieve location IDs from the List Locations endpoint.
idempotency_key
string
—
Optional unique identifier for this request to ensure idempotency. Use this to prevent duplicate requests from creating multiple custom attributes if the request is retried. Maximum 45 characters.
custom_attribute
object
✅
—
The custom attribute object containing the value and optional version number.
Square Upsert Locations Custom Attributes Batch
Square Upsert Locations Custom Attributes BatchIntegration name: 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). Supports 1 to 25 upsert operations per request. Before using this action, ensure the custom attribute definitions exist in your Square seller account. The custom attribute keys must match existing definitions. Use optimistic concurrency (version field) to prevent overwriting concurrent updates. Required permissions: MERCHANT_PROFILE_WRITE
Parameters
Your Toolhouse AI worker will automatically pass these parameters as input when the tool is called.
values
object
✅
{"request1":{"location_id":"L9YZVY8XPTC15","custom_attribute":{"key":"bestseller","value":"premium"}},"request2":{"location_id":"L18JNM7DFNQC1","custom_attribute":{"key":"delivery-zone","value":"zone-a"}}}
A map of 1 to 25 individual upsert requests. Each key in the map is a unique identifier (request ID) that you define to track the request. The value is an object containing the location_id and custom_attribute to upsert. Request IDs are case-sensitive and must be unique within the batch.
Square Upsert Merchant Custom Attribute
Square Upsert Merchant Custom AttributeIntegration name: 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. The custom attribute key must match an existing custom attribute definition in the Square account.
Parameters
Your Toolhouse AI worker will automatically pass these parameters as input when the tool is called.
key
string
✅
"test-attribute"
The key of the custom attribute to create or update. This key must match the key of a custom attribute definition in the Square seller account. If the requesting application is not the definition owner, you must use the qualified key (e.g., 'app_id:attribute_key').
merchant_id
string
✅
"MLBN7K732KMAD"
The ID of the target merchant. You can obtain this from the List Merchants endpoint or from your Square dashboard.
idempotency_key
string
—
Optional unique identifier for this request to ensure idempotency. Use this to prevent duplicate requests from creating multiple custom attributes if the request is retried. Maximum 5 KB.
custom_attribute
object
✅
—
The custom attribute object containing the value and optional version number.
Square Upsert Merchants Custom Attributes Batch
Square Upsert Merchants Custom Attributes BatchIntegration name: 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, merchant categories). Supports 1 to 25 upsert operations per request. Before using this action, ensure the custom attribute definitions exist in your Square seller account. The custom attribute keys must match existing definitions. Use optimistic concurrency (version field) to prevent overwriting concurrent updates. Required permissions: MERCHANT_PROFILE_WRITE
Parameters
Your Toolhouse AI worker will automatically pass these parameters as input when the tool is called.
values
object
✅
{"request1":{"merchant_id":"MLBN7K732KMAD","custom_attribute":{"key":"business-type","value":"retail"}},"request2":{"merchant_id":"M8JN3KL5PQTR9","custom_attribute":{"key":"established-year","value":2020}}}
A map of 1 to 25 individual upsert requests. Each key in the map is a unique identifier (request ID) that you define to track the request. The value is an object containing the merchant_id and custom_attribute to upsert. Request IDs are case-sensitive and must be unique within the batch.