Square setup guide

Agents read payments, invoices and accounts. Anything that moves money is tier 4: a person always approves it.

Ways to connect

Company admins connect apps, on the Integrations page in Everdeck: open Square, choose one of the ways below, follow its steps and fill in its fields. Everdeck checks what you enter before it saves anything, and asks you to confirm it’s you (your second factor) before you type any secret. How connecting works.

Square can be connected 2 ways. Where there’s a key or token to paste, that’s usually the quickest.

Personal access token

API key.

1. Sign in to the Square Developer Console (https://developer.squareup.com/apps) with your Square account and create an application (for example Everdeck), or open an existing one.
2. Select Credentials in the left pane, switch to Production and click Show next to the access token. Copy it into the form. (The Sandbox token only works with the Sandbox environment.) This token has full access to your Square account, so keep it in Everdeck only.
3. You don't need to add a webhook subscription: live updates from Square (starting work when a payment, refund, invoice or dispute changes) aren't available yet, so leave the webhook signature key empty.

Field	What to enter
Square environment	Choice: Production, Sandbox.
Access token	A secret: Everdeck saves it encrypted and never shows it again. Where to find it.
Webhook signature key (optional, not used yet)	A secret: Everdeck saves it encrypted and never shows it again. Live updates from Square aren't available yet; leave this empty.

Disconnecting deletes the credentials Everdeck saved, but Everdeck can't revoke them: the key, token or password itself keeps working at Square until you delete or rotate it there.

Your Square app (OAuth)

Your OAuth app.

This way signs in with an OAuth app you create for Square, as its steps describe: Everdeck never uses an app of its own. Register this redirect URI with your app:

https://everdeck.io/api/oauth/callback

Then save the app’s client ID and secret in Everdeck, on the connect page or under OAuth apps, and sign in.

1. In the Square Developer Console (https://developer.squareup.com/apps) create or open an application.
2. Select OAuth in the left pane, switch to Production and set the Redirect URL to https://everdeck.io/api/oauth/callback. Save.
3. Copy the Application ID and Application secret from the same page into the form.
4. Click Connect and sign in as the Square account owner (or a team member allowed to authorize apps), then allow the listed permissions.
5. You don't need to add a webhook subscription: live updates from Square aren't available yet, so leave the webhook signature key empty.

Field	What to enter
Webhook signature key (optional, not used yet)	A secret: Everdeck saves it encrypted and never shows it again. Live updates from Square aren't available yet; leave this empty.

The scopes Everdeck asks for:

• MERCHANT_PROFILE_READ
• CUSTOMERS_READ
• CUSTOMERS_WRITE
• PAYMENTS_READ
• PAYMENTS_WRITE
• ORDERS_READ
• ORDERS_WRITE
• INVOICES_READ
• INVOICES_WRITE
• ITEMS_READ
• DISPUTES_READ

When you disconnect, Everdeck asks Square to revoke the sign-in, then deletes the tokens it saved.

What agents can do

An agent uses an action only when its charter grants it, on the agent’s Tools tab, where you choose whether each one runs by itself (Auto), asks first or never runs. Each action has a risk tier: tier 3 actions, which customers or the public see, ask first unless you choose otherwise, and tier 4 actions (money, deleting things, access) always need a person. How tools and tiers work.

Actions marked Reads outside content return things people outside your company may have written. Agents treat what they read as information, never as instructions, and their riskier actions later in the same session need approval.

• List locationsTier 0 · ReadReads outside contentsquare_list_locations

  List the business's locations with id, name, status, currency and time zone. Orders, invoices and payment lists are per location.

• Search customersTier 0 · ReadReads outside contentsquare_search_customers

  Find customer profiles by email (fuzzy), phone (fuzzy), your reference id (exact) or creation time. With no filter, returns all customers alphabetically. Up to 100 per page.

• Create a customerTier 2 · ReversibleReads outside contentsquare_create_customer

  Add a customer profile. Square does not block duplicates, so search by email first. Provide at least one of given_name, family_name, company_name, email or phone.

• Update a customerTier 2 · ReversibleReads outside contentsquare_update_customer

  Change a customer's name, email, phone, reference id, note or address. Send only what changes.

• List paymentsTier 0 · ReadReads outside contentsquare_list_payments

  List card and other payments, newest first, for a time range (default the last year) at one location (default the main one). Filter by exact total (smallest currency unit), card last 4 or brand. Use the id with refund_payment.

• Refund a paymentTier 4 · Money or irreversibleReads outside contentsquare_refund_payment

  Refund all or part of a completed payment back to the original card or method. amount is in the smallest currency unit and cannot exceed what is left unrefunded. Refunds start PENDING and complete asynchronously.

• Search ordersTier 0 · ReadReads outside contentsquare_search_orders

  Search orders at up to 10 locations by state (OPEN, COMPLETED, CANCELED, DRAFT), customer or update time, newest updated first. Shows line items, totals and the payments (tenders) for each.

• Search invoicesTier 0 · ReadReads outside contentsquare_search_invoices

  List Square invoices for one location, optionally one customer, newest first. Status shows DRAFT, UNPAID, SCHEDULED, PARTIALLY_PAID, PAID, CANCELED and so on; public_url is the payment page.

• Draft an invoiceTier 2 · ReversibleReads outside contentsquare_create_invoice

  Create a draft invoice for a customer with line items, due on one date and payable by card on Square's hosted page. Nothing is sent until publish_invoice. Prices are in the smallest currency unit.

• Send an invoiceTier 4 · Money or irreversibleReads outside contentsquare_publish_invoice

  Publish a draft invoice: Square emails or texts it to the customer with a payment link (or, for SHARE_MANUALLY, just creates the link), or schedules it. Needs the invoice's current version.

• Search catalog itemsTier 0 · ReadReads outside contentsquare_search_catalog_items

  Find items and their variations by name, SKU or description, with variation ids and prices. Use a variation id as catalog_object_id on invoice line items.

Testing, problems and disconnecting

Everdeck checks the connection when you save it. On the connection’s page in Integrations, Test checks it again at any time.

If Square later refuses the connection, for example because a key was deleted or a sign-in expired, the connection shows Needs attention on the Integrations page and the people who manage connections are told. Agents can’t use it until a company admin fixes it with Edit or Reconnect.

To stop agents using Square, open the connection and select Disconnect. Agents stop using it at once and its saved credentials are deleted. What else happens depends on how it was connected: each way above says.