Square Integration — ModuleX AI

Overview

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

Categories: Finance & Payments · Payments · Commerce · Finance · Auth: OAuth2 · Actions: 6

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

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

given_name

string

The first name associated with the customer profile

family_name

string

The last name associated with the customer profile

company_name

string

A business name associated with the customer profile

email_address

string

The email address associated with the customer profile

phone_number

string

Phone number (9-16 digits, optional + prefix and country code)

reference_id

string

An optional second ID to associate the customer with an entity in another system

note

string

A custom note associated with the customer profile

Response

{
  "$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"
}

create_invoice — Create a draft invoice for an order. You must publish (send) the invoice before Square can process it.

Parameters

location_id

string

required

The ID of the Square location

order_id

string

required

The ID of the order associated with the invoice

customer_id

string

required

The ID of the customer who will receive the invoice

due_date

string

required

The due date for the payment request, in YYYY-MM-DD format

accepted_payment_methods

array

required

Payment methods customers can use. Valid values: card, square_gift_card, bank_account, buy_now_pay_later, cash_app_pay

Response

{
  "$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"
}

create_order — Create a new order that can include information about products for purchase.

Parameters

location_id

string

required

The ID of the Square location for the order

customer_id

string

The ID of the customer associated with the order

reference_id

string

An optional second ID to associate the order with an entity in another system

line_items

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’})

Response

{
  "$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"
}

list_event_types_options — Retrieve the list of available webhook event types from Square.

Response

{
  "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"
}

list_location_options — Retrieve the list of locations for the authenticated Square account.

Response

{
  "$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"
}

send_invoice — Publish the latest version of a specified invoice so Square can process it.

Parameters

location_id

string

required

The ID of the Square location

invoice_id

string

required

The ID of the invoice to publish

Response

{
  "$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"
}

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.

Square Integration for AI Agents & Workflows

Overview

Authentication

OAuth2 Authentication

Required Credentials

OAuth Configuration

Available Actions

Parameters

Response

Parameters

Response

Parameters

Response

Response

Response

Parameters

Response

Limits & Quotas

Coinbase

Lemon Squeezy

Nasdaq Data Link

Links

​Overview

​Authentication

​OAuth2 Authentication

​Required Credentials

​OAuth Configuration

​Available Actions

​Parameters

​Response

​Parameters

​Response

​Parameters

​Response

​Response

​Response

​Parameters

​Response

​Limits & Quotas

​Related integrations

Coinbase

Lemon Squeezy

Nasdaq Data Link

​Links

Overview

Authentication

OAuth2 Authentication

Required Credentials

OAuth Configuration

Available Actions

Parameters

Response

Parameters

Response

Parameters

Response

Response

Response

Parameters

Response

Limits & Quotas

Related integrations

Links