Square

Create a booking/appointment. Requires start_at, location_id, and appointment_segments with service and team member.

List bookings. Filter by location, team member, or date range. Returns paginated list with status.

Get a booking by ID. Returns full booking details including service, team member, and customer.

Update a booking. Can reschedule, change team member, or update notes. Use version for concurrency.

Cancel a booking. Booking status changes to CANCELLED. Use booking_version for concurrency.

List team members available for booking. Filter by location or bookable status. Returns profiles with availability.

Search for available booking time slots. Specify date range and service. Returns available times with team members.

List cards on file. Filter by customer_id or reference_id. Returns cards with last 4 digits, brand, and expiration.

Get a card by ID. Returns card details including last 4 digits, brand, expiration, and billing address.

Save a card on file for a customer. Requires source_id (card nonce from Web Payments SDK) and customer_id. Returns saved card.

Disable a card on file. The card can no longer be used for payments. This action is irreversible.

List catalog objects (items, categories, taxes, discounts). Filter by object types. Returns paginated list with cursor.

Get a catalog object by ID. Include related objects (variations, categories, images) with include_related_objects.

Create or update a catalog object. Object must include type and type-specific data (item_data, category_data, etc).

Delete a catalog object by ID. Also deletes related objects (e.g., deleting item deletes its variations).

Search catalog by text (name, description, SKU), exact match, or prefix. Filter by object types and include related objects.

Create or update multiple catalog objects in one request. More efficient than individual upserts.

Delete multiple catalog objects in one request. Also deletes related objects.

Create a customer group for segmentation. Groups help organize customers for marketing and reporting.

List all customer groups. Returns group names and IDs for segmentation.

Get a customer group by ID. Returns group details including name and creation time.

Update a customer group’s name. Returns the updated group.

Delete a customer group. Removes the group but not the customers in it.

Add a customer to a group. Customer will be included in group-based reports and marketing.

Remove a customer from a group. Customer will no longer be included in group-based activities.

Create a new customer profile. Provide name, email, phone, address. Returns customer with unique ID for future payments and orders.

List all customers with optional sorting and pagination. Returns customers with their contact info and IDs.

Get a customer by ID. Returns full customer profile including contact info, addresses, and group memberships.

Update a customer’s profile. Provide fields to update (name, email, phone, address, etc). Returns updated customer.

Delete a customer by ID. Removes the customer profile. Use version for optimistic concurrency.

Search customers by email, phone, reference_id, or fuzzy name match. Use to find existing customers before creating duplicates.

Create a gift card. Specify PHYSICAL or DIGITAL type. Card starts with $0 balance until activated.

List gift cards. Filter by type, state, or linked customer. Returns cards with balances.

Get a gift card by ID. Returns card details including balance, state, and linked customers.

Get a gift card by its GAN (gift card account number). Use when customer provides the card number.

Link a customer to a gift card. Customer can view and use the card in their account.

Unlink a customer from a gift card. Customer will no longer see the card in their account.

Create a gift card activity: ACTIVATE, LOAD, REDEEM, DEACTIVATE, or ADJUST balance. Each type has specific required details.

Get inventory counts for catalog items at locations. Filter by item IDs, location IDs, or inventory states.

Change inventory counts. Supports physical counts, adjustments, and transfers between locations. Requires idempotency_key.

Get history of inventory changes. Filter by item, location, change type, or time range.

Create an invoice for an order. Requires location_id, order_id. Invoice starts as DRAFT until published.

List invoices for a location. Returns paginated list with invoice status and amounts.

Get an invoice by ID. Returns full invoice details including payment requests and status.

Update a draft invoice. Can modify payment requests, recipient, title, etc. Requires current version.

Delete a draft invoice. Cannot delete published invoices - cancel them instead.

Publish a draft invoice to send to customer. Invoice status changes from DRAFT to UNPAID. Requires version.

Cancel a published invoice. Changes status to CANCELED. Cannot be undone. Requires version.

Search invoices by location and optionally by customer. Returns matching invoices with details.

List all business locations. Returns location details including address, hours, and capabilities.

Get a location by ID. Returns full location details including address, hours, and social media links.

Create a new business location. Requires name. Can include address, hours, and contact info.

Update a location’s details. Can modify name, address, hours, contact info, and social links.

Create a loyalty account for a customer. Link by phone number. Returns account with initial balance.

Search loyalty accounts by phone, customer ID, or program. Returns accounts with points balances.

Get a loyalty account by ID. Returns points balance, lifetime points, and expiring points.

Add points to a loyalty account from a purchase. Can link to order_id or add manual points.

Manually adjust loyalty points. Positive to add, negative to subtract. Provide reason for audit.

Redeem a loyalty reward on an order. Deducts points from account. Returns reward with discount details.

List all loyalty programs. Returns program details including reward tiers and accrual rules.

List merchants associated with the access token. Usually returns a single merchant for the account.

Get merchant info by ID. Use ‘me’ for the current merchant. Returns business name, country, and main location.

Create an order with line items. Requires location_id and idempotency_key. Can include catalog items or custom items with prices.

Search orders by location, customer, state, or date range. Returns matching orders with details.

Get an order by ID. Returns full order details including line items, totals, fulfillments, and payments.

Update an order. IMPORTANT: First call get_order to get current version. Add line items, update fulfillment, or change state.

Pay for an order using payment IDs. Links payments to the order and completes the transaction.

Clone an existing order to create a copy. Useful for repeat orders. Returns new order with same line items.

Calculate order totals without creating an order. Preview taxes, discounts, and final amounts before committing.

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 with optional filters. Filter by time range, location, card details, or amount. Returns paginated list with cursor for next page.

Get a payment by ID. Returns full payment details including status, amounts, card details, and receipt URL.

Cancel a payment that has not been completed. Only works for payments in APPROVED or PENDING status.

Complete a delayed payment. Use for payments created with autocomplete=false. Captures the authorized amount.

Refund a payment. Requires payment_id, idempotency_key, and amount_money. Can refund full or partial amounts. Returns refund with status.

List refunds with optional filters. Filter by time range, location, status, or source type. Returns paginated list.

Get a refund by ID. Returns refund details including status, amount, and associated payment.

Create a subscription for recurring billing. Requires location, plan_variation_id, and customer_id. Returns subscription with status.

List subscriptions. Filter by location or customer. Returns paginated list with status and billing info.

Get a subscription by ID. Returns full subscription details including phases and scheduled actions.

Update a subscription. Can change card, tax percentage, or price override. Use version for concurrency.

Cancel a subscription. Schedules cancellation at end of current billing period.

Pause a subscription. Can set pause duration or resume date. Customer won’t be billed during pause.

Resume a paused subscription. Can specify when to resume. Billing resumes from resume date.

Create a team member. Provide name, email, phone. Assign to locations. Returns team member with ID.

List team members. Filter by location or status. Returns paginated list with contact info.

Get a team member by ID. Returns full profile including locations and status.

Update a team member. Can modify name, contact info, status, and location assignments.

Search team members by location, status, or owner flag. Returns matching members.

Validate Square API credentials by listing merchants. Returns {success, message}.