Skip to main content
Square logo
  • Category: payment processing
  • Auth: OAUTH2
  • Composio-managed OAuth available? Yes
  • Tools: 122
  • Triggers: 0
  • Slug: SQUARE
  • Version: 20261103_00

Tools

Slug: SQUARE_ACCEPT_DISPUTEAccepts a dispute, acknowledging liability and returning funds to the cardholder; acceptance is irreversible and requires DISPUTES_WRITE permission. Non-JSON responses, including HTTP failures, can produce an empty result, so check the returned dispute and errors.

Input Parameters

string
required
The Square-generated unique ID of the dispute to accept. Accepting a dispute acknowledges liability and cannot be reversed.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: SQUARE_ADD_GROUP_TO_CUSTOMERTool 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.

Input Parameters

string
required
The ID of the customer group to add the customer to. This is the unique Square-generated group identifier.
string
required
The ID of the customer to add to a group. This is the unique Square-generated customer identifier.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: SQUARE_CALCULATE_ORDERTool 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.

Input Parameters

object
required
The order to be calculated. Expects the entire order, not a sparse update. Must include location_id and line_items with pricing information.
array
Identifies one or more loyalty reward tiers to apply during the order calculation. These are preview-only; no actual redemptions occur.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: SQUARE_CANCEL_BOOKINGCancels 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.

Input Parameters

string
required
The ID of the Booking object representing the to-be-cancelled booking. Obtain this from booking creation responses or booking retrieval endpoints.
integer
The revision number for the booking, used for optimistic concurrency control. If provided, the booking will only be cancelled if this version matches the current version on the server.
string
A unique identifier ensuring idempotent operations. Recommended for all create and update operations to prevent duplicate processing.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: SQUARE_CANCEL_INVOICECancels 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.

Input Parameters

