# Square

Analyze payments, orders, and retail operations

Connect Square to Scoop to analyze your retail operations, track payments and tips, understand order patterns, and compare location performance.

# AI-Assisted Setup

When connecting Square to Scoop, choose **"Guide me with AI"** for an intelligent, guided setup experience.

## Available Analysis Templates

| Template | Object | Data Mode | Best For | What You'll Analyze |
|----------|--------|-----------|----------|---------------------|
| **Sales Analytics** (Default) | payments | Snapshot | Transaction tracking | Payment amounts, tips, status |
| **Order Tracking** | orders | Snapshot | Order analysis | Totals, discounts, sources |
| **Customer Database** | customers | Sync | Customer insights | Contact info, acquisition |
| **Product Catalog** | catalog_objects | Sync | Product mix | Items, categories |
| **Location Performance** | locations | Sync | Multi-store | Store details, status |

## Example Questions You Can Answer

**Sales & Payments:**
- "What's our daily/weekly/monthly sales volume?"
- "How much are we collecting in tips?"
- "What payment methods are most popular (card, cash, wallet)?"
- "What's our failed payment rate?"
- "How do sales compare across locations?"

**Orders:**
- "What's our average order value?"
- "How much tax are we collecting?"
- "What's our discount usage?"
- "How many orders are open vs completed?"
- "Which order sources (POS, online) perform best?"

**Customers:**
- "How many customers do we have?"
- "Where are our customers coming from (first-party, third-party)?"
- "What's our customer acquisition trend?"
- "How many customers have email addresses?"

**Products:**
- "How many items are in our catalog?"
- "What's the breakdown of items vs categories?"
- "How often is our catalog updated?"

**Locations:**
- "How many locations are active?"
- "Where are our locations distributed?"
- "What time zones do we operate in?"

## Need Something Different?

If the templates above don't match your needs, select **"Something else"** and describe what you want to analyze. For example:

- "I want to compare tip percentages by location"
- "I need to track discount usage trends"
- "I want to analyze customer acquisition by source"

Scoop's AI will recommend the right configuration for your specific use case.

## Snapshotting for Transaction Analysis

Transactions are constantly happening. Configure your Payments or Orders extract as a **Snapshot** dataset to:

- Track sales growth over time
- Compare performance across periods
- Analyze trends in tips and discounts
- Monitor payment method shifts

> **Pro Tip:** Enable snapshotting for payments from day one to build the historical data needed for trend analysis and YoY comparisons.

# Connecting Square to Scoop

1. Create a new dataset in Scoop
2. Select **Square** from the application list
3. Click **Connect** to start the OAuth flow
4. Authorize Scoop to access your Square data
5. Choose your analysis template or customize
6. Save and extract data

## Required Permissions

Scoop requests read-only access to:
- Payments (transactions)
- Orders (purchases)
- Customers (buyer database)
- Items (product catalog)
- Merchant profile (locations)

> **Security Note:** Scoop only reads your Square data. We never process payments, modify orders, or change your catalog.

# What Data You Get

## Payments
Individual payment transactions.

| Field | Description |
|-------|-------------|
| Payment ID | Unique identifier (prefixed with SQ) |
| Amount | Payment amount (converted from cents) |
| Currency | Currency code |
| Tip Amount | Tip if applicable |
| Status | COMPLETED, CANCELED, FAILED |
| Source Type | CARD, CASH, WALLET, etc. |
| Location ID | Which store |
| Order ID | Associated order |
| Customer ID | Customer if known |
| Created Date | Transaction time |

## Orders
Purchases with totals and breakdowns.

| Field | Description |
|-------|-------------|
| Order ID | Unique identifier (prefixed with SQ) |
| Location ID | Which store |
| State | OPEN, COMPLETED, CANCELED |
| Total | Order total (converted from cents) |
| Tax | Tax amount |
| Discount | Discount amount |
| Tip | Tip amount |
| Source | Square POS, Online, etc. |
| Customer ID | Customer if known |
| Closed Date | When order completed |

## Customers
Customer database.

| Field | Description |
|-------|-------------|
| Customer ID | Unique identifier (prefixed with SQ) |
| First Name | Given name |
| Last Name | Family name |
| Email | Email address |
| Phone | Phone number |
| Company | Company name |
| Creation Source | How they were added |
| Created Date | When added |

## Catalog Objects
Products and categories.

| Field | Description |
|-------|-------------|
| Object ID | Unique identifier (prefixed with SQ) |
| Type | ITEM, CATEGORY, etc. |
| Item Name | Product name |
| Description | Product description |
| Deleted | Whether soft-deleted |
| Created Date | When created |

## Locations
Store locations.

| Field | Description |
|-------|-------------|
| Location ID | Unique identifier (prefixed with SQ) |
| Name | Location name |
| City | City |
| State | State/Province |
| Status | ACTIVE, INACTIVE |
| Timezone | Location timezone |

# Analysis Examples

## Sales Performance
Track your revenue:
- Daily/weekly/monthly sales totals
- Payment method distribution
- Tip trends over time
- Failed payment analysis

## Location Comparison
Compare stores:
- Sales by location
- Average order value by store
- Tip percentages by location
- Payment methods by region

## Customer Insights
Understand your buyers:
- Acquisition source breakdown
- Customer growth over time
- Contact coverage (email, phone)

# Best Practices

- **Start with Payments**: This is your core transaction data
- **Enable Snapshotting**: Build historical trend data
- **Add Location Data**: For multi-store analysis
- **Track Orders Too**: Orders provide more detail than payments alone

# Troubleshooting

## Connection Issues
- Ensure you have owner or admin access to the Square account
- Re-authorize if your OAuth token has expired (30-day expiry)
- Check that all required scopes are granted

## Missing Data
- Some data requires specific Square products (Square for Retail, etc.)
- Historical data may be limited
- Sandbox mode will show test data only

## Token Refresh
Square tokens expire after 30 days. If you see authentication errors:
- Reconnect your Square account in Scoop
- Scoop will obtain new credentials automatically

## Rate Limits
Square allows ~10 requests/second per merchant:
- Scoop automatically handles rate limiting
- Large data sets may take longer to sync
- Contact support for persistent issues