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

# Square Integration for AI Agents & Workflows

> Payment processing, commerce, and business management platform

{/* Self-hosted logo — build-time vendored from modulex.json / Iconify (see scripts/lib/logo.js). */}

<img src="https://mintcdn.com/modulexaillc/df8MOr-hXotYLTh5/logos/square.svg?fit=max&auto=format&n=df8MOr-hXotYLTh5&q=85&s=629c57bfe1b4854c3eca108d81069c0d" alt="Square logo" width="72" height="72" data-path="logos/square.svg" />

## Overview

Add **Square** to any ModuleX agent or workflow. Payment processing, commerce, and business management via the Square Connect API (`connect.squareup.com/v2`).

<Info>
  **Categories**: Finance & Payments · Payments · Commerce · Finance · **Auth**: OAuth2 · **Actions**: 6
</Info>

## Authentication

### OAuth2 Authentication

Connect using Square OAuth (recommended)

#### Required Credentials

| Field         | Description                    | Required | Format                                            |
| ------------- | ------------------------------ | -------- | ------------------------------------------------- |
| Client ID     | Square OAuth App Client ID     | Yes      | `sq0idp-xxxxxxxxxxxxxxxx`                         |
| Client Secret | Square OAuth App Client Secret | Yes      | `sq0csp-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx` |

#### OAuth Configuration

* **Authorization URL**: `https://connect.squareup.com/oauth2/authorize`
* **Token URL**: `https://connect.squareup.com/oauth2/token`
* **Scopes**: `CUSTOMERS_WRITE`, `CUSTOMERS_READ`, `ORDERS_WRITE`, `ORDERS_READ`, `INVOICES_WRITE`, `INVOICES_READ`, `MERCHANT_PROFILE_READ`

## Available Actions