integer
required
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.
string
required
The Square-assigned ID of the invoice to cancel. Obtain this from GET_INVOICE or LIST_INVOICES actions.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: SQUARE_CANCEL_PAYMENTCancels (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

Input Parameters

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

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: SQUARE_CREATE_BATCH_INVENTORY_CHANGESApplies 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.

Input Parameters

array
required
The set of physical counts and inventory adjustments to be made. Maximum 100 changes per request.
string
required
A client-supplied, universally unique identifier (UUID) for the request to ensure idempotency.
boolean
If true, calculated inventory counts are not returned. This can be useful if the counts are not needed. Defaults to true.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: SQUARE_CREATE_BULK_CUSTOMERSTool 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.

Input Parameters

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

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: SQUARE_CREATE_CARDTool 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.

Input Parameters

object
required
Details of the card and customer to store on file.
string
required
Card nonce or payment ID used as the source of card data.
string
required
Unique key for this CreateCard request (1–45 characters).
string
Token from Payments.verifyBuyer() for SCA/3-D Secure verification.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: SQUARE_CREATE_CUSTOMERTool 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.

Input Parameters

string
A custom note associated with the customer profile.
object
Represents a physical postal address.
object
Tax ID information for EU/UK sellers.
string
The birthday associated with the customer profile. Format: YYYY-MM-DD or MM-DD. Returns as YYYY-MM-DD.
string
A nickname for the customer profile.
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.
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.
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.
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.
string
An optional second ID used to associate the customer profile with an entity in another system.
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.
string
A unique key to ensure idempotent request processing. Recommended for all create operations.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: SQUARE_CREATE_CUSTOMER_CUSTOM_ATTRIBUTE_DEFINITIONTool 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.

Input Parameters

string
Unique key for this request to ensure idempotency. Prevents duplicate definitions from being created if the request is retried.
object
required
The custom attribute definition to create for customers.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: SQUARE_CREATE_CUSTOMER_GROUPTool to create a new customer group for a business. Use when you need to organize customers into groups for targeted marketing or segmentation.

Input Parameters

object
required
The customer group object containing the name and other properties.
string
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.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: SQUARE_CREATE_DISPUTE_EVIDENCE_FILEUploads a file as supporting evidence for an existing Square dispute, such as a PDF or image. File content can be supplied inline as base64, and an idempotency key identifies the upload.

Input Parameters

object
required
The file to upload as dispute evidence (max 5 MB).
string
required
The ID of the dispute to upload evidence for.
string
Optional MIME type of the uploaded file. Must be one of image/heic, image/heif, image/jpeg, application/pdf, image/png, image/tiff.
string
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.
string
required
A unique key for this upload to ensure idempotency (max 45 characters).
string
Optional filename for inline file content. Defaults to the original filename.
string
Optional MIME type for inline file content. Defaults to the FileUploadable mimetype or application/octet-stream.
string
Optional base64-encoded file content. When provided, the file will be uploaded from this inline content instead of fetching from FileUploadable storage.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: SQUARE_CREATE_DISPUTE_EVIDENCE_TEXTUpload 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

Input Parameters

string
required
The ID of the dispute to upload text evidence for.
string
required
The text string to upload as evidence (max 500 characters).
string
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.
string
required
A unique key identifying the request (max 45 characters).

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: SQUARE_CREATE_GIFT_CARD_ACTIVITYCreates 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.

Input Parameters

string
required
A unique string that identifies this CreateGiftCardActivity request. Ensures idempotent processing to prevent duplicate activities.
object
required
The gift card activity to create. Must include type, location_id, either gift_card_id or gift_card_gan, and the appropriate activity_details for the type.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: SQUARE_CREATE_INVOICE_ATTACHMENTUpload 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.

Input Parameters

object
required
File to upload and attach to the invoice. Supported formats: GIF, JPEG, PNG, TIFF, BMP, or PDF.
string
required
The ID of the invoice to attach the file to. The invoice must be in DRAFT, SCHEDULED, UNPAID, or PARTIALLY_PAID state.
string
Description text for the attachment that will be displayed on the invoice. Maximum 128 characters.
string
A unique string to ensure idempotency for this request. Prevents duplicate attachments if the same request is sent multiple times. Maximum 128 characters.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: SQUARE_CREATE_LOCATIONTool 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.

Input Parameters

object
required
Details of the location to create.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: SQUARE_CREATE_LOCATION_CUSTOM_ATTRIBUTE_DEFINITIONTool 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.

Input Parameters

string
Unique string ensuring idempotency for safe request retry (maximum 45 characters).
object
required
The custom attribute definition to create for locations.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: SQUARE_CREATE_ORDERCreates 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.

Input Parameters

object
required
The order to be created. Must include location_id and line_items. Each line item requires quantity and either catalog_object_id or both name and base_price_money.
string
required
A unique key to ensure idempotent request processing. Generate a unique value for each create order request to prevent duplicate orders.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: SQUARE_CREATE_REFUNDRefunds 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.

Input Parameters

string
A description of the reason for the refund. Visible to the customer on their receipt and transaction history.
string
required
The Square payment ID to refund. Required for linked refunds. You can obtain payment IDs from the List Payments endpoint or from payment creation responses.
object
required
The amount to refund. Cannot exceed the original payment total minus any prior refunds. Must be in the same currency as the original payment.
object
Represents an amount of money.
string
An optional ID of the team member associated with processing the refund.
string
required
A unique key to ensure idempotent request processing. Required for all refund operations to prevent duplicate refunds.
string
Used for optimistic concurrency control. This opaque token identifies a specific version of the Payment object to ensure the payment hasn’t been modified since retrieval.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: SQUARE_CREATE_TEAM_MEMBERTool 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.

Input Parameters

object
required
The data used to create the TeamMember object. Requires at minimum given_name and family_name.
string
required
A unique string that identifies this CreateTeamMember request. Used to ensure idempotent request processing. Max 45 characters.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: SQUARE_DELETE_CATALOG_OBJECTTool 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.

Input Parameters

string
required
The ID of the catalog object to delete. When an object is deleted, other objects in the graph that depend on that object will be deleted as well.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: SQUARE_DELETE_CATALOG_OBJECTS_BATCHDeletes 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.

Input Parameters

array
required
The IDs of the CatalogObjects to be deleted. When an object is deleted, other objects in the graph that depend on that object will be deleted as well (for example, deleting a CatalogItem will delete its CatalogItemVariation). Minimum 1 and maximum 200 object IDs.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: SQUARE_DELETE_CUSTOMERTool to delete a Square customer profile. Use when you need to permanently remove a customer record from Square.

Input Parameters

integer
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.
string
required
The ID of the customer to delete.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: SQUARE_DELETE_CUSTOMER_CUSTOM_ATTRIBUTETool 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.

Input Parameters

string
required
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.
string
required
The ID of the target customer profile. You can obtain this from listing customers or from a specific customer retrieval.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: SQUARE_DELETE_CUSTOMER_CUSTOM_ATTRIBUTE_DEFINITIONTool 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.

Input Parameters

string
required
The key of the custom attribute definition to delete.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: SQUARE_DELETE_CUSTOMER_GROUPTool to delete a customer group by its ID. Use when you need to permanently remove a customer group from Square.

Input Parameters

string
required
The ID of the customer group to delete.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: SQUARE_DELETE_CUSTOMERS_BULKTool 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.

Input Parameters

array
required
An array containing the IDs of the customer profiles to delete. Minimum 1 and maximum 100 customer IDs.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: SQUARE_DELETE_DISPUTE_EVIDENCERemoves 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

Input Parameters

string
required
The unique ID of the dispute from which to remove evidence. You can obtain this from listing disputes or from a specific dispute retrieval.
string
required
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.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: SQUARE_DELETE_INVOICETool to delete a Square invoice (only DRAFT invoices can be deleted).

Input Parameters

integer
The version of the invoice to delete. If you do not know the version, retrieve the invoice first via Get Invoice or List Invoices.
string
required
The Square-assigned ID of the invoice to delete. Format: ‘inv:0-’ followed by an alphanumeric string.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: SQUARE_DELETE_INVOICE_ATTACHMENTTool to delete an attachment from a Square invoice. Endpoint: DELETE /v2/invoices/{invoice_id}/attachments/{attachment_id}

Input Parameters

string
required
The Square-assigned ID of the invoice to delete the attachment from. Format: ‘inv:0-’ followed by an alphanumeric string.
string
required
The ID of the attachment to delete.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: SQUARE_DELETE_LOCATION_CUSTOM_ATTRIBUTETool 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.

Input Parameters

string
required
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.
string
required
The ID of the target location. You can obtain this from the List Locations endpoint.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: SQUARE_DELETE_LOCATION_CUSTOM_ATTRIBUTE_DEFINITIONTool 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.

Input Parameters

string
required
The key of the custom attribute definition to delete.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: SQUARE_DELETE_LOCATIONS_CUSTOM_ATTRIBUTES_BATCHTool 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.

Input Parameters

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

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: SQUARE_DELETE_MERCHANT_CUSTOM_ATTRIBUTETool 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.

Input Parameters

string
required
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.
string
required
The ID of the target merchant. You can obtain this from the List Merchants endpoint or from your Square dashboard.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: SQUARE_DELETE_MERCHANT_CUSTOM_ATTRIBUTE_DEFINITIONTool 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.

Input Parameters

string
required
The key of the custom attribute definition to delete.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: SQUARE_DELETE_MERCHANTS_CUSTOM_ATTRIBUTES_BATCHTool 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.

Input Parameters

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

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: SQUARE_DELETE_WEBHOOK_SUBSCRIPTIONPermanently 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).

