Square Integration

This article will walk you through the process of connecting your Square account to your Alpine 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 Alpine.
• 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 Alpine database, please contact your Customer Success Manager.

Overview

Your Alpine 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 Alpine and associating them with the appropriate constituent records.

Setup

To connect your Square account to Alpine:

1. Log in to your Alpine 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 Alpine 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. Alpine will begin syncing eligible transaction data automatically.

What We Push Into Square

This integration is pull-only.

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

What We Pull From Square

Each night, Alpine imports eligible completed transactions from Square along with associated customer information.

Imported data may include:

• Customer name
• Email address
• Phone number
• Mailing address
• Transaction details
• Purchased items

Initial Sync

When the integration runs for the first time, Alpine 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, Alpine 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 or update constituent records in Alpine.

Square Field	Alpine Field
Email Address	Email
Given Name	Email Salutation
Given Name + Family Name	Name
Phone Number	Phone
Address Line 1	Address Line 1
Address Line 2	Address Line 2
City	City
State	State
ZIP/Postal Code	ZIP Code

Constituent Matching

When importing transactions, Alpine 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, Alpine 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, Alpine will not replace that address with updated information from Square.

Transaction Mapping

Imported Square transactions are stored as Actions within Alpine.

Information imported may include:

Square Field	Stored In Alpine
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, Alpine can automatically create and associate campaigns based on the purchased item.

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

Example:

Product: Annual Membership

Variations:

• Individual
• Family

In this scenario, Alpine 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 Alpine.

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 Alpine?

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 Alpine update constituent information from Square?

No. Alpine 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 Alpine.

Any additional questions?

Ask your Customer Success Manager.