> This page is for Agent Handler. > For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.merge.dev/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.merge.dev/_mcp/server. # Square **Authentication:** OAuth or personal access token. See [Magic Link](/merge-agent-handler/features/magic-link) for the runtime auth flow, or [Application credentials](/merge-agent-handler/admin-setup/add-oauth-credentials) to bring your own OAuth app. ## Sample use cases * List transactions over \$500 last week, by location. * Issue a refund for the transaction at the SF location for `TXN-12345`. * Pull total revenue by item category for Q1. ## Available Tools #### create\_booking Create a booking/appointment. Requires start\_at, location\_id, and appointment\_segments with service and team member. #### list\_bookings List bookings. Filter by location, team member, or date range. Returns paginated list with status. #### get\_booking Get a booking by ID. Returns full booking details including service, team member, and customer. #### update\_booking Update a booking. Can reschedule, change team member, or update notes. Use version for concurrency. #### cancel\_booking Cancel a booking. Booking status changes to CANCELLED. Use booking\_version for concurrency. #### list\_team\_member\_booking\_profiles List team members available for booking. Filter by location or bookable status. Returns profiles with availability. #### search\_availability Search for available booking time slots. Specify date range and service. Returns available times with team members. #### list\_cards List cards on file. Filter by customer\_id or reference\_id. Returns cards with last 4 digits, brand, and expiration. #### get\_card Get a card by ID. Returns card details including last 4 digits, brand, expiration, and billing address. #### create\_card Save a card on file for a customer. Requires source\_id (card nonce from Web Payments SDK) and customer\_id. Returns saved card. #### disable\_card Disable a card on file. The card can no longer be used for payments. This action is irreversible. #### list\_catalog List catalog objects (items, categories, taxes, discounts). Filter by object types. Returns paginated list with cursor. #### get\_catalog\_object Get a catalog object by ID. Include related objects (variations, categories, images) with include\_related\_objects. #### upsert\_catalog\_object Create or update a catalog object. Object must include type and type-specific data (item\_data, category\_data, etc). #### delete\_catalog\_object Delete a catalog object by ID. Also deletes related objects (e.g., deleting item deletes its variations). #### search\_catalog\_objects Search catalog by text (name, description, SKU), exact match, or prefix. Filter by object types and include related objects. #### batch\_upsert\_catalog\_objects Create or update multiple catalog objects in one request. More efficient than individual upserts. #### batch\_delete\_catalog\_objects Delete multiple catalog objects in one request. Also deletes related objects. #### create\_customer\_group Create a customer group for segmentation. Groups help organize customers for marketing and reporting. #### list\_customer\_groups List all customer groups. Returns group names and IDs for segmentation. #### get\_customer\_group Get a customer group by ID. Returns group details including name and creation time. #### update\_customer\_group Update a customer group's name. Returns the updated group. #### delete\_customer\_group Delete a customer group. Removes the group but not the customers in it. #### add\_customer\_to\_group Add a customer to a group. Customer will be included in group-based reports and marketing. #### remove\_customer\_from\_group Remove a customer from a group. Customer will no longer be included in group-based activities. #### create\_customer Create a new customer profile. Provide name, email, phone, address. Returns customer with unique ID for future payments and orders. #### list\_customers List all customers with optional sorting and pagination. Returns customers with their contact info and IDs. #### get\_customer Get a customer by ID. Returns full customer profile including contact info, addresses, and group memberships. #### update\_customer Update a customer's profile. Provide fields to update (name, email, phone, address, etc). Returns updated customer. #### delete\_customer Delete a customer by ID. Removes the customer profile. Use version for optimistic concurrency. #### search\_customers Search customers by email, phone, reference\_id, or fuzzy name match. Use to find existing customers before creating duplicates. #### create\_gift\_card Create a gift card. Specify PHYSICAL or DIGITAL type. Card starts with \$0 balance until activated. #### list\_gift\_cards List gift cards. Filter by type, state, or linked customer. Returns cards with balances. #### get\_gift\_card Get a gift card by ID. Returns card details including balance, state, and linked customers. #### get\_gift\_card\_from\_gan Get a gift card by its GAN (gift card account number). Use when customer provides the card number. #### link\_customer\_to\_gift\_card Link a customer to a gift card. Customer can view and use the card in their account. #### unlink\_customer\_from\_gift\_card Unlink a customer from a gift card. Customer will no longer see the card in their account. #### create\_gift\_card\_activity Create a gift card activity: ACTIVATE, LOAD, REDEEM, DEACTIVATE, or ADJUST balance. Each type has specific required details. #### batch\_retrieve\_inventory\_counts Get inventory counts for catalog items at locations. Filter by item IDs, location IDs, or inventory states. #### batch\_change\_inventory Change inventory counts. Supports physical counts, adjustments, and transfers between locations. Requires idempotency\_key. #### retrieve\_inventory\_changes Get history of inventory changes. Filter by item, location, change type, or time range. #### create\_invoice Create an invoice for an order. Requires location\_id, order\_id. Invoice starts as DRAFT until published. #### list\_invoices List invoices for a location. Returns paginated list with invoice status and amounts. #### get\_invoice Get an invoice by ID. Returns full invoice details including payment requests and status. #### update\_invoice Update a draft invoice. Can modify payment requests, recipient, title, etc. Requires current version. #### delete\_invoice Delete a draft invoice. Cannot delete published invoices - cancel them instead. #### publish\_invoice Publish a draft invoice to send to customer. Invoice status changes from DRAFT to UNPAID. Requires version. #### cancel\_invoice Cancel a published invoice. Changes status to CANCELED. Cannot be undone. Requires version. #### search\_invoices Search invoices by location and optionally by customer. Returns matching invoices with details. #### list\_locations List all business locations. Returns location details including address, hours, and capabilities. #### get\_location Get a location by ID. Returns full location details including address, hours, and social media links. #### create\_location Create a new business location. Requires name. Can include address, hours, and contact info. #### update\_location Update a location's details. Can modify name, address, hours, contact info, and social links. #### create\_loyalty\_account Create a loyalty account for a customer. Link by phone number. Returns account with initial balance. #### search\_loyalty\_accounts Search loyalty accounts by phone, customer ID, or program. Returns accounts with points balances. #### get\_loyalty\_account Get a loyalty account by ID. Returns points balance, lifetime points, and expiring points. #### accumulate\_loyalty\_points Add points to a loyalty account from a purchase. Can link to order\_id or add manual points. #### adjust\_loyalty\_points Manually adjust loyalty points. Positive to add, negative to subtract. Provide reason for audit. #### redeem\_loyalty\_reward Redeem a loyalty reward on an order. Deducts points from account. Returns reward with discount details. #### list\_loyalty\_programs List all loyalty programs. Returns program details including reward tiers and accrual rules. #### list\_merchants List merchants associated with the access token. Usually returns a single merchant for the account. #### get\_merchant Get merchant info by ID. Use 'me' for the current merchant. Returns business name, country, and main location. #### create\_order Create an order with line items. Requires location\_id and idempotency\_key. Can include catalog items or custom items with prices. #### search\_orders Search orders by location, customer, state, or date range. Returns matching orders with details. #### get\_order Get an order by ID. Returns full order details including line items, totals, fulfillments, and payments. #### update\_order Update an order. IMPORTANT: First call get\_order to get current version. Add line items, update fulfillment, or change state. #### pay\_order Pay for an order using payment IDs. Links payments to the order and completes the transaction. #### clone\_order Clone an existing order to create a copy. Useful for repeat orders. Returns new order with same line items. #### calculate\_order Calculate order totals without creating an order. Preview taxes, discounts, and final amounts before committing. #### create\_payment Create a payment to charge a customer. Requires source\_id (card nonce or card on file), idempotency\_key (unique UUID), and amount\_money. Returns payment with status and receipt URL. #### list\_payments List payments with optional filters. Filter by time range, location, card details, or amount. Returns paginated list with cursor for next page. #### get\_payment Get a payment by ID. Returns full payment details including status, amounts, card details, and receipt URL. #### cancel\_payment Cancel a payment that has not been completed. Only works for payments in APPROVED or PENDING status. #### complete\_payment Complete a delayed payment. Use for payments created with autocomplete=false. Captures the authorized amount. #### create\_refund Refund a payment. Requires payment\_id, idempotency\_key, and amount\_money. Can refund full or partial amounts. Returns refund with status. #### list\_refunds List refunds with optional filters. Filter by time range, location, status, or source type. Returns paginated list. #### get\_refund Get a refund by ID. Returns refund details including status, amount, and associated payment. #### create\_subscription Create a subscription for recurring billing. Requires location, plan\_variation\_id, and customer\_id. Returns subscription with status. #### list\_subscriptions List subscriptions. Filter by location or customer. Returns paginated list with status and billing info. #### get\_subscription Get a subscription by ID. Returns full subscription details including phases and scheduled actions. #### update\_subscription Update a subscription. Can change card, tax percentage, or price override. Use version for concurrency. #### cancel\_subscription Cancel a subscription. Schedules cancellation at end of current billing period. #### pause\_subscription Pause a subscription. Can set pause duration or resume date. Customer won't be billed during pause. #### resume\_subscription Resume a paused subscription. Can specify when to resume. Billing resumes from resume date. #### create\_team\_member Create a team member. Provide name, email, phone. Assign to locations. Returns team member with ID. #### list\_team\_members List team members. Filter by location or status. Returns paginated list with contact info. #### get\_team\_member Get a team member by ID. Returns full profile including locations and status. #### update\_team\_member Update a team member. Can modify name, contact info, status, and location assignments. #### search\_team\_members Search team members by location, status, or owner flag. Returns matching members.