Docs · Setup

Connect Square in 5 minutes

One-time setup in Square's developer portal. After this the Connect Square button works one-click for your merchant and every café you ever onboard to this StockPilot deployment.

1

Open Square's developer portal

Go to developer.squareup.com/apps and sign in with your Square merchant account. If you don't have one, create a free Square account first (same sign-in works for the developer portal).

2

Click + New Application

Top-right corner of the apps list. Use these exact values:

Application name

StockPilot

Description

Inventory management for cafés — auto-depletes stock on every Square sale, drafts supplier POs, forecasts runouts.

Pick Production (not Sandbox) if you want to connect real merchants. You can also create a Sandbox app first to test — the app works with both; just keep the two sets of credentials separate.

3

Configure OAuth redirect

Open the app. Left nav → OAuth. Paste into the Redirect URL field:

Redirect URL

https://stockpilot-app-production-2a53.up.railway.app/api/integrations/square/callback

Click Save. Leave the OAuth Production/Sandbox toggle matching the app type you picked in step 2.

4

Copy Application ID + Secret

Same OAuth screen. You'll see two values near the top — Application ID and Application Secret. They're what Square calls “Client ID” and “Client Secret” in OAuth terms. Reveal the secret, copy both. You'll paste them into Railway in step 6.

5

Create a webhook subscription

Left nav → Webhooks → Subscriptions. Click Add subscription. Use:

Name

StockPilot sales + catalog

Notification URL

https://stockpilot-app-production-2a53.up.railway.app/api/integrations/square/webhook

Under Event types check these six:

  • order.created
  • order.updated
  • payment.updated
  • catalog.version.updated
  • item.updated
  • category.updated

Save. Square will show a Signature key on the subscription detail page — reveal and copy it. That goes into Railway in step 6 as SQUARE_WEBHOOK_SIGNATURE_KEY.

6

Paste all three into Railway

Open your StockPilot service on Railway → Variables tab → + New Variable three times:

  • SQUARE_CLIENT_ID=paste the Application ID
  • SQUARE_CLIENT_SECRET=paste the Application Secret
  • SQUARE_WEBHOOK_SIGNATURE_KEY=paste the webhook signature key

Railway redeploys automatically — takes ~60 seconds. Optionally add SQUARE_ENVIRONMENT=production (defaults to sandbox).

7

Back to StockPilot, click Connect Square

Reload /settings. The Square row no longer errors — clicking Connect Square now opens Square's real OAuth screen. Sign in as your merchant, grant, return. The row flips to Live · 0 sales this week and the catalog starts syncing in the background.

From this point forward, every Square sale depletes inventory in real time.
← Back to Settings