Input Parameters

string
required
ID of the webhook subscription to delete.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: SQUARE_GET_BOOKINGRetrieves 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).

Input Parameters

string
required
The ID of the booking to retrieve. This is the unique Square-generated booking identifier.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: SQUARE_GET_BUSINESS_BOOKING_PROFILETool 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.

Input Parameters

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

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: SQUARE_GET_CURRENT_MERCHANTTool 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.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: SQUARE_GET_CUSTOMER_CUSTOM_ATTRIBUTERetrieves 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.

Input Parameters

string
required
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.
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.
string
required
The ID of the target customer profile. This is the unique Square-assigned ID that identifies the customer.
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.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: SQUARE_GET_CUSTOMERS_CUSTOM_ATTRIBUTE_DEFINITIONSTool 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.

Input Parameters

string
required
The key of the custom attribute definition to retrieve. If the requesting application is not the definition owner, you must use the qualified key.
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.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: SQUARE_GET_CUSTOMERS_GRAPHQLTool 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.

Input Parameters

integer
Maximum number of customer records to return in a single request (1-100). If not specified, the API default applies.
string
required
The merchant ID to filter customers. Required to retrieve customers from the Customer Directory. This is the Square location or business identifier.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: SQUARE_GET_DISPUTE_EVIDENCERetrieves 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}

Input Parameters

string
required
The ID of the dispute for which to retrieve evidence. You can obtain dispute IDs by listing disputes or from dispute webhooks.
string
required
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.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: SQUARE_GET_GIFT_CARD_FROM_GANRetrieves gift card information by its GAN (gift card account number), including available ID, type, state, balance, and associated customer IDs.

Input Parameters

string
required
The gift card account number (GAN) of the gift card to retrieve. Square-issued gift cards have 16-digit GANs. The 255-digit maximum accommodates third-party imported GANs.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: SQUARE_GET_INVOICERetrieves 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

Input Parameters

string
required
The Square-assigned ID of the invoice to retrieve. Format: ‘inv:0-’ followed by an alphanumeric string.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: SQUARE_GET_LOYALTY_ACCOUNTTool 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.

Input Parameters

string
required
The ID of the loyalty account to retrieve. This is the unique Square-generated loyalty account identifier.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: SQUARE_GET_MERCHANTTool 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.

Input Parameters

string
required
The ID of the merchant to retrieve. Use ‘me’ to retrieve the merchant that is currently accessible to this call.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: SQUARE_GET_ONLINE_CHECKOUT_LOCATION_SETTINGSTool 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.

Input Parameters

string
required
The ID of the location for which to retrieve online checkout settings. This is the unique Square-generated identifier for the location.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: SQUARE_GET_REFUNDRetrieves 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.

Input Parameters

string
required
The unique ID for the desired PaymentRefund. You can obtain refund IDs from the List Payment Refunds endpoint or from refund creation responses.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: SQUARE_GET_SUBSCRIPTIONRetrieves 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.

Input Parameters

string
Optional parameter to include related information. Supported value: ‘actions’ to include scheduled actions on the subscription. Beta feature.
string
required
The Square-assigned ID of the subscription to retrieve. This is the unique identifier for the subscription.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: SQUARE_GET_TEAM_MEMBERTool 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.

Input Parameters

string
required
The ID of the team member to retrieve. This is the unique Square-generated team member identifier.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: SQUARE_LIST_CARDSTool 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.

