Square

Payments and commerce: customers, payments, orders and locations for a Square seller account.

9 actions OAuth 2 6 read2 write1 destructive Calls connect.squareup.com

Connect

TypeScript

const conn = await setu.connections.initiate({ userId: "user_1", toolkit: "square" });
console.log(conn.connectUrl); // show this to your user
await conn.waitUntilActive();

Permissions requested

Scope	Why it is requested
`MERCHANT_PROFILE_READ`	Read your business profile and locations
`CUSTOMERS_READ`	Read your customers
`CUSTOMERS_WRITE`	Create, update and delete customers
`PAYMENTS_READ`	Read payments
`ORDERS_READ`	Read orders

Actions

Create customerwritesquare.create_customerCreate a customer profile with a name, email, phone number or note. At least one identifying field is required by Square.

Needs scope: CUSTOMERS_WRITE

Input	Type		Description
`given_name`	string	Optional
`family_name`	string	Optional
`company_name`	string	Optional
`email_address`	string	Optional
`phone_number`	string	Optional	E.164 or national format
`reference_id`	string	Optional	Your own id for the customer
`note`	string	Optional	Free-text note

TypeScript

await setu.execute({
  userId: "user_1",
  action: "square.create_customer",
  input: {},
});

Delete customerdestructivesquare.delete_customerPermanently delete a customer profile by id.

Needs scope: CUSTOMERS_WRITE

Input	Type		Description
`customer_id`	string	Required	Square customer id

TypeScript

await setu.execute({
  userId: "user_1",
  action: "square.delete_customer",
  input: {
    "customer_id": "<customer_id>"
  },
  confirm: true,
});

Get customerreadsquare.get_customerGet one customer by id with contact details and notes.

Needs scope: CUSTOMERS_READ

Input	Type		Description
`customer_id`	string	Required	Square customer id

TypeScript

await setu.execute({
  userId: "user_1",
  action: "square.get_customer",
  input: {
    "customer_id": "<customer_id>"
  },
});

Get paymentreadsquare.get_paymentGet one payment by id with status, amount, order and receipt link.

Needs scope: PAYMENTS_READ

Input	Type		Description
`payment_id`	string	Required	Square payment id

TypeScript

await setu.execute({
  userId: "user_1",
  action: "square.get_payment",
  input: {
    "payment_id": "<payment_id>"
  },
});

List locationsreadsquare.list_locationsList the seller's business locations with ids, names and status. Location ids are needed to filter payments and orders.

Needs scope: MERCHANT_PROFILE_READ

No input.

TypeScript

await setu.execute({
  userId: "user_1",
  action: "square.list_locations",
  input: {},
});

List paymentsreadsquare.list_paymentsList payments, newest first, optionally for a time range (RFC 3339) and one location. Amounts are in the smallest currency unit (cents).

Needs scope: PAYMENTS_READ

Input	Type		Description
`begin_time`	string	Optional	Start of created_at range, RFC 3339
`end_time`	string	Optional	End of created_at range, RFC 3339
`location_id`	string	Optional	Limit to one location
`sort_order`	string	Optional
`limit`	integer	Optional	Up to 100
`cursor`	string	Optional	Cursor from a previous response

TypeScript

await setu.execute({
  userId: "user_1",
  action: "square.list_payments",
  input: {},
});

Search customersreadsquare.search_customersSearch customers. Pass a CustomerQuery filter, for example {filter: {email_address: {exact: "[email protected]"}}}; with no query, returns customers in the default order.

Needs scope: CUSTOMERS_READ

Input	Type		Description
`query`	object	Optional	Square CustomerQuery: {filter: {email_address\|phone_number\|reference_id\|creation_source\|created_at\|updated_at\|group_ids...}, sort: {field, order}}
`limit`	integer	Optional	1 to 100
`cursor`	string	Optional	Cursor from a previous response

TypeScript

await setu.execute({
  userId: "user_1",
  action: "square.search_customers",
  input: {},
});

Search ordersreadsquare.search_ordersSearch orders at one or more locations (up to 10), for example completed orders sorted by close time. Requires location ids; use list_locations first.

Needs scope: ORDERS_READ

Input	Type		Description
`location_ids`	array of string	Required	Location ids to search (max 10)
`query`	object	Optional	Square SearchOrdersQuery: {filter: {state_filter, date_time_filter, ...}, sort: {sort_field, sort_order}}
`limit`	integer	Optional	Results per page
`cursor`	string	Optional	Cursor from a previous response

TypeScript

await setu.execute({
  userId: "user_1",
  action: "square.search_orders",
  input: {
    "location_ids": []
  },
});

Update customerwritesquare.update_customerUpdate fields on an existing customer by id. Only the fields you pass change.

Needs scope: CUSTOMERS_WRITE

Input	Type		Description
`customer_id`	string	Required	Square customer id
`given_name`	string	Optional
`family_name`	string	Optional
`company_name`	string	Optional
`email_address`	string	Optional
`phone_number`	string	Optional	E.164 or national format
`reference_id`	string	Optional	Your own id for the customer
`note`	string	Optional	Free-text note

TypeScript

await setu.execute({
  userId: "user_1",
  action: "square.update_customer",
  input: {
    "customer_id": "<customer_id>"
  },
});