Overview
Square is a POS + payments platform popular with brick-and-mortar retailers. The Automize Square connector covers customers, catalog (products), orders, payments, and invoices.
- Regions: US, CA, UK, AU, JP, IE, FR, ES. Different sandbox + live URLs per region – connector picks based on the account's home country.
- Plans: Free POS. Paid feature add-ons (Square for Restaurants, Retail, Appointments). API access on all plans.
Setting up the connection
Auth type: OAuth 2.0 (Authorization Code).
- Sign in to developer.squareup.com → Create Application.
- Set OAuth Redirect URL to the one in the Automize Square connector dialog.
- Set scopes: MERCHANT_PROFILE_READ, CUSTOMERS_READ, CUSTOMERS_WRITE, ITEMS_READ, ITEMS_WRITE, ORDERS_READ, ORDERS_WRITE, PAYMENTS_READ, PAYMENTS_WRITE, INVOICES_READ, INVOICES_WRITE.
- Copy Application ID + Application Secret.
- In Automize, open Settings → Connectors → Square → Add connection. Choose Sandbox or Production, paste credentials, connect.
Find your credentials at https://developer.squareup.com/apps.
Rate limits
Square enforces per-merchant rate limits (~700/min on most endpoints). Connector retries 429 with Retry-After.
Data model
Square primitives:
Merchant ─┬─ Locations (physical stores)
│ ├─ Orders ─── Line Items ─── Catalog Items
│ ├─ Payments
│ └─ Invoices
├─ Customers
└─ Catalog (Items + Variations + Categories + Modifiers)Available operations
11 operations available. Click any row to jump to its detail.
| Operation | Category | What it does |
|---|---|---|
| Create Customer | General | Create a new customer |
| Create Invoice | General | Create a new invoice |
| Create Order | General | Create a new order |
| Create Payment | General | Create a new payment |
| Get Payment | General | Get payment details by ID |
| List Catalog | General | List catalog objects |
| List Customers | General | List all customers |
| List Invoices | General | List invoices for a location |
| List Orders | General | Search orders |
| List Payments | General | List all payments |
| Search Catalog | General | Search catalog objects |
Operations
Create Customer
Create a new customer
| Parameter | Required | Type | Description |
|---|---|---|---|
Given Name given_name | Yes | text | |
Family Name family_name | Yes | text | |
Email Address email_address | Yes | text | |
Phone Number phone_number | Yes | text |
Tips
- given_name + family_name + email_address + phone_number.
- Square dedupes by email – duplicate emails return existing customer.
Create Invoice
Create a new invoice
| Parameter | Required | Type | Description |
|---|---|---|---|
Invoice invoice | Yes | text | |
Idempotency Key idempotency_key | Yes | text |
Tips
- invoice: {order_id, primary_recipient:{customer_id}, payment_requests:[{request_type:'BALANCE'}], delivery_method:'EMAIL'}.
- idempotency_key required.
Create Order
Create a new order
| Parameter | Required | Type | Description |
|---|---|---|---|
Order order | Yes | text |
Tips
- order: {location_id, line_items:[{catalog_object_id, quantity}], state}.
- Returns order_id used for Create Payment.
Create Payment
Create a new payment
| Parameter | Required | Type | Description |
|---|---|---|---|
Source Id source_id | Yes | text | |
Amount Money amount_money | Yes | text | |
Idempotency Key idempotency_key | Yes | text |
Tips
- source_id: card nonce from Web Payments SDK OR saved card_id.
- amount_money: {amount: 1000, currency: 'USD'} – amount in smallest unit (cents).
- idempotency_key: REQUIRED – UUID for retry safety.
Errors
INVALID_PAYMENT– Card declined / invalid source. Check source_id is fresh.
Get Payment
Get payment details by ID
| Parameter | Required | Type | Description |
|---|---|---|---|
Payment Id payment_id | Yes | text |
Tips
- Returns payment + status (APPROVED, COMPLETED, CANCELED, FAILED).
List Catalog
List catalog objects
No input parameters.
Tips
- Filter by types (ITEM, ITEM_VARIATION, CATEGORY, MODIFIER, TAX, DISCOUNT).
List Customers
List all customers
No input parameters.
Tips
- Page via cursor. Filter by sort_field, sort_order.
List Invoices
List invoices for a location
No input parameters.
Tips
- Filter by location_id, customer_id, status.
List Orders
Search orders
| Parameter | Required | Type | Description |
|---|---|---|---|
Location Ids location_ids | Yes | text | |
Query query | Yes | text |
Tips
- location_ids[] required + query filters (state, created_at, total_money range).
List Payments
List all payments
No input parameters.
Tips
- Filter by begin_time, end_time, sort_order, location_id.
Search Catalog
Search catalog objects
| Parameter | Required | Type | Description |
|---|---|---|---|
Object Types object_types | Yes | text | |
Query query | Yes | text |
Tips
- Body: {object_types:['ITEM'], query: {prefix_query: {attribute_name:'name', attribute_prefix:'pizza'}}}.
FAQ
- Sandbox vs production?
- Different OAuth URLs + credentials. Sandbox uses test cards (4111 1111 1111 1111). Set environment on connection.
- Why is my payment failing with 'idempotency key reused'?
- Square requires unique idempotency_key per logical operation. Generate a new UUID per call (NOT per retry – retries reuse the same key intentionally for idempotency).
- Multi-location stores?
- One Square account can have multiple locations. Pass location_id per operation. List Locations (not exposed here) returns all available.
- Web Payments SDK – what's that?
- Client-side card tokenisation. Browser → Square gets a card nonce → server passes nonce as source_id to Create Payment. Avoids handling card numbers server-side (PCI scope).