# Square

The Square integration allows you to automatically send email or SMS surveys to your customers based on Square events like payments, refunds, order fulfillments, and subscription changes.

## Step 1: Connect Your Square Account

1. In Zigpoll, go to **Settings** -> **Manage Integrations**
2. Find **Square** in the integrations list and enable it
3. Enter your Square **Access Token**
4. Press **Save**

{% hint style="info" %}
You can find your access token in the [Square Developer Dashboard](https://developer.squareup.com/apps) under your application's credentials. Use a **Production** access token for live data or a **Sandbox** token for testing.
{% endhint %}

## Step 2: Create a Survey

1. Go to your account dashboard and click **Create Survey**
2. Choose a question template or build your own slides
3. In the delivery step, select one of the Square templates:

| Template              | Square Event           | Description                                    |
| --------------------- | ---------------------- | ---------------------------------------------- |
| **Payment Completed** | `payment.completed`    | Sent after a Square payment is completed       |
| **Refund Processed**  | `refund.created`       | Sent after a refund is processed               |
| **Order Fulfilled**   | `order.fulfilled`      | Sent after an order is fulfilled               |
| **New Subscription**  | `subscription.created` | Sent when a customer starts a new subscription |

Each template supports both **Email** and **SMS** delivery. Use the dropdown on the template card to choose your preferred channel.

4. Adjust the **Trigger Settings** to control the delay before sending (e.g., send 1 hour after the event)
5. Click **Create Survey**

Zigpoll will automatically register a webhook subscription on your Square account. You can verify it in your Square Developer Dashboard under **Webhooks**.

## Step 3: Customer Targeting (Optional)

You can filter which customers receive the survey based on Square event data. Go to the **Targeting** tab on your survey and configure rules using:

* **Amount** - Filter by payment amount (e.g., only send for orders over $50)
* **Currency** - Filter by currency code (e.g., only USD transactions)
* **Note / Metadata** - Filter by order notes or metadata
* **Item IDs** - Filter by Square catalog item IDs

## Step 4: Customize Your Email

Go to the **Email** tab on your survey to customize:

* Subject line
* Header, body, and footer text
* Button text and colors
* Sender name and reply-to address

## How It Works

1. When the configured Square event fires, Square sends a webhook to Zigpoll
2. Zigpoll verifies the webhook signature and extracts the customer's email
3. After the configured delay, Zigpoll sends the survey via email or SMS
4. Responses are tracked in your Zigpoll dashboard with Square metadata (customer ID, amount, event type)

## Troubleshooting

**Survey not being sent?**

* Check that your survey is **visible** (not hidden or archived)
* Check the **Activity** tab to see if emails were queued and sent
* Verify the webhook subscription exists in your Square Developer Dashboard
* For some event types (subscriptions, certain orders), the customer email is fetched from the Square Customer object. Make sure your customers have an email address on file.

**Permission error when creating a survey?**

* Your access token may not have sufficient permissions. Generate a new token with full access from the Square Developer Dashboard.

**Webhook showing errors?**

* The webhook signing key may be out of sync. Try deleting the survey and creating a new one to re-register the webhook.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.zigpoll.com/integrations/square.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.