Input Parameters

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.
string ("ASC" | "DESC")
Enum for sort order options.
string
Limit results to cards associated with the customer supplied. By default, all cards owned by the merchant are returned.
string
Limit results to cards associated with the reference_id supplied.
boolean
Includes disabled cards. By default, list cards returns only cards with status enabled.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: SQUARE_LIST_CHANNELSTool to list requested channels from Square. Use when you need to retrieve channel information for a specific reference type, reference ID, or status.

Input Parameters

integer
Maximum number of results to return. When not provided the returned results will be capped at 100 channels.
string
Cursor to fetch the next result. Pagination cursor returned by a previous call to this endpoint.
string
Status of channel. Filter channels by their status (e.g., ACTIVE, INACTIVE).
string
ID of reference associated to channel. Filter channels by the reference ID.
string
Type of reference associated to channel. Filter channels by the reference type.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: SQUARE_LIST_CUSTOMER_CUSTOM_ATTRIBUTE_DEFINITIONSTool 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.

Input Parameters

integer
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.
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. For more information, see Pagination.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: SQUARE_LIST_CUSTOMER_CUSTOM_ATTRIBUTE_DEFINITIONS_GRAPH_QLQueries customer custom attribute definitions and their metadata via Square’s GraphQL API, filtered by the supplied merchant IDs. Alpha feature.

Input Parameters

array
required
List of merchant IDs to filter custom attribute definitions. Only definitions associated with these merchant IDs will be returned.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: SQUARE_LIST_CUSTOMER_CUSTOM_ATTRIBUTESLists a page of custom attributes for a customer profile, optionally including definitions that provide metadata about each attribute. Use the returned cursor to request additional pages.

Input Parameters

integer
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.
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.
string
required
The ID of the target customer profile. You can obtain this from listing customers or from a specific customer retrieval.
boolean
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.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: SQUARE_LIST_CUSTOMER_GROUPSTool 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.

Input Parameters

integer
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.
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. For more information, see Pagination.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: SQUARE_LIST_CUSTOMERSTool 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).

Input Parameters

boolean
Indicates whether to return the total count of customers in the count field of the response. The default value is false.
integer
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.
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.
string ("DEFAULT" | "CREATED_AT")
Enum for customer sort field options.
string ("ASC" | "DESC")
Enum for sort order options.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: SQUARE_LIST_CUSTOMER_SEGMENTSTool 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.

Input Parameters

integer
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).
string
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).

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: SQUARE_LIST_DISPUTE_EVIDENCETool to list evidence items associated with a given dispute. Endpoint: GET /v2/disputes/{dispute_id}/evidence

Input Parameters

string
A pagination cursor returned by a previous call to this endpoint. Provide this to retrieve the next set of results.
string
required
ID of the dispute to list evidence for.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: SQUARE_LIST_INVOICESTool to list invoices for a Square location.

Input Parameters

integer
Maximum number of invoices to return (1-200). Defaults to Square’s default if unset.
string
Pagination cursor from a previous ListInvoices call; use to fetch the next page.
string
required
The Square location ID for which to list invoices.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: SQUARE_LIST_LOCATION_CUSTOM_ATTRIBUTE_DEFINITIONSTool 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.

Input Parameters

integer
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.
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. For more information, see Pagination.
string
Filters the CustomAttributeDefinition results by their visibility values.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: SQUARE_LIST_LOCATIONSTool 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).

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: SQUARE_LIST_LOCATIONS_CUSTOM_ATTRIBUTESLists a page of custom attributes for a specific Square location. Use the returned cursor to retrieve further pages; results can be filtered by visibility.

Input Parameters

integer
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.
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. For more information, see Pagination.
string
required
The ID of the target location. This is the unique Square-assigned ID that identifies the location.
boolean
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.
string
Filters the CustomAttributeDefinition results by their visibility values. Possible values include VISIBILITY_READ_ONLY, VISIBILITY_READ_WRITE_VALUES, and VISIBILITY_HIDDEN.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: SQUARE_LIST_MERCHANT_CUSTOM_ATTRIBUTE_DEFINITIONSTool 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.

Input Parameters

integer
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.
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. For more information, see Pagination.
string
Filters the CustomAttributeDefinition results by their visibility values.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: SQUARE_LIST_MERCHANTSTool 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.

Input Parameters

integer
The cursor generated by the previous response. Provide this cursor to retrieve the next set of results.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: SQUARE_LIST_MERCHANTS_CUSTOM_ATTRIBUTESLists a page of custom attributes for a specific Square merchant. Use the returned cursor to retrieve further pages; results can be filtered by visibility.

Input Parameters

integer
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.
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. For more information, see Pagination.
string
required
The ID of the target merchant. This is the unique Square-assigned ID that identifies the merchant.
boolean
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.
string
Filters the CustomAttributeDefinition results by their visibility values. Possible values include VISIBILITY_READ_ONLY, VISIBILITY_READ_WRITE_VALUES, and VISIBILITY_HIDDEN.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: SQUARE_LIST_PAYMENTSTool 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.

Input Parameters

