Configure Square as a data pipeline source ​

Set up Square as a data pipeline source to extract payment, order, catalog, customer, and labor records into your destination.

Use this guide to generate a Square access token, set up a connection, configure your pipeline, add objects, review sync behavior, and understand known limitations.

Features supported ​

The following features are supported when you use Square as a pipeline source:

• Cloud connectivity: Connect to Square over HTTPS through https://connect.squareup.com/v2. On-prem agents aren't required.
• Sandbox and production environments: Connect to either your live production account or a Square Sandbox account for testing. Workato treats each mode as a separate environment.
• Full sync and incremental sync: Supports full sync and incremental sync modes. Incremental sync uses a timestamp filter for objects that support one. Refer to Sync modes for more information.
• Object-level selection: Select Square objects to sync as separate tables in your destination. Refer to Supported objects for the full list.
• Soft-delete tracking: Catalog objects carry a native deleted flag that Workato preserves in your destination. Refer to Delete tracking for more information.
• Custom attributes: Custom attributes that sellers or partner applications define on Customers, Locations, Orders, Merchants, and catalog objects sync as dedicated columns. Refer to Custom attributes for more information.
• Schema drift detection and handling: Detect and apply schema changes automatically with Auto-sync new fields, or keep the schema fixed with Block new fields.
• Field-level data protection: Replicate sensitive fields as is or hash them before they reach your destination.
• Configurable sync frequency: Schedule syncs on a time-based interval or with a cron expression. The minimum supported interval is 15 minutes.

Prerequisites ​

Connecting Square as a data pipeline source requires:

• A Square account, or a Square Sandbox account if you want to test your pipeline before you connect to production data
• Credentials for your chosen authentication method:
  • Personal access token: A Square personal access token generated from the Square Developer Console. Refer to Generate a Square personal access token for setup steps.
  • OAuth 2.0: A Square account user with permission to authorize third-party applications.

Generate a Square personal access token ​

Generate the token in the Square Developer Console before you create the connection in Workato. Skip this section if you connect with OAuth 2.0.

Refer to Square's access token documentation for more information about generating and managing tokens.

Workato requests a read-only scope for each object you can sync, such as PAYMENTS_READ for Payments or CUSTOMERS_READ for Customers for OAuth connections. Refer to Square's OAuth Permissions Reference for more information on the exact scopes requested when you connect.

Supported connection types ​

Square data pipelines support two authentication methods:

• Personal access token: Provide an access token generated from the Square Developer Console. This token grants unrestricted access to your account and is appropriate for single-account integrations. Refer to Generate a Square personal access token for setup steps.
• OAuth 2.0: Connect through an authorization code grant by authorizing Workato access from your Square account. Recommended if you connect multiple sellers' accounts.

Connect to Square ​

Complete the following steps to connect to Square:

Configure the pipeline ​

Complete the following steps to configure Square as your data pipeline source:

[minute] [hour] [day of month] [month] [day of week]

0 8 * * *

Supported objects ​

Square data pipelines sync data from the Square REST API. The following tables list the supported objects, grouped by category. Each object syncs as a separate table in your destination.

Payments and refunds ​

Orders ​

Customers ​

Catalog and inventory ​

Catalog objects support custom attributes and carry a native deleted flag. Refer to Custom attributes and Delete tracking for more information. Inventory reflects current stock levels only and doesn't retain a history of past stock counts.

Locations and account ​

Labor and team ​

Gift cards and loyalty ​

Syncing Loyalty Accounts or Loyalty Programs requires a Loyalty program configured on your Square account. Refer to Limitations for more information.

Invoicing and subscriptions ​

Vendors ​

Sync modes ​

Square data pipelines support full sync and incremental sync. The sync mode is configured per object when you add it to your pipeline.

Full sync ​

A full sync reads all available records from Square for the selected object and replaces the record set in the destination table. Objects without a reliable modified-time filter in the Square API, such as Locations, Merchants, Team Members, and Vendors, support full sync only.

Incremental sync ​

An incremental sync extracts only records that changed since the last successful run. Square incremental sync uses the following mechanisms, depending on the object:

• Payments, Orders, Customers, and most catalog objects (Catalog Items, Catalog Categories, Catalog Discounts, Catalog Taxes, Catalog Modifier Lists, Catalog Pricing Rules): an updated_at filter that captures both new and edited records.
• Inventory: a calculated_at filter that reflects the most recent stock adjustment for each item and location.
• Timecards: a start_at filter, plus a weekly re-read of the trailing 90 days to catch retroactive edits, because Square doesn't expose an updated_at filter for timecards. Refer to Limitations for more information.
• Refunds, Payouts, and Cash Drawer Shifts: a creation-time filter only, so status changes to an already-synced record aren't captured. Refer to Limitations for more information.
• Gift Card Activities: a creation-time filter. Gift card activities are an append-only log and are never edited after creation.

Refer to the Supported objects tables to see the sync mode for each object.

Delete tracking ​

Delete tracking depends on the object's sync mode. Full-sync objects are marked Yes (destination-inferred), because Workato compares each run's complete record set against the previous run and flags records that no longer appear. Catalog Items and its related catalog objects carry a native is_deleted field that Square sets when an object is removed, so Workato marks these Yes (soft) instead.

Objects that sync incrementally with no source-driven delete signal are marked No, because an incremental run only reads changed records and Square doesn't emit delete events through its REST list endpoints. Inventory reflects current stock levels rather than discrete records, so delete tracking doesn't apply.

Schema and data type handling ​

The following considerations apply to schema and data types when you sync data from Square.

Data types ​

Square returns timestamps as RFC 3339 strings in UTC. Nested objects that don't sync as their own child table, such as card details on a payment, sync as a JSON string column instead. Workato extracts Order Line Items, Catalog Item Variations, and Timecard Breaks as separate child tables. Orders don't always include a customer_id. Guest checkouts leave it empty.

Custom attributes ​

Square sellers and partner applications can define custom attributes on Customers, Locations, Orders, Merchants, and catalog objects. Workato discovers each definition and adds it as a dedicated cattr_<key> column, which only appears in your destination if you select it. Selecting a custom attribute column on Customers, Locations, Orders, or Merchants adds an API call per record and increases sync time on high-volume objects; catalog objects don't have this cost, because Square returns their custom attribute values inline.

Sensitive data handling ​

Square objects can contain significant PII and financial data. The following objects commonly contain sensitive fields:

Square doesn't return raw card numbers or CVV values through the API. Square returns only tokenized and fingerprinted card data for Payments.

Use the Hash option in field-level data protection during pipeline configuration to protect PII before it reaches your destination. Refer to the Configure the pipeline steps for more information.

Limitations ​

The following limitations apply when you use Square as a data pipeline source:

Some objects only detect new records, not later updates ​

Refunds, Payouts, and Cash Drawer Shifts filter incremental syncs on creation time only, so a later status change, such as a refund completing or a payout failing, isn't captured after the record's initial sync. Timecards has the same gap beyond its 90-day lookback window. Set the When first started, this pipeline should pick up records from field to a date before the affected records and re-run a full sync to recover a specific date range for any of these objects.

The Loyalty Programs object requires a Square Loyalty program ​

Square accounts can have at most one Loyalty program. Syncing Loyalty Programs fails if your account doesn't have one configured. Skip this object if you don't use Square's loyalty features.

Minimum sync frequency ​

The minimum supported sync interval is 15 minutes. You can't trigger syncs more frequently than this.