Square integration

What it does

The Square integration connects TaskJuice to your clients' Square seller accounts. Your workflows can manage customer profiles and groups, create and update orders, take, complete, cancel, and refund payments, draft and send invoices, book and reschedule appointments, manage catalog items and inventory, and react to events that fire inside the seller's account. Every read and write is scoped to the merchant who authorized the connection, so an agency that manages several Square clients keeps each merchant's data separate.

Connect a Square account

Square connections use OAuth through your own Square application, so the consent screen your client sees carries your agency's name.

1. Create an application in the Square Developer Console and copy its production application ID and secret.
2. Under OAuth, add your TaskJuice OAuth callback URL as the redirect URL.
3. In TaskJuice, add the application ID and secret as your Square OAuth client, and tick the permissions your workflows need: customers, orders, payments, items, inventory, invoices, merchant profile (for locations), employees (for the team member picker), and appointments. Appointments need both the APPOINTMENTS_* and the seller-level APPOINTMENTS_ALL_* permissions, or booking actions only see bookings your app created.
4. Add a Square connection from any Square node in the workflow editor, or send your client a connection link. Your client signs in to Square and approves access.

To revoke access, the seller removes the authorization from their Square Dashboard under Apps.

Set up triggers

Square webhook subscriptions belong to your Square application, not to one seller, so one subscription delivers events for every seller who connected through that application. You create it once, by hand:

1. In the Square Developer Console, open your application and go to Webhooks > Subscriptions, then Add subscription.
2. Paste the Square webhook URL shown in the TaskJuice trigger panel as the notification URL. It must match exactly; Square signs the URL together with the body, so a trailing slash or a different host makes every delivery fail verification.
3. Tick the event types your workflows use (listed under each trigger below) and save.
4. Copy the subscription's Signature key and paste it into the trigger panel's signing secret field.

TaskJuice routes each delivery to the right client by the seller's merchant_id.

Triggers

• Payment Event fires on payment.created and payment.updated.
• Order Event fires on order.created, order.updated, and order.fulfillment.updated.
• Customer Event fires on customer.created, customer.updated, and customer.deleted.
• Booking Event fires on booking.created and booking.updated (Square Appointments).
• Invoice Event fires on invoice.created, invoice.published, invoice.updated, invoice.payment_made, invoice.scheduled_charge_failed, invoice.canceled, invoice.refunded, and invoice.deleted.
• Refund Event fires on refund.created and refund.updated.
• Inventory Count Updated fires on inventory.count.updated when an item variation's stock changes at a location.
• Catalog Version Updated fires on catalog.version.updated whenever anything in the catalog changes.

Each trigger carries the event type, so you can branch on one transition, for example only payment.updated with a COMPLETED status.

Actions

Customers

• Create Customer, Update Customer, Delete Customer, Retrieve Customer, List Customers, and Search Customers.
• Add Customer to Group and Remove Customer from Group, with the group picked from a list.
• Set Customer Custom Attribute sets a custom attribute value on a customer.

Orders and payments

• Create Order, Update Order, Retrieve Order, and Search Orders.
• Create Payment charges a card or stored card, or records a CASH or EXTERNAL payment against an order to mark it paid.
• Complete Payment and Cancel Payment finish or void a payment created with autocomplete off.
• Retrieve Payment and List Payments.
• Refund Payment and List Refunds.

Invoices

• Create Invoice, Send Invoice, Retrieve Invoice, List Invoices, Cancel Invoice, and Delete Invoice (drafts only).

Appointments

• Create Booking, Update Booking, Cancel Booking, Retrieve Booking, and List Bookings, with the location picked from a list (and the team member, when listing).

Catalog and inventory

• Create Catalog Item, Retrieve Catalog Object, Delete Catalog Object, and Search Catalog Items. Set the product type to APPOINTMENTS_SERVICE to find bookable services.
• Change Inventory adjusts stock, and Retrieve Inventory Count reads current stock per location.
• List Locations returns every location on the seller account.

Known limitations

• Triggers need a manual subscription. Square only lets an application's own access token manage webhook subscriptions, so TaskJuice cannot create the subscription for you. Add any new event types to the subscription in the Square Developer Console when you start using a new trigger.
• Catalog changes arrive as one coarse event. Square sends catalog.version.updated for the whole catalog, not per item. Use Search Catalog Items or Retrieve Catalog Object to find what changed.
• Updates use optimistic concurrency. Update Order, Update Booking, Cancel Invoice, and Send Invoice need the record's current version; read it first, or Square rejects the call with a conflict.
• Every request pins Square-Version: 2026-08-19. Newer Square API versions are adopted by an explicit update, not silently.
• Production only. The integration calls connect.squareup.com; the Square Sandbox is not supported.
• Scope of the action set. The integration covers the Square operations agencies use day to day. Labor, loyalty, gift cards, subscriptions, terminal, disputes, payouts, vendors, and custom-attribute definitions are not included.
• Square rate-limits per application and seller. A 429 is retried with backoff automatically.