integer
Maximum number of payments to return per page (1-100). Defaults to 100.
integer
Filter by exact amount in the smallest currency unit (e.g., cents for USD) in total_money for a payment.
string
Pagination cursor returned by a previous call to this endpoint. Use to fetch the next page of results.
string
Filter by the last four digits of a payment card.
string
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.
string
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.
string
Filter by brand of the payment card (e.g., ‘VISA’, ‘MASTERCARD’, ‘AMEX’).
string
Field to use for sorting results (e.g., ‘CREATED_AT’). Defaults to CREATED_AT.
string
Sort direction for results: ‘ASC’ (oldest first) or ‘DESC’ (newest first). Defaults to DESC.
string
Limit results to the location supplied. If not provided, defaults to the main location.
string
End of the time range for offline payments, in RFC 3339 format.
boolean
Whether the payment was taken offline or not.
string
Start of the time range for offline payments, in RFC 3339 format.
string
End of the time range to retrieve payments for based on updated_at field, in RFC 3339 format.
string
Start of the time range to retrieve payments for based on updated_at field, in RFC 3339 format.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: SQUARE_LIST_SUBSCRIPTIONSTool to search and list Square customer billing subscriptions. Use this action when you need to retrieve subscription information for customers, filter subscriptions by location, or view all active subscriptions. Results are ordered chronologically by subscription creation date.

Input Parameters

integer
Maximum number of results to return per page (minimum: 1). Default: 25.
object
Query parameters for filtering subscriptions.
string
Pagination cursor returned by a previous call. Use to retrieve the next set of results.
array
Related information to include in the response. This is a Beta feature; currently supports ‘actions’ value to include scheduled subscription actions.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: SQUARE_LIST_WEBHOOK_EVENT_TYPESTool to list available webhook event types. Use when you need to discover event types before creating or updating a webhook subscription.

Input Parameters

string
Overrides the application default API version (YYYY-MM-DD) for listing event types.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: SQUARE_LIST_WEBHOOK_SUBSCRIPTIONSList 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).

Input Parameters

integer
Maximum number of subscriptions to return (1-100). Defaults to Square’s default if unset.
string
Pagination cursor from a previous call; use to fetch the next page.
string
Sort order by creation time. Allowed values: ‘ASC’ or ‘DESC’.
boolean
If true, include disabled subscriptions in the response. Defaults to false.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: SQUARE_PAY_ORDERPays an existing Square order by processing approved payments and completing the transaction. Use this action when you need to finalize payment on an order that has already been created and has associated approved payments. The total amount of the payment_ids provided must equal the order total, and upon success, the order state transitions to COMPLETED. Important: The payments referenced in payment_ids must be in APPROVED status and must have been created with a reference to this order_id. For orders with a zero total, you can pass an empty payment_ids array or omit it entirely. Using the idempotency_key prevents duplicate payment processing if the request is retried. Required permissions: ORDERS_WRITE, PAYMENTS_WRITE

Input Parameters

string
required
The unique Square-generated ID of the order to pay. This is typically a long alphanumeric string (e.g., ‘CAISENgvlJ6jLWAzERDzjyHVybY’). You can obtain order IDs from the Search Orders endpoint or from webhook notifications.
array
Identifiers of approved payments to collect. The total of all listed payments must equal the order total. These payments must have been created with reference to this order and be in APPROVED status. For orders with zero total, you may pass an empty array.
integer
The version of the order to pay. If not provided, the latest version is used. Use this for optimistic concurrency control to ensure you’re paying the expected version of the order.
string
required
A unique key to ensure idempotency and prevent duplicate payments. Generate a new unique key per payment request. This is critical for preventing accidental double-charging.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: SQUARE_REMOVE_GROUP_FROM_CUSTOMERRemoves 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.

Input Parameters

string
required
The ID of the customer group to remove the customer from.
string
required
The ID of the customer to remove from the group.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: SQUARE_RETRIEVE_BULK_CUSTOMERSTool to retrieve multiple customer profiles in a single request. Use when you need to efficiently fetch up to 100 customer profiles by their IDs.

Input Parameters

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

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: SQUARE_RETRIEVE_CHANNELRetrieve 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.

Input Parameters

string
required
The unique Square-generated ID of the channel to retrieve. This is typically an alphanumeric string starting with ‘CH_’ (e.g., ‘CH_6RMv8wKc6TGsx9yuIG1eIUxR2ZKkGBeBuirfYRlQuYC’).

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: SQUARE_RETRIEVE_CHANNELS_BULKTool 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.

Input Parameters

array
required
Array of channel IDs to retrieve in bulk. Each ID uniquely identifies a channel to fetch.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: SQUARE_RETRIEVE_CUSTOMERTool 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.

Input Parameters

string
required
The ID of the customer to retrieve. This is the unique Square-generated customer identifier.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: SQUARE_RETRIEVE_CUSTOMER_GROUPTool 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.

Input Parameters

string
required
The ID of the customer group to retrieve. This is a unique Square-assigned identifier.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: SQUARE_RETRIEVE_CUSTOMER_SEGMENTTool 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.

Input Parameters

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

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: SQUARE_RETRIEVE_DISPUTETool to retrieve a Square dispute by ID. Endpoint: GET /v2/disputes/{dispute_id}

Input Parameters

string
required
ID of the dispute to retrieve.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: SQUARE_RETRIEVE_INVENTORY_CHANGESRetrieves physical counts and inventory adjustments for a catalog object at selected locations, or all locations if none are specified. Results are paginated newest first, supporting inventory history review and reconciliation; INVENTORY_READ permission is required. DEPRECATED: Square retired this endpoint; use BatchRetrieveInventoryChanges with a single catalog object ID instead.

Input Parameters

string
A pagination cursor returned by a previous call to this endpoint. Provide this to retrieve the next set of results for the original query.
string
The Location IDs to look up as a comma-separated list. An empty value queries all locations.
string
required
The Square-generated ID of the CatalogObject to retrieve inventory changes for. This is typically an ITEM_VARIATION ID.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: SQUARE_RETRIEVE_INVENTORY_COUNTS_BATCHRetrieve inventory counts for multiple catalog objects and locations in a single batch request. Filter by catalog objects, locations, states, or an updated-after timestamp for inventory sync and reporting.

Input Parameters

integer
Maximum number of inventory count records to return per page. Must be between 1 and 1000. Defaults to 25.
string
Pagination cursor returned by a previous call to this endpoint. Provide this to retrieve the next page of results.
array
Filter results by inventory states. Provide one or more inventory states to filter by. Note: NONE, SOLD, and UNLINKED_RETURN states are ignored by this filter.
array
Filter results by location IDs. Provide Square-assigned location IDs to retrieve inventory counts for specific locations only. If not provided, returns counts for all locations.
string
Filter to return inventory counts updated after this timestamp, in RFC 3339 format (e.g., ‘2024-01-01T00:00:00Z’). Useful for syncing inventory changes since a specific time.
array
Filter results by catalog object IDs. Provide Square-assigned IDs for the catalog objects (item variations or items) you want to retrieve inventory counts for. Maximum 1000 IDs.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: SQUARE_RETRIEVE_LOCATIONTool 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.

Input Parameters

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

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: SQUARE_RETRIEVE_LOCATION_CUSTOM_ATTRIBUTERetrieves 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.

Input Parameters

string
required
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.
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.
string
required
The ID of the target location. You can obtain this from the List Locations endpoint.
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.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: SQUARE_RETRIEVE_LOCATION_CUSTOM_ATTRIBUTE_DEFINITIONTool 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.

Input Parameters

string
required
The key of the custom attribute definition to retrieve. If the requesting application is not the definition owner, you must use the qualified key.
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.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: SQUARE_RETRIEVE_MERCHANT_CUSTOM_ATTRIBUTERetrieves 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.

Input Parameters

string
required
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.
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.
string
required
The ID of the target merchant. This is the unique Square-assigned ID that identifies the merchant.
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.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: SQUARE_RETRIEVE_MERCHANT_CUSTOM_ATTRIBUTE_DEFINITIONTool 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.

Input Parameters

string
required
The key of the custom attribute definition to retrieve. If the requesting application is not the definition owner, you must use the qualified key.
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.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: SQUARE_RETRIEVE_MERCHANTSTool 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.

Input Parameters

array
required
List of merchant IDs to retrieve information for. Each ID must be a valid Square merchant identifier.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: SQUARE_RETRIEVE_ORDERRetrieves 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.

Input Parameters

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

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: SQUARE_RETRIEVE_TOKEN_STATUSTool 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.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: SQUARE_RETRIEVE_WEBHOOK_SUBSCRIPTIONRetrieve 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).

Input Parameters

string
required
ID of the webhook subscription to retrieve. Square webhook subscription IDs typically start with ‘wbhk_’.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: SQUARE_SEARCH_BOOKING_AVAILABILITYSearches for available appointment time slots for booking services at Square locations. Use this action when you need to find open booking slots for a specific service, location, and time range. This is essential for scheduling appointments as it shows which times are available for booking based on service requirements and team member availability.

Input Parameters

object
required
Query object containing filter criteria for the availability search. Specifies the time range, location, and service details.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: SQUARE_SEARCH_CATALOG_OBJECTSSearches for catalog objects (items, categories, taxes, discounts, etc.) in the Square catalog. Use this action when you need to find specific catalog items by name, SKU, category, or other attributes, or when retrieving the entire catalog with filtering and sorting options. Supports full-text search, exact matching, prefix matching, range queries, and complex combinations of filters.

Input Parameters

integer
Maximum number of results to return per page. This is advisory only; Square may return more or fewer results. Maximum: 1000. Default: 25.
object
Composite query for filtering and sorting catalog objects.
string
Pagination cursor returned by a previous call. Use to retrieve the next set of results.
string
Return objects modified after this RFC 3339 timestamp (exclusive). Use for incremental sync.
array
The desired catalog object types to include in the result. If not specified, all object types may be returned. Common types include: ITEM, ITEM_VARIATION, CATEGORY, DISCOUNT, TAX, MODIFIER, MODIFIER_LIST, IMAGE, MEASUREMENT_UNIT, ITEM_OPTION, PRICING_RULE, PRODUCT_SET, TIME_PERIOD, SUBSCRIPTION_PLAN, CUSTOM_ATTRIBUTE_DEFINITION, QUICK_AMOUNT_SETTINGS.
boolean
If true, returns deleted objects with is_deleted set to true. Cannot be true simultaneously with include_category_path_to_root. Default: false.
If true, includes related objects referenced by the result objects (one level deep). For example, if an ITEM is returned, its variations are included. Default: false.
boolean
If true, includes the path_to_root field in category objects showing the hierarchy from root to the category. Cannot be true with include_deleted_objects. Default: false.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: SQUARE_SEARCH_CUSTOMERSTool 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.

Input Parameters

boolean
Whether to return the total count of matching customers in the response. Default: false.
integer
Maximum number of results to return per page (1-100). Default: 100.
object
Query parameters for filtering and sorting customers.
string
Pagination cursor returned by a previous call. Use to retrieve the next set of results.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: SQUARE_SEARCH_ORDERSTool 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.

Input Parameters

integer
Maximum number of results to return per page. Default: 500, Maximum: 1000.
object
Query parameters for filtering and sorting orders.
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.
array
required
The location IDs for the orders to query. All locations must belong to the same merchant. Maximum: 10 location IDs.
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.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: SQUARE_SUBMIT_DISPUTE_EVIDENCESubmits 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.

Input Parameters

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

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: SQUARE_TEST_WEBHOOK_SUBSCRIPTIONTests 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.

Input Parameters

string
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.
string
required
The ID of the webhook subscription to test. Obtain this from the List Webhook Subscriptions or Create Webhook Subscription endpoints.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: SQUARE_UPDATE_BOOKINGUpdates an existing Square booking with new appointment details, times, notes, or team members. Use when you need to modify a booking’s start time, change appointment segments, update customer or seller notes, or modify the location type. Requires the current booking version number for optimistic concurrency control - get this from a previous retrieve booking call. Seller must subscribe to Appointments Plus or Premium to use this action.

Input Parameters

object
required
The booking data to update. Must include version field for optimistic concurrency control.
string
required
The ID of the Booking object representing the to-be-updated booking.
string
A unique key to ensure idempotency. Generate a new key per update request.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: SQUARE_UPDATE_CUSTOMERUpdates an existing Square customer profile, including details such as name, email, address, or phone number. Supports sparse updates and an optional version for optimistic concurrency control; null values are omitted rather than sent to remove fields.

Input Parameters

string
A custom note associated with the customer profile.
object
Physical address with sparse update support.
object
Tax ID for EU/UK sellers only.
integer
Current customer profile version for optimistic concurrency control. Get this from a previous retrieve/search customer call.
string
Birthday in date format: YYYY-MM-DD or MM-DD.
string
A nickname for the customer profile. Max 100 characters.
string
The given name (first name) associated with the customer profile. Max 300 characters.
string
required
The ID of the customer to update.
string
The family name (last name) associated with the customer profile. Max 300 characters.
string
A business name associated with the customer profile. Max 500 characters.
string
Phone number requiring 9-16 digits, optional + prefix, and country code.
string
An optional second ID used to associate the customer profile with an entity in another system. Max 100 characters.
string
The email address associated with the customer profile. Max 254 characters.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: SQUARE_UPDATE_CUSTOMER_CUSTOM_ATTRIBUTE_DEFINITIONTool 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.

Input Parameters

string
required
The key of the custom attribute definition to update.
string
Updated display name for the custom attribute definition.
object
Updated schema definition for the custom attribute. Required when the attribute type is Selection. Use JSON schema format to define allowed values and constraints.
integer
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.
string
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).
string
Updated description of the custom attribute definition.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: SQUARE_UPDATE_CUSTOMER_GROUPUpdates the name of an existing Square customer group identified by its ID.

Input Parameters

object
required
The CustomerGroup object including all the updates you want to make.
string
required
The ID of the customer group to update. This is the unique identifier for the group that will be modified.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: SQUARE_UPDATE_CUSTOMERS_BULKUpdates multiple Square customer profiles in a single batch, using customer IDs and the fields to update. An optional version supports optimistic concurrency control; null-valued fields are omitted from the request.

Input Parameters

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

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: SQUARE_UPDATE_LOCATIONTool 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.

Input Parameters

object
required
The location object with only the fields to update. All fields are optional.
string
required
The ID of the location to update.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: SQUARE_UPDATE_LOCATION_CUSTOM_ATTRIBUTE_DEFINITIONTool 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.

Input Parameters

string
required
The key of the custom attribute definition to update. This is the unique identifier for the custom attribute definition.
string
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.
object
required
The custom attribute definition fields to update. Only the provided fields will be updated; omitted fields remain unchanged.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: SQUARE_UPDATE_MERCHANT_CUSTOM_ATTRIBUTE_DEFINITIONTool 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.

Input Parameters

string
required
The key of the custom attribute definition to update. This is the unique identifier for the custom attribute definition.
string
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.
object
required
The custom attribute definition fields to update. Only the provided fields will be updated; omitted fields remain unchanged.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: SQUARE_UPDATE_ONLINE_CHECKOUT_LOCATION_SETTINGSTool 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.

Input Parameters

string
required
The ID of the location for which to update online checkout settings. This is the unique Square-generated identifier for the location.
object
required
The location settings to update. Only include the fields that you want to change.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: SQUARE_UPDATE_ORDERUpdates 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.

Input Parameters

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.
string
required
ID of the order to update.
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.
string
A unique key to ensure idempotency. Generate a new key per update.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: SQUARE_UPDATE_TEAM_MEMBERTool to update an existing Square team member’s information. Use when you need to modify team member details like name, email, phone number, status, location assignments, or wage settings. Supports sparse updates: only include fields you want to change. To update wage_setting.job_assignments, provide the complete list of job assignments.

Input Parameters

object
required
The team member fields to update. Only include fields you want to change. Fields can be cleared using a null value.
string
required
The ID of the team member to update.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: SQUARE_UPDATE_WEBHOOK_SUBSCRIPTIONTool 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.

Input Parameters

string
New display name for the subscription (max 64 characters).
boolean
Whether the subscription should be active.
string
Webhook API version to use for this subscription, e.g., ‘2021-06-16’.
array
List of event types to subscribe to, e.g., [‘payment.created’].
string
required
ID of the webhook subscription to update.
string
Destination URL for webhook notifications.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: SQUARE_UPDATE_WEBHOOK_SUBSCRIPTION_SIGNATURE_KEYTool to rotate the signature key for a webhook subscription. Use when you need to replace the current signature key for security purposes.

Input Parameters

string
A unique string to make this request idempotent. Max 45 characters.
string
required
The ID of the webhook subscription to rotate the signature key for.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: SQUARE_UPSERT_CATALOG_OBJECTCreates or updates a catalog object in the Square catalog. Use when you need to add or modify items, variations, categories, taxes, discounts, or other catalog entities in the merchant’s inventory system. For new objects, use a temporary ID starting with ’#’ (e.g., ‘#new-item-1’). For updates, provide the existing object ID and current version number. The object type field determines which data field should be populated (e.g., type=ITEM requires item_data). Only one update request is processed at a time per seller account.

Input Parameters

object
required
The catalog object to create or update. For new objects, use a temporary ID starting with ’#’. For updates, include the existing object ID and current version number.
string
required
A unique key to ensure idempotent request processing. Use a UUID or similar unique identifier to prevent duplicate object creation if the request is retried.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: SQUARE_UPSERT_CATALOG_OBJECTS_BATCHCreates or updates multiple catalog objects in a single batch operation. Use this action when you need to efficiently manage catalog items, categories, discounts, taxes, or other catalog entities in bulk. Supports up to 10,000 objects across all batches, with each batch containing up to 1,000 objects. Use temporary IDs starting with # (e.g., #Tea) for new objects, and existing IDs to update objects. Each batch is processed atomically (all succeed or all fail). Use when you need to create multiple catalog items at once, update existing catalog objects in bulk, or set up an initial product catalog. The idempotency_key ensures safe retries without duplicate creation. Required permissions: ITEMS_WRITE

Input Parameters

array
required
List of batches containing catalog objects to create or update. Each batch can contain up to 1,000 objects. Maximum 10,000 total objects across all batches. Each batch is processed atomically.
string
required
A unique key to ensure idempotent request processing. Prevents duplicate object creation on retries. Must be 1-128 characters long.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: SQUARE_UPSERT_CUSTOMER_CUSTOM_ATTRIBUTETool 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.

Input Parameters

string
required
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’).
string
required
The ID of the target customer profile. You can retrieve customer IDs from the List Customers endpoint or when creating a customer.
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.
object
required
The custom attribute object containing the value and optional version number.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: SQUARE_UPSERT_CUSTOMER_CUSTOM_ATTRIBUTES_BATCHTool 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

Input Parameters

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

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: SQUARE_UPSERT_LOCATION_CUSTOM_ATTRIBUTETool 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.

Input Parameters

string
required
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’).
string
required
The ID of the target location. You can retrieve location IDs from the List Locations endpoint.
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.
object
required
The custom attribute object containing the value and optional version number.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: SQUARE_UPSERT_LOCATIONS_CUSTOM_ATTRIBUTES_BATCHTool 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

Input Parameters

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

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: SQUARE_UPSERT_MERCHANT_CUSTOM_ATTRIBUTETool 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.

Input Parameters

string
required
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’).
string
required
The ID of the target merchant. You can obtain this from the List Merchants endpoint or from your Square dashboard.
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.
object
required
The custom attribute object containing the value and optional version number.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: SQUARE_UPSERT_MERCHANTS_CUSTOM_ATTRIBUTES_BATCHTool 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

Input Parameters

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

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not