.png)
Square Integration Guide
Connect Square payments, orders, customers, catalog, inventory, and invoices with enterprise systems through REST APIs, selected webhooks, and Martini workflows.
Square integration options at a glance
Square’s primary integration surface is its versioned REST API, covering Payments, Orders, Customers, Catalog, Inventory, Locations, Invoices, subscriptions, refunds, and related services. Square also provides webhook notifications for selected payment, order, customer, catalog, inventory, subscription, invoice, and merchant events. OAuth 2.0 supports seller-authorized applications, while personal access tokens support applicable single-account scenarios. Martini can consume these APIs, validate signed webhook requests, orchestrate scheduled or event-driven workflows, manage cursor-based pagination, apply transformations, and coordinate selected batch or asynchronous operations. General-purpose SQL, SOAP, GraphQL, and file-transfer interfaces were not confirmed.
| Integration point | Supported by Square? | Common use cases | How Martini supports it |
|---|---|---|---|
| REST APIs | Yes | Square’s versioned REST APIs support Payments, Orders, Customers, Catalog, Inventory, Locations, Invoices, subscriptions, refunds, and other services. | Martini can consume authenticated HTTP APIs, expose an internal API façade, map JSON, paginate through cursors, and orchestrate create or update operations. |
| Webhooks / outbound callbacks | Limited | Square provides selected payment, order, customer, catalog, inventory, subscription, invoice, and merchant events; coverage does not include every object change. | Martini can receive webhook requests, validate Square signatures, deduplicate events, retrieve current resources, and route workflows. |
| Bulk / async / batch APIs | Limited | Batch and asynchronous operations are available for selected order, catalog, and inventory scenarios rather than as a universal bulk interface. | Martini can coordinate batch calls, persist cursors or job identifiers, and reconcile asynchronous results. |
| Authentication | Yes | Square supports OAuth 2.0 for seller-authorized applications and personal access tokens for applicable single-account use cases; requests use bearer tokens and permissions. | Martini can store credentials in secure configuration, consume bearer-authenticated APIs, and separate tenant-specific authorization data. |
| File / attachment APIs | Limited | Resource-specific image or content handling exists in selected areas, including catalog-related content; no general-purpose file API was confirmed. | Martini can process supported resource payloads but should use a separate document-storage service for arbitrary files. |
| Scheduled synchronization | Yes | Scheduled API retrieval is appropriate for pagination, reconciliation, and objects or changes not covered by selected webhook subscriptions. | Martini workflows can run on schedules, retain synchronization checkpoints, prevent overlapping runs, and retry bounded failures. |
| GraphQL APIs | Not confirmed | No official Square GraphQL API was identified in the supplied documentation; Square’s documented application APIs are REST-based. | Martini should use Square REST APIs rather than assume GraphQL support. |
| SOAP APIs | No | No Square SOAP API was identified in the supplied documentation. | Martini should use Square REST APIs and selected webhooks instead of SOAP. |
| Database access | No | Square does not expose a general SQL or direct database interface for application integrations. | Martini should obtain data through Square APIs, webhooks, and applicable documented reporting or export capabilities. |
How Square exposes data and business events
Square REST APIs
Square’s versioned REST API is the principal integration interface for Payments, Orders, Customers, Catalog, Inventory, Locations, Invoices, subscriptions, refunds, and other services. Operations and schemas are API-specific and versioned.
Martini implementation pattern
Martini implementation pattern: a workflow or API uses bearer-authenticated HTTP requests, handles cursor pagination, maps Square JSON into a canonical model, applies business rules, and writes to downstream systems or exposes a controlled internal façade.
Implementation sequence
Square Webhooks
Square supports webhook notifications for selected payment, order, customer, catalog, inventory, subscription, invoice, and merchant events. Notifications are selective and may identify a changed resource without containing its complete current representation.
Martini implementation pattern
Martini implementation pattern: receive the request through a webhook workflow, validate Square’s signature, acknowledge valid input promptly, use the event ID for idempotency, retrieve the current resource when needed, and route processing asynchronously or through downstream workflows.
Implementation sequence
Square Batch and Async Operations
Square provides batch-style and asynchronous operations for selected APIs, including order retrieval, catalog upserts or retrieval, and supported inventory scenarios. These capabilities are not a universal bulk interface.
Martini implementation pattern
Martini implementation pattern: a scheduled or event-driven workflow groups eligible operations, submits supported batch requests, stores cursors or job identifiers, polls or retrieves results where required, and reconciles partial failures.
Implementation sequence
Square OAuth and Access Tokens
Square supports OAuth 2.0 for applications acting on behalf of sellers and personal access tokens for applicable single-account or development scenarios. API permissions vary by object and operation.
Martini implementation pattern
Martini implementation pattern: store application credentials and tokens as environment secrets, select the minimum required permissions, attach the bearer token to requests, and isolate credentials and resource IDs by seller and environment.
Implementation sequence
Common Square integration patterns
Pattern 1: Post Square payments and orders to accounting
When to use this pattern
Use this pattern when financial and order activity from Square must be posted to an ERP or accounting application. Webhooks can provide timely triggers, while scheduled reconciliation improves completeness for important financial data.
Integration direction
Example Mapping
| Square Field | Canonical Field | Target Field |
|---|---|---|
| order.id | transaction.externalId | externalTransactionId |
| order.total_money.amount | transaction.totalMinorUnits | totalAmountMinorUnits |
| payment.status | payment.status | paymentStatus |
| location_id | businessLocationId | locationId |
Martini implementation pattern
Martini receives a supported event or retrieves records on a schedule, fetches the related Order, Payment, Refund, Customer, and Location resources, preserves minor-unit monetary precision, maps taxes and discounts, applies duplicate and status rules, and retries or flags failed accounting writes for reconciliation.
Martini capabilities used
- workflows
- API consumption
- data mapping
- business rules
- error handling
- scheduled synchronization
Pattern 2: Synchronize Square catalog and inventory
When to use this pattern
Use this pattern when Square catalog definitions or inventory counts must be shared with Shopify, a warehouse platform, or another product system. Batch operations can reduce request volume for supported catalog scenarios.
Integration direction
Example Mapping
| Square Field | Canonical Field | Target Field |
|---|---|---|
| catalog_object.id | product.externalId | productExternalId |
| item_variation.item_variation_data.name | variant.name | variantTitle |
| inventory_count.quantity | stock.quantity | inventoryQuantity |
| location_id | stock.locationId | locationId |
Martini implementation pattern
A scheduled workflow retrieves Catalog objects and inventory counts with cursor state, maps items, variations, modifiers, and locations, applies system-of-record rules, optionally uses supported batch requests, and records rejected or conflicting updates for review.
Martini capabilities used
- scheduled workflows
- API consumption
- batch orchestration
- data mapping
- business rules
- reconciliation
Pattern 3: Synchronize Square customers with a CRM
When to use this pattern
Use this pattern when Customer profiles need to be available in Salesforce or HubSpot for engagement, service, or lifecycle reporting. Selected customer events can reduce latency, with scheduled retrieval covering gaps.
Integration direction
Example Mapping
| Square Field | Canonical Field | Target Field |
|---|---|---|
| customer.id | customer.externalId | squareCustomerId |
| customer.given_name | customer.firstName | FirstName |
| customer.family_name | customer.lastName | LastName |
| customer.email_address | customer.email |
Martini implementation pattern
Martini consumes selected customer events or queries Customers, normalizes contact data, resolves update ownership, upserts the CRM record using the Square ID, and prevents loops or duplicates through correlation and processing state.
Martini capabilities used
- webhook consumption
- API consumption
- data mapping
- deduplication
- workflow orchestration
- error handling
Pattern 4: Reconcile invoices and subscriptions
When to use this pattern
Use this pattern when invoice, payment, and subscription status must be reflected in an ERP, billing application, or customer portal. The workflow should preserve the distinction between these related but different states.
Integration direction
Example Mapping
| Square Field | Canonical Field | Target Field |
|---|---|---|
| invoice.id | billingDocument.externalId | externalInvoiceId |
| invoice.status | billingDocument.status | invoiceStatus |
| subscription.id | subscription.externalId | subscriptionId |
| invoice.payment_requests | billingDocument.paymentSchedule | paymentSchedule |
Martini implementation pattern
Martini responds to supported invoice or subscription events and runs scheduled checks, retrieves current resources, maps state transitions, applies tenant and accounting rules, and retries delayed dependent-resource reads before reconciliation.
Martini capabilities used
- webhook consumption
- scheduled workflows
- API orchestration
- data transformation
- state management
- retry handling
Applications commonly integrated with Square
Square transaction and operational data can be coordinated with named finance, commerce, CRM, and support applications. These are integration architecture patterns rather than claims of prebuilt Square integrations.
| Application | Scenario | Direction | Martini Pattern |
|---|---|---|---|
| Salesforce | Synchronize Square Customers, Orders, Payments, and refunds with customer, sales, and service processes. | Square → Martini → Salesforce | Receive selected Square events or run scheduled API queries, retrieve related resources, normalize customer and transaction data, and upsert Salesforce objects with correlation and duplicate controls. |
| NetSuite | Post Square sales, payments, refunds, taxes, and settlement information into financial and ERP workflows. | Square → Martini → NetSuite | Use webhook-triggered and scheduled workflows to retrieve Orders and Payments, preserve minor-unit monetary precision, map accounting dimensions, and retry or reconcile failed writes. |
| Shopify | Coordinate catalog, customer, order, and inventory information across commerce channels where Square and Shopify are both used. | Shopify → Martini → Square | Define field ownership, compare Catalog objects and inventory counts, transform item variations and quantities, and use Square batch operations where supported. |
| QuickBooks Online | Transfer Square sales, fees, refunds, and payout information into accounting and reconciliation processes. | Square → Martini → QuickBooks Online | Retrieve financial resources, map taxes and payment states to accounting structures, apply idempotency keys, and maintain a reconciliation ledger for retries. |
| Xero | Synchronize Square sales, payments, refunds, and settlement data for accounting operations. | Square → Martini → Xero | Orchestrate incremental and reconciliation workflows, map Square identifiers and currencies, validate required accounting fields, and route exceptions for review. |
| HubSpot | Make Square customer and transaction information available for customer engagement and lifecycle reporting. | Square → Martini → HubSpot | Normalize Customers and selected order or payment summaries, apply ownership rules for reverse updates, and upsert HubSpot records using stable Square IDs. |
| Zendesk | Give support teams customer, order, payment, and subscription context when handling cases. | Square → Martini → Zendesk | Retrieve the latest Square resources after relevant events, map selected fields to Zendesk customer or ticket context, and handle unavailable or delayed resources with bounded retries. |
| Workday | Combine Square transaction data with enterprise finance and operational reconciliation processes. | Square → Martini → Workday | Stage normalized Square data through a Martini workflow, apply organizational and accounting mappings, and deliver validated batches with reconciliation status. |
How to build a Square integration in Martini
Objective
Establish Square access using OAuth 2.0 for seller-authorized applications or a personal access token for applicable single-account scenarios.
Instructions in Martini
- Create environment-specific Square configuration
- Store application credentials, access tokens, and refresh data as secrets
- Request only the permissions required by the integration
- Separate seller, sandbox, and production credentials
Objective
Select webhook events for timely processing and scheduled workflows for pagination, reconciliation, or changes not covered by Square event subscriptions.
Instructions in Martini
- Subscribe only to required Square event types
- Create a webhook entry point for selected notifications
- Add a scheduler for full or incremental reconciliation
- Prevent overlapping synchronization runs
Objective
Use Square REST APIs to obtain the current resource representation because webhook payloads may not contain complete data.
Instructions in Martini
- Validate webhook signatures before processing
- Retrieve related Orders, Payments, Customers, or other resources
- Follow cursor-based pagination until the cursor is absent
- Store synchronization checkpoints separately from transient cursors
Objective
Coordinate event handling, dependent API calls, transformation, downstream writes, and reconciliation as maintainable Martini workflows.
Instructions in Martini
- Route by Square event type and object
- Use correlation IDs and resource IDs throughout the workflow
- Move long-running processing behind prompt webhook acknowledgement
- Persist processing and reconciliation state where required
Objective
Transform Square JSON into canonical and target schemas while preserving financial precision and object relationships.
Instructions in Martini
- Map minor-unit amounts together with currency codes
- Retain Square IDs for Payments, Orders, Customers, Locations, and related objects
- Validate required fields and tolerate unknown additive fields
- Apply field ownership and status mapping rules
Objective
Apply idempotent downstream mutations and verify that financial and operational data remains complete.
Instructions in Martini
- Use Square idempotency support where the endpoint provides it
- Deduplicate events and downstream writes
- Retry throttling and transient failures with bounded backoff
- Compare source and target state in scheduled reconciliation
Common Square data objects used in integrations
| Object | Typical Use | Common target systems | Martini handling |
|---|---|---|---|
| Payments | Represent payment transactions, amounts, status, refunds, and payment source information. | NetSuite, QuickBooks Online, Xero, Salesforce | Retrieve after relevant events, preserve integer minor-unit amounts and currency, retain Square IDs, and apply idempotent downstream writes. |
| Orders | Represent itemized purchases with line items, taxes, discounts, fulfillment details, and totals. | NetSuite, Shopify, QuickBooks Online, Salesforce | Retrieve the current Order representation, map line and financial details, resolve related Customers and Locations, and reconcile incomplete transactions. |
| Customers | Store customer profiles, contact information, preferences, and related activity. | Salesforce, HubSpot, Zendesk, Shopify | Normalize contact fields, define ownership for reverse updates, retain Square customer IDs, and deduplicate by stable identifiers. |
| Catalog objects | Define items, item variations, categories, modifiers, taxes, discounts, and related catalog data. | Shopify, warehouse platforms, reporting systems | Use batch catalog operations where supported, map variation and modifier structures, and tolerate additive schema changes. |
| Locations | Identify physical or operational locations associated with a Square seller account. | NetSuite, reporting platforms, commerce systems | Use location IDs to partition transactions, apply location-specific mappings, and validate environment and seller boundaries. |
| Invoices | Represent customer-facing billing documents, payment schedules, and invoice state. | NetSuite, QuickBooks Online, Xero, Salesforce | Distinguish invoice, payment, and subscription status; retrieve dependent resources and reconcile delayed or repeated events. |
Authentication and security considerations
Authentication and access control
Square supports OAuth 2.0 for applications acting on behalf of sellers and personal access tokens for applicable single-account scenarios. Requests use bearer access tokens, with permissions varying by API and operation.
- Store application credentials, access tokens, and refresh data in Martini secrets or secure environment configuration.
- Request only the Square permissions required by each integration.
- Separate seller-specific credentials, sandbox resources, and production resources.
- Validate Square webhook signatures before accepting event data.
Operational considerations for Square integrations
Reliability and operations
Square integrations should account for versioned APIs, cursor-based pagination, rate limits, selective webhook coverage, eventual consistency, and duplicate delivery.
- Use bounded retries with backoff for throttling and transient failures.
- Prevent overlapping scheduled runs and persist durable synchronization checkpoints.
- Use event IDs, resource IDs, and idempotency keys to prevent duplicate writes.
- Retrieve the latest resource after a webhook when the payload is incomplete or dependent data is delayed.
- Preserve integer minor-unit amounts and currency codes for financial data.
- Test API-version changes in the Square sandbox and monitor workflow logs and reconciliation results.
Why use Martini instead of scripts or point-to-point integrations?
Maintainable integration delivery
Martini provides a workflow and API layer between Square and enterprise applications, avoiding isolated scripts and tightly coupled point-to-point logic.
- Centralize authentication, webhook validation, pagination, retries, and reconciliation.
- Reuse mappings and business rules across finance, commerce, CRM, and support flows.
- Expose controlled API façades instead of distributing Square credentials to every consumer.
- Combine event-driven processing with scheduled synchronization when Square webhook coverage is selective.
- Use structured error handling, monitoring, and deployment configuration to support production operations.
Frequently asked questions
Square can be integrated through its versioned REST APIs, selected webhook event notifications, OAuth 2.0 or personal access tokens, scheduled synchronization, and selected batch or asynchronous operations. Square APIs expose Payments, Orders, Customers, Catalog, Inventory, Locations, Invoices, subscriptions, refunds, and related resources.
Yes. Martini can consume Square REST APIs, receive and validate selected Square webhook notifications, orchestrate scheduled and event-driven workflows, transform Square JSON, and synchronize data with enterprise applications. A Martini-native Square connector was not confirmed.
No. A dedicated Square connector is not required. Martini can integrate with Square using Square REST APIs, OAuth or access-token authentication, selected webhook events, scheduled workflows, and supported batch operations.
Lonti does not charge an additional per-connector or per-vendor fee to integrate Square. The integration is subject to the provisioned capacity of the Martini environment. Separate costs may apply from Square, cloud infrastructure, or other third-party systems depending on subscriptions, usage, and deployment model.
Use Square REST APIs as the primary integration method. Use selected webhooks for timely event notification, scheduled workflows for reconciliation and uncovered changes, and batch or asynchronous operations where the specific Square API supports them. GraphQL and SOAP were not confirmed for Square.
Square provides webhook notifications for selected payment, order, customer, catalog, inventory, subscription, invoice, and merchant events. Coverage is selective rather than universal, so integrations should retrieve current resources and use scheduled reconciliation for gaps.
Square list APIs commonly use cursor-based pagination, so workflows should continue until no cursor remains and retain durable synchronization checkpoints. Webhook event IDs, resource IDs, correlation IDs, and endpoint idempotency support should be used to prevent duplicate downstream mutations.
Yes. Martini can expose a controlled API that abstracts selected Square operations, applies authentication and authorization, validates inputs, orchestrates Square REST calls, and returns a canonical response to downstream applications. This does not require a native Square connector.
Related Martini documentation
Workflows
Transformation
Connect Square with your enterprise systems
Use Martini to build secure, maintainable Square integrations across payments, orders, customers, catalog, inventory, invoices, and downstream business applications.