Square Integration

This article will walk you through the process of connecting your Square account to your Humanitru database and explain how transaction and constituent data syncs between the two systems.

Before You Start

• You'll need an active Square account.
• The following steps can only be completed by users with Admin permissions in Humanitru.
• The Square integration must be enabled for your organization before it can be connected.

Note: If you do not see the option to connect Square in your database, please contact your Customer Success Manager.

Overview

Your database can be configured to automatically integrate with your Square account, importing transaction and constituent information on a nightly basis.

This integration helps eliminate manual imports by automatically bringing completed Square transactions into Humanitru and associating them with the appropriate constituent records.

Setup

To connect your Square account to Humanitru:

1. Log in to your database.
2. Click Settings from the left-hand navigation menu.
3. Scroll to the Integrations section.
4. Locate Square and click Connect.
5. Sign in to your Square account when prompted.
6. Review the requested permissions and authorize Humanitru to access your Square data.
7. Once authorization is complete, you'll be returned to Humanitru and your connection status will display as Connected.

How Authentication Works

Humanitru uses Square's secure OAuth authentication process.

During setup:

1. You'll be redirected to Square's login page.
2. You'll sign in and authorize Humanitru.
3. Square will securely provide Humanitru with authorization credentials.
4. Humanitru will begin syncing eligible transaction data during the nightly sync.

What We Push Into Square

This integration is pull-only.

Your database does not send any data back to Square. No constituent, donation, campaign, or transaction information is pushed from Humanitru into your Square account.

Initial Sync

When the integration runs for the first time, Humanitru imports completed transactions from the previous 60 days.

If you need to import transactions older than 60 days, please contact your Customer Success Manager.

Ongoing Syncs

After the initial import, Humanitru automatically retrieves newly completed transactions during each nightly sync.

Transactions That Are Not Imported

The integration does not import:

• Orders without customer information
• Authorization-only transactions
• Voided authorizations
• Failed or unsettled payments
• Transfer and payout activity
• Catalog updates
• Balance adjustments
• Refunds or partial refunds

Only transactions associated with completed orders are eligible for import.

Recurring Transactions

Recurring subscription payments are imported as separate transactions each time a charge is successfully processed.

Constituent Mapping

The following Square fields are used to create constituent records in the database. 

Square Field	Humanitru Field
Email Address	Email
Given Name	Email Salutation
Given Name + Family Name	Name
Phone Number	Phone
Address (line1, line2, city, state, postal_code, country)	Address

Note: The fields are only updated if the constituent data is blank.

Constituent Matching

When importing transactions, Humanitru first attempts to locate an existing constituent using:

1. Email Address
2. Name

If no match is found, a new constituent record is created.

Important Note About Existing Data

To protect your data, Humanitru only fills in blank constituent fields.

Existing constituent information will never be overwritten by Square data during future syncs.

For example, if a constituent record already contains an address, Humanitru will not replace that address with updated information from Square.

Transaction Mapping

Imported Square transactions are stored as Actions within Humanitru.

Information imported may include:

Square Field	Stored In Humanitru
Order ID	Action Notes
Transaction Date	Action Date
Transaction Amount	Action Notes
Purchased Items	Action Notes
Product Information	Campaign Assignment (when applicable)

Campaign Mapping

When a transaction includes a Square catalog item, Humanitru can automatically create and associate campaigns based on the purchased item.

For products with variations, Humanitru uses the variation name when available.

Example:

Product: Annual Membership

Variations:

• Individual
• Family

In this scenario, Humanitru would create campaign associations using:

• Individual
• Family

rather than the parent item name.

Custom or free-form line items that are not connected to a Square catalog item are not used for campaign creation.

Tip: Action records imported from Square can be converted into Donations, Memberships, or other action types using Smart Automations.

Sync Details

Timing

Frequency: Nightly

The Square integration syncs once each night and does not update in real time.

Action Matching

Each imported transaction includes the Square Order ID.

This unique identifier helps prevent duplicate transactions from being created, even when sync windows overlap.

Best Practices

To get the most value from the Square integration:

Collect Email Addresses at Checkout

Email addresses significantly improve constituent matching and help ensure transactions are connected to the correct supporter record.

Use Consistent Product Catalogs

Maintaining a structured Square catalog helps create cleaner campaign reporting and more meaningful segmentation inside Humanitru.

Create Dedicated Donation Products

If you process donations through Square, consider using dedicated donation products or catalog items to simplify reporting and automation workflows.

Frequently Asked Questions

Does the integration sync in real time?

No. The Square integration syncs nightly.

Will refunds appear in Humanitru?

Not currently. Refunds and partial refunds are not imported.

What happens if a transaction has no customer information?

Transactions without associated customer records are skipped during the import process.

Can Humanitru update constituent information from Square?

No. Humanitru only fills blank constituent fields and will never overwrite existing constituent data.

Can imported transactions be converted into Donations or Memberships?

Yes. Smart Automations can be used to convert imported Square actions into other action types within Humanitru.

Any additional questions?

Ask your Customer Success Manager.