Square integration

What it does

The Square integration connects TaskJuice to your clients' Square seller accounts so your workflows can manage customer profiles, push orders through the point-of-sale, charge payments, manage the catalog of items and variations, and react in near real time 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 multiple Square clients keeps each merchant's data isolated.

Connect a Square account

1. Open your workspace in TaskJuice and navigate to Connections.
2. Choose Square and click Connect.
3. Sign in to Square with credentials that have permission to manage the seller account.
4. Approve the scopes covering customers, orders, payments, and catalog items.
5. TaskJuice returns to the workspace with the connection ready to use in any workflow.

To revoke access at any time, sign in to the Square Developer dashboard and remove the TaskJuice authorization from the seller's account.

Triggers

• square/payment-event fires on payment.created and payment.updated events. Filter downstream by type to narrow to specific transitions such as completed captures or refunds.
• square/order-event fires on order.created, order.updated, and order.fulfillment.updated events so a workflow can react when carts move through fulfillment.
• square/customer-event fires on customer.created, customer.updated, and customer.deleted events.

Each webhook arrives signed with HMAC-SHA256 on the x-square-hmacsha256-signature header. Square signs the concatenation of the notification URL and the raw request body using the subscription's signature key. Paste the signature key from your TaskJuice connection into the Square Developer dashboard under Webhook Subscriptions when you create the subscription that points at TaskJuice.

Actions

• square/create-customer creates a new Square customer profile with name, email, phone, and reference id.
• square/list-customers paginates the seller's customer roster with cursor-based pagination and the standard sort options.
• square/retrieve-customer fetches a single customer profile by its Square id.
• square/create-order opens a new order under a Square location, optionally attached to a customer, with line items priced in the smallest currency unit.
• square/retrieve-order fetches a single order by its Square id, including line items and totals.
• square/create-payment charges a card nonce or a stored source via the Square Payments API and can be linked to an order, customer, or location.
• square/retrieve-payment fetches a single payment by id along with its status and source type.
• square/create-catalog-item upserts an item (and its variations) into the seller's Square catalog using the standard idempotency key contract.

Known limitations

• Per Square's published guidance, the Connect APIs apply per-application and per-merchant rate limits. TaskJuice surfaces 429 responses as retryable rate-limit errors so downstream retries back off automatically.
• The bundle pins the Square-Version request header to 2024-10-17. Newer Square API releases that change response shapes will be picked up by an explicit version bump, not silently.
• Webhook subscriptions are tied to a single signature key and a single notification URL. If you rotate the URL or the key, recreate the subscription in the Square Developer dashboard.
• The integration targets the US production endpoint (connect.squareup.com). Sandbox and regional Square endpoints are out of scope for this bundle.