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

# Square Server

> Point-of-sale and business management platform for payment processing, inventory management, customer relationships, invoicing, bookings, and commerce operations

# Square Server

## Overview

The Square server provides point-of-sale and business management capabilities. Built by [Square](https://squareup.com), this server enables AI assistants to manage payment processing, inventory management, customer relationships, invoicing, bookings, and complete commerce operations through Square's comprehensive API.

## Getting Started

<Steps>
  <Step title="Connect to Square">
    Add the Square server to your Civic environment through the server directory.
  </Step>

  <Step title="Authenticate with Square">
    On the Civic Chat tab, ask to retrieve your business details on Square.
    An Authorization pop-up will appear, guiding you through the OAuth login process.
  </Step>

  <Step title="Test Connection">
    Once you have logged in, Civic will fetch your Square business information and display it.
  </Step>
</Steps>

## What You Can Do

<CardGroup cols={2}>
  <Card title="Business Management" icon="building">
    Access and manage your Square business account details and settings
  </Card>

  <Card title="Product Catalog" icon="box">
    List, create, update, and manage products in your Square catalog
  </Card>

  <Card title="Order Management" icon="receipt">
    View and manage orders, track sales, and process transactions
  </Card>

  <Card title="Sales Reports" icon="chart-line">
    Generate detailed sales reports and analyze business performance
  </Card>
</CardGroup>

## Use Cases

<AccordionGroup>
  <Accordion title="Business Operations" icon="briefcase">
    * **Account Details**: Retrieve your business information and account settings
    * **Business Insights**: Access key business metrics and performance data
    * **Location Management**: View and manage multiple business locations
    * **Configuration**: Access and update business configuration settings
  </Accordion>

  <Accordion title="Product & Catalog Management" icon="tags">
    * **Product Listing**: View all products in your Square catalog
    * **Inventory Management**: Track product inventory and availability
    * **Catalog Updates**: Add new products or update existing product details
    * **Pricing Management**: Manage product pricing and variations
  </Accordion>

  <Accordion title="Order & Transaction Management" icon="cash-register">
    * **Order Tracking**: View all orders from today or specific time periods
    * **Transaction History**: Access detailed transaction records
    * **Order Details**: Get comprehensive information about specific orders
    * **Payment Processing**: Track payment status and methods
  </Accordion>

  <Accordion title="Sales Analytics" icon="chart-bar">
    * **Sales Reports**: Generate monthly, weekly, or custom date range sales reports
    * **Performance Metrics**: Analyze sales trends and business performance
    * **Revenue Tracking**: Monitor revenue across products and time periods
    * **Business Intelligence**: Get insights into top-performing products and services
  </Accordion>
</AccordionGroup>

***

## Available Tools (3)

<AccordionGroup>
  <Accordion title="get_service_info">
    **CALL THIS FIRST** before trying to get type info. Get information about a Square API service category and its available methods.

    * **Input**: `service` - The Square API service category (e.g., 'catalog', 'payments', 'customers', 'inventory')
    * **Returns**: Available methods and service details for the specified Square API service category
    * **Use Cases**: Discover what operations are available in a service before making requests
  </Accordion>

  <Accordion title="get_type_info">
    Get request and response schema for a specific Square API method. You must call this before calling make\_api\_request.

    * **Input**:
      * `service` - The Square API service category (e.g., 'catalog', 'payments')
      * `method` - The API method to call (e.g., 'list', 'create')
    * **Returns**: Request and response schema for the specified API method
    * **Use Cases**: Understand required parameters and response format before making API calls
  </Accordion>

  <Accordion title="make_api_request">
    Unified tool for all Square API operations. Be sure to get types before calling.

    * **Input**:
      * `service` (required) - The Square API service category
      * `method` (required) - The API method to call
      * `request` (optional) - JSON object with required parameters for the method
      * `characterization` (optional) - Brief description of business intent (e.g., 'Processing customer payment', 'Adding inventory item', 'Generating sales report') - Do not pass PII

    * **Available Services** (40+ services):
      * **Payments**: applepay, cards, payments, refunds, disputes
      * **Catalog**: catalog, inventory
      * **Customers**: customers, customergroups, customersegments, customercustomattributes
      * **Orders**: orders, ordercustomattributes
      * **Invoices**: invoices
      * **Bookings**: bookings, bookingcustomattributes
      * **Locations**: locations, locationcustomattributes, devices
      * **Team**: team, labor
      * **Loyalty**: loyalty, giftcards, giftcardactivities
      * **Merchants**: merchants, merchantcustomattributes
      * **Financial**: bankaccounts, payouts, cashdrawers
      * **Integrations**: webhooksubscriptions, events, sites, snippets
      * **Commerce**: checkout, subscriptions, terminal, vendors

    * **Best Practice**: Always call get\_service\_info first, then get\_type\_info before making API requests
  </Accordion>
</AccordionGroup>

<Info>
  The Square server provides a comprehensive wrapper around Square's REST API, enabling full access to Square's business management capabilities through natural language interactions.
</Info>

***

## Configuration Requirements

### Authentication Setup

The Square server uses OAuth2 authentication with Square's API:

<AccordionGroup>
  <Accordion title="OAuth Scopes" icon="key">
    **Required Scopes for Full Functionality:**

    * **Business Information**: Read access to business account details
    * **Catalog**: Read/write access to product catalog
    * **Orders**: Read access to orders and transactions
    * **Payments**: Read access to payment information
    * **Reports**: Access to sales reports and analytics
  </Accordion>

  <Accordion title="Account Requirements" icon="building">
    * **Square Account**: Active Square business account (free or paid)
    * **API Access**: Ensure API access is enabled for your account
    * **Permissions**: Appropriate role permissions for accessing business data
    * **Rate Limits**: Be aware of API rate limits based on your account tier
  </Accordion>
</AccordionGroup>

## Best Practices

### API Usage

1. **Service Discovery**: Use `get_service_info` first to understand available operations
2. **Type Understanding**: Use `get_type_info` to understand data structures before requests
3. **Efficient Requests**: Request only the data you need to minimize API usage
4. **Error Handling**: Handle API errors gracefully and respect rate limits

### Business Operations

1. **Read First**: Fetch current state before making updates to business data
2. **Validation**: Validate data formats and requirements before creating or updating resources
3. **Testing**: Test operations with read-only requests before making changes
4. **Monitoring**: Regularly check sales reports and analytics for business insights

<Tip>
  **Pro Tip**: Start by retrieving your business details and exploring your catalog before attempting to make changes. This helps you understand your current Square setup and available data.
</Tip>

## Resources

<CardGroup cols={2}>
  <Card title="Official Square MCP Documentation" icon="book" href="https://developer.squareup.com/docs/mcp">
    Complete Square MCP server documentation
  </Card>

  <Card title="Square Developer Portal" icon="code" href="https://developer.squareup.com/">
    Square API reference and developer resources
  </Card>

  <Card title="Get Help" icon="slack" href="https://join.slack.com/t/civic-developers/shared_invite/zt-37tv9fyo7-aDT43mUjOFQwdQFmfZLTRw">
    Ask questions in our developer Slack community
  </Card>

  <Card title="Troubleshooting" icon="wrench" href="/civic/troubleshooting">
    Common Square server connection fixes
  </Card>
</CardGroup>

***

## Guardrails

This server supports all [14 universal guardrails](/civic/concepts/guardrails). Server-specific guardrails are coming soon.