<AccordionGroup>
  <Accordion title="create_customer — Create a new customer for a business. Must provide at least one of: given_name, family_name, company_name, email_address, or phone_number.">
    ### Parameters

    <ResponseField name="given_name" type="string">
      The first name associated with the customer profile
    </ResponseField>

    <ResponseField name="family_name" type="string">
      The last name associated with the customer profile
    </ResponseField>

    <ResponseField name="company_name" type="string">
      A business name associated with the customer profile
    </ResponseField>

    <ResponseField name="email_address" type="string">
      The email address associated with the customer profile
    </ResponseField>

    <ResponseField name="phone_number" type="string">
      Phone number (9-16 digits, optional + prefix and country code)
    </ResponseField>

    <ResponseField name="reference_id" type="string">
      An optional second ID to associate the customer with an entity in another system
    </ResponseField>

    <ResponseField name="note" type="string">
      A custom note associated with the customer profile
    </ResponseField>

    ### Response

    ```json theme={null}
    {
      "$defs": {
        "CustomerResource": {
          "additionalProperties": false,
          "properties": {
            "id": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "default": null,
              "title": "Id"
            },
            "given_name": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "default": null,
              "title": "Given Name"
            },
            "family_name": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "default": null,
              "title": "Family Name"
            },
            "company_name": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "default": null,
              "title": "Company Name"
            },
            "email_address": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "default": null,
              "title": "Email Address"
            },
            "phone_number": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "default": null,
              "title": "Phone Number"
            },
            "reference_id": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "default": null,
              "title": "Reference Id"
            },
            "note": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "default": null,
              "title": "Note"
            },
            "created_at": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "default": null,
              "title": "Created At"
            },
            "updated_at": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "default": null,
              "title": "Updated At"
            }
          },
          "title": "CustomerResource",
          "type": "object"
        }
      },
      "additionalProperties": false,
      "properties": {
        "success": {
          "title": "Success",
          "type": "boolean"
        },
        "error": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Error"
        },
        "customer": {
          "anyOf": [
            {
              "$ref": "#/$defs/CustomerResource"
            },
            {
              "type": "null"
            }
          ],
          "default": null
        }
      },
      "required": [
        "success"
      ],
      "title": "CreateCustomerOutput",
      "type": "object"
    }
    ```
  </Accordion>

  <Accordion title="create_invoice — Create a draft invoice for an order. You must publish (send) the invoice before Square can process it.">
    ### Parameters

    <ResponseField name="location_id" type="string" required>
      The ID of the Square location
    </ResponseField>

    <ResponseField name="order_id" type="string" required>
      The ID of the order associated with the invoice
    </ResponseField>

    <ResponseField name="customer_id" type="string" required>
      The ID of the customer who will receive the invoice
    </ResponseField>

    <ResponseField name="due_date" type="string" required>
      The due date for the payment request, in YYYY-MM-DD format
    </ResponseField>

    <ResponseField name="accepted_payment_methods" type="array" required>
      Payment methods customers can use. Valid values: card, square\_gift\_card, bank\_account, buy\_now\_pay\_later, cash\_app\_pay
    </ResponseField>

    ### Response

    ```json theme={null}
    {
      "$defs": {
        "InvoiceResource": {
          "additionalProperties": false,
          "properties": {
            "id": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "default": null,
              "title": "Id"
            },
            "version": {
              "anyOf": [
                {
                  "type": "integer"
                },
                {
                  "type": "null"
                }
              ],
              "default": null,
              "title": "Version"
            },
            "location_id": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "default": null,
              "title": "Location Id"
            },
            "order_id": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "default": null,
              "title": "Order Id"
            },
            "status": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "default": null,
              "title": "Status"
            },
            "created_at": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "default": null,
              "title": "Created At"
            },
            "updated_at": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "default": null,
              "title": "Updated At"
            }
          },
          "title": "InvoiceResource",
          "type": "object"
        }
      },
      "additionalProperties": false,
      "properties": {
        "success": {
          "title": "Success",
          "type": "boolean"
        },
        "error": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Error"
        },
        "invoice": {
          "anyOf": [
            {
              "$ref": "#/$defs/InvoiceResource"
            },
            {
              "type": "null"
            }
          ],
          "default": null
        }
      },
      "required": [
        "success"
      ],
      "title": "CreateInvoiceOutput",
      "type": "object"
    }
    ```
  </Accordion>

  <Accordion title="create_order — Create a new order that can include information about products for purchase.">
    ### Parameters

    <ResponseField name="location_id" type="string" required>
      The ID of the Square location for the order
    </ResponseField>

    <ResponseField name="customer_id" type="string">
      The ID of the customer associated with the order
    </ResponseField>

    <ResponseField name="reference_id" type="string">
      An optional second ID to associate the order with an entity in another system
    </ResponseField>

    <ResponseField name="line_items" type="object">
      Line items for the order. Array of objects, each with: quantity (string), name (string), base\_price\_money (\{amount: int in cents, currency: string e.g. 'USD'})
    </ResponseField>

    ### Response

    ```json theme={null}
    {
      "$defs": {
        "OrderResource": {
          "additionalProperties": false,
          "properties": {
            "id": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "default": null,
              "title": "Id"
            },
            "location_id": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "default": null,
              "title": "Location Id"
            },
            "reference_id": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "default": null,
              "title": "Reference Id"
            },
            "state": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "default": null,
              "title": "State"
            },
            "created_at": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "default": null,
              "title": "Created At"
            },
            "updated_at": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "default": null,
              "title": "Updated At"
            }
          },
          "title": "OrderResource",
          "type": "object"
        }
      },
      "additionalProperties": false,
      "properties": {
        "success": {
          "title": "Success",
          "type": "boolean"
        },
        "error": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Error"
        },
        "order": {
          "anyOf": [
            {
              "$ref": "#/$defs/OrderResource"
            },
            {
              "type": "null"
            }
          ],
          "default": null
        }
      },
      "required": [
        "success"
      ],
      "title": "CreateOrderOutput",
      "type": "object"
    }
    ```
  </Accordion>

  <Accordion title="list_event_types_options — Retrieve the list of available webhook event types from Square.">
    ### Response

    ```json theme={null}
    {
      "additionalProperties": false,
      "properties": {
        "success": {
          "title": "Success",
          "type": "boolean"
        },
        "error": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Error"
        },
        "event_types": {
          "items": {
            "type": "string"
          },
          "title": "Event Types",
          "type": "array"
        }
      },
      "required": [
        "success"
      ],
      "title": "ListEventTypesOptionsOutput",
      "type": "object"
    }
    ```
  </Accordion>

  <Accordion title="list_location_options — Retrieve the list of locations for the authenticated Square account.">
    ### Response

    ```json theme={null}
    {
      "$defs": {
        "LocationOption": {
          "additionalProperties": false,
          "properties": {
            "id": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "default": null,
              "title": "Id"
            },
            "name": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "default": null,
              "title": "Name"
            },
            "status": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "default": null,
              "title": "Status"
            }
          },
          "title": "LocationOption",
          "type": "object"
        }
      },
      "additionalProperties": false,
      "properties": {
        "success": {
          "title": "Success",
          "type": "boolean"
        },
        "error": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Error"
        },
        "locations": {
          "items": {
            "$ref": "#/$defs/LocationOption"
          },
          "title": "Locations",
          "type": "array"
        }
      },
      "required": [
        "success"
      ],
      "title": "ListLocationOptionsOutput",
      "type": "object"
    }
    ```
  </Accordion>

  <Accordion title="send_invoice — Publish the latest version of a specified invoice so Square can process it.">
    ### Parameters

    <ResponseField name="location_id" type="string" required>
      The ID of the Square location
    </ResponseField>

    <ResponseField name="invoice_id" type="string" required>
      The ID of the invoice to publish
    </ResponseField>

    ### Response

    ```json theme={null}
    {
      "$defs": {
        "InvoiceResource": {
          "additionalProperties": false,
          "properties": {
            "id": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "default": null,
              "title": "Id"
            },
            "version": {
              "anyOf": [
                {
                  "type": "integer"
                },
                {
                  "type": "null"
                }
              ],
              "default": null,
              "title": "Version"
            },
            "location_id": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "default": null,
              "title": "Location Id"
            },
            "order_id": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "default": null,
              "title": "Order Id"
            },
            "status": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "default": null,
              "title": "Status"
            },
            "created_at": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "default": null,
              "title": "Created At"
            },
            "updated_at": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "default": null,
              "title": "Updated At"
            }
          },
          "title": "InvoiceResource",
          "type": "object"
        }
      },
      "additionalProperties": false,
      "properties": {
        "success": {
          "title": "Success",
          "type": "boolean"
        },
        "error": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Error"
        },
        "invoice": {
          "anyOf": [
            {
              "$ref": "#/$defs/InvoiceResource"
            },
            {
              "type": "null"
            }
          ],
          "default": null
        }
      },
      "required": [
        "success"
      ],
      "title": "SendInvoiceOutput",
      "type": "object"
    }
    ```
  </Accordion>
</AccordionGroup>

## Limits & Quotas

* **Rate limits**: Square enforces per-endpoint rate limits, typically 30-100 requests per 30 seconds depending on the endpoint category.
* **Sandbox**: Square provides a sandbox environment for testing at `connect.squareupsandbox.com`.
* **Error model**: Non-2xx responses and timeouts are caught and returned as `success=False` + `error` rather than raising. Square errors include a JSON `errors[]` array with `category`, `code`, and `detail` fields.

## Related integrations

<CardGroup cols={3}>
  <Card title="Coinbase" href="/integrations/tools/coinbase" />

  <Card title="Lemon Squeezy" href="/integrations/tools/lemon-squeezy" />

  <Card title="Nasdaq Data Link" href="/integrations/tools/nasdaq" />
</CardGroup>

## Links

* [Square](https://squareup.com)