> ## Documentation Index
> Fetch the complete documentation index at: https://docs.alpacarelay.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Square

> Connect Square to sync your customers, appointments, and purchase activity into AlpacaRelay.

Square works in the opposite direction to an ESP integration. Rather than pushing a design out, AlpacaRelay pulls your business data **in** — customers, orders, payments, refunds, and appointments — so you can see your business at a glance and email the people in it.

<Info>
  Square doesn't send your emails and doesn't receive your designs. If you're looking to push a finished design into a sending platform, see the [integrations overview](/integrations/overview).
</Info>

## What you get

<Columns cols={2}>
  <Card title="A business dashboard" icon="chart-line">
    Revenue, orders, refunds, appointments, and customer counts, read from your synced Square data.
  </Card>

  <Card title="Contacts to email" icon="users">
    Import your Square customers as AlpacaRelay contacts, then segment and send to them.
  </Card>
</Columns>

AlpacaRelay keeps its own copy of your Square data rather than calling Square each time you open a page. That's what makes the dashboard fast and keeps it working when Square is briefly unavailable.

| Synced from Square | What it's used for                               |
| ------------------ | ------------------------------------------------ |
| Customers          | Contact import, segmentation, personalization    |
| Orders             | Purchase history, top products and services      |
| Payments           | Gross and net revenue, processing fees           |
| Refunds            | Net revenue, refund reporting                    |
| Appointments       | Upcoming bookings — requires Square Appointments |

## What you need

* A Square account with a seller you can authorize.
* **Square Appointments activated**, if you want appointment data. It's a separate product in your Square dashboard; without it, everything else still syncs.

## Connect Square

<Steps>
  <Step title="Open Connected apps">
    Go to **Settings** → **Connected apps**, then click **Connect app** and choose **Square**.
  </Step>

  <Step title="Sign in to Square">
    Square's authorization page opens. Sign in as the seller whose data you want to sync.
  </Step>

  <Step title="Accept every requested permission">
    Approve all of them. AlpacaRelay requests read-only access — it never modifies anything in your Square account, and never charges or refunds.

    <Warning>
      Declining any permission leaves the connection in a state that can't sync. Square grants permissions once, at the moment you authorize, so a partial approval can only be fixed by reconnecting and accepting everything.
    </Warning>
  </Step>

  <Step title="Wait for the first sync">
    Connecting automatically starts a **12-month backfill** of your history. Larger accounts take longer — the connection shows **Syncing your Square data…** until it finishes.
  </Step>
</Steps>

## Connection states

Square reports more states than a simple connected/disconnected, because the fixes differ:

| State                                     | What it means                        | What to do                               |
| ----------------------------------------- | ------------------------------------ | ---------------------------------------- |
| **Connected**                             | Syncing normally                     | Nothing                                  |
| **Syncing your Square data…**             | First sync, or a sync in progress    | Wait — the dashboard fills in as it goes |
| **Authorization is no longer valid**      | Access was revoked or expired        | **Reconnect**                            |
| **Missing permissions**                   | You connected but declined something | **Reconnect** and accept all permissions |
| **The last sync failed**                  | A transient failure                  | Nothing — it retries automatically       |
| **Automatic synchronization has stopped** | Someone disconnected it              | **Connect** again                        |

<Note>
  If we add a new Square permission in future, you'll be asked to reconnect. Square can't add a permission to an authorization that already exists, so this is unavoidable — we batch permission changes to keep it rare.
</Note>

## View your business data

The **Business** section shows what's been synced.

<Warning>
  Business isn't in the sidebar yet. Reach it by adding `?section=business` to your workspace URL — for example `app.alpacarelay.com/app/your-workspace?section=business`.
</Warning>

Six tiles summarize the selected date range: **Gross revenue**, **Net revenue**, **Refunds**, **Orders**, **Appointments**, and **Customers**. Below them, tabs list the underlying records: **Payments**, **Orders**, **Appointments**, **Refunds**, and **Customers**.

A few things worth knowing before you read a number as gospel:

<AccordionGroup>
  <Accordion title="Tiles count completed activity only">
    An open order, or a payment that's authorized but not captured, isn't revenue yet and isn't counted. This is usually why a tile reads lower than your Square dashboard for the same day.
  </Accordion>

  <Accordion title="Processing fees appear only once a payment settles">
    Square doesn't report the fee until then. Rather than guess at it, AlpacaRelay tells you fees are still pending — so **Net revenue** on very recent payments is incomplete rather than wrong.
  </Accordion>

  <Accordion title="The date range applies to some tabs, not all">
    Payments, Orders, and Refunds are filtered by the selected range, which defaults to the last 30 days. Customers isn't filtered — you see everyone synced.
  </Accordion>

  <Accordion title="Appointments shows upcoming bookings only">
    Past appointments aren't browsable yet. A business with no future bookings sees an empty tab even when it has history.
  </Accordion>

  <Accordion title="Multi-location businesses are fully covered">
    Every location is synced and its records carry the location they belong to. Revenue figures cover all of them, not just your main location.
  </Accordion>
</AccordionGroup>

## Keep your data fresh

Click **Sync now** in the Business section to pull recent changes. That catches anything created or updated in roughly the **last four days** — deliberately wider than it sounds, because Square can take up to 72 hours to receive orders taken on a point-of-sale terminal that was offline.

<Warning>
  **There's no scheduled sync yet.** After the initial backfill, your data stays as it is until someone clicks **Sync now**. If a dashboard number looks stale, that's the first thing to check.
</Warning>

The 12-month backfill runs only when you first connect. To re-run a full history sync, disconnect and reconnect.

## Import Square customers as contacts

This is what turns Square data into email you can actually send.

<Steps>
  <Step title="Go to Contacts">
    Open **Audience** → **Contacts** in the sidebar.
  </Step>

  <Step title="Import from Square">
    Choose Square as the import source. Your customers are read live from Square, so you don't need to sync first.
  </Step>

  <Step title="Review the result">
    You'll see how many customers were scanned, how many became contacts, and how many were skipped.
  </Step>
</Steps>

Imports bring across **email address, first name, and last name**. Up to 10,000 customers are imported at a time.

Customers are skipped when they have **no email address**, or an address that isn't valid — Square accepts customer records without one, but there's nothing to send to. Skipped records are counted so the numbers reconcile.

<Warning>
  **Check consent before you send.** Square only records whether someone has *unsubscribed* — it has no positive opt-in signal — and imported contacts arrive with consent marked unknown rather than opted-in. Unknown is not consent. If you have people in Square who unsubscribed there, review your contacts before sending a marketing campaign to a freshly imported list.
</Warning>

Once imported, Square customers behave like any other contact: build a segment from them, and send.

## Appointments and Square Appointments

Appointment data needs **Square Appointments** switched on in your Square dashboard. It's a separate Square product, not a permission.

If it isn't active, Square refuses appointment requests and AlpacaRelay records a warning against that one data type — the sync still completes and everything else still syncs. You'll see a note above the Appointments tab explaining it.

<Tip>
  This case looks identical to an expired authorization from Square's side. If you see a warning about appointments specifically while payments and customers sync fine, the fix is in your Square dashboard, not in reconnecting.
</Tip>

## Sandbox and production are separate

If you've been testing with a Square sandbox seller, none of that data exists in your real Square account. They're entirely separate systems with separate merchants and separate records — connecting production gives you a fresh backfill of your real history.

## Privacy

Synced customer records include personal data: email addresses, phone numbers, postal addresses, birthdays, and any notes on the customer in Square. Treat the Business section accordingly, and remember that importing customers as contacts copies their email addresses into AlpacaRelay.

AlpacaRelay never stores your Square access tokens. Authorization is held by our integration provider, and access is read-only throughout.

## Troubleshooting

<AccordionGroup>
  <Accordion title="The dashboard is empty right after connecting">
    The first sync walks 12 months of history and takes time on a busy account. The connection shows a syncing state while it runs.
  </Accordion>

  <Accordion title="The dashboard is still empty later">
    Check the date range first — Payments, Orders, and Refunds default to the last 30 days, and a quiet month looks like a broken integration. Then check the Customers tab, which isn't date-filtered: if customers are there, syncing works and the range is the issue.
  </Accordion>

  <Accordion title="Numbers are lower than my Square dashboard">
    Tiles count completed activity only, and processing fees on unsettled payments are still pending. Both make recent figures conservative rather than wrong.
  </Accordion>

  <Accordion title="Appointments is empty but I take bookings">
    Either Square Appointments isn't active, or you have no upcoming appointments — the tab is forward-looking and doesn't show past bookings.
  </Accordion>

  <Accordion title="I'm asked to reconnect repeatedly">
    A missing-permission state can't be cleared by reconnecting alone. Reconnect and make sure you accept every requested permission on Square's page.
  </Accordion>

  <Accordion title="Data hasn't changed in days">
    Expected — there's no scheduled sync yet. Click **Sync now**.
  </Accordion>
</AccordionGroup>