Integrations

Four services are required to run a store. Everything else is optional, and stays hidden until you configure it.

The admin splits along that line. Settings → Integrations holds the platform connections. Settings → Developer holds API keys, webhooks, deliveries, import runs and the self-host checks.

The four required services

PostgreSQL 15+
Redis / Upstash
S3-compatible storage
Resend

The fourth one is not what people expect on a required list. Sign-in is a magic link by email, so without Resend nobody can log in, including you. It is not a notifications nicety you can defer until launch week; it is the front door.

Outbound webhooks

Subscribe an endpoint to store events, and each event is delivered to it.

Every delivery is signed with HMAC-SHA256, and logged with its status code and its response body. The log is what turns "the integration is broken" into a specific failing request with a specific reply.

A failed delivery is retried up to five times.

An endpoint that keeps failing is switched off automatically:

last 15 completed deliveries all failed   →   endpoint disabled
one success in that window                →   endpoint stays alive

The disable is recorded in the activity log, so an integration that stopped working did not stop silently.

Fifteen consecutive failures is a dead endpoint, not a bad afternoon — and a single success anywhere in the window is enough to keep it running, so a flaky receiver is not killed for a bad patch.

The full list of events you can subscribe to is served at:

/api/webhooks/events

Service API keys

Issue keys for your own systems. There are six scopes:

• Read
• Cart read
• Cart write
• Order write
• Webhook write
• Operator MCP

Only scopes that something actually enforces exist. There is no decorative permission on that list that a key could carry without it meaning anything — which is why the list is short.

Keys are stored hashed, so the admin cannot show you a key again after it is issued.

Minting or revoking a key is restricted to a super admin, even though viewing the page is not. Someone can audit which keys exist without being able to create one.

MCP for AI assistants

Two endpoints, with very different audiences.

/api/mcp is public, and advertised at /.well-known/ucp. It gives a shopper's assistant eight tools:

1. Store info
2. Product search
3. Product details
4. Create cart
5. Add to cart
6. View cart
7. Checkout link
8. Order status

Nothing there charges. The checkout tool hands back a link that a person opens and completes through the normal storefront — the assistant can build a cart, but a human finishes the purchase in your checkout, under your policies.

/api/mcp/admin needs a key carrying the operator MCP scope (admin:mcp), and exposes the same tool kit as the in-admin assistant, through the same gate.

That shared gate is the important part. A tool you disabled in Settings → AI is invisible over MCP too, and every change-making call produces an approval card you click in the admin. The remote route is not a way around the controls you set on the local one.

See MCP servers.

Platform connections

Six platforms connect from Settings → Integrations:

• Google Ads
• Google Merchant Center
• Meta Commerce
• Shopify
• X
• Bluesky

Each stores its credentials encrypted, records its last successful sync, and is flagged on the settings page when that sync goes stale or errors.

The staleness flag matters more than the error flag. A connection that errors tells you; a connection that has silently stopped syncing looks exactly like one that had nothing to sync.

Catalog import

Connect a Shopify store over OAuth and import products, customers and collections.

Each run records:

• Its scope and mode
• Running counts of imported, updated, skipped and failed rows
• A downloadable error report
• A checkpoint, so a stopped run can resume

Imported records keep a mapping back to their Shopify ids, which is what lets a second run update what the first one created instead of duplicating it.

Newsletter providers

Seven options:

Klaviyo
Mailchimp
ConvertKit
Buttondown
Loops
Beehiiv
a plain webhook

The first one configured is the one used. There is no priority setting to get wrong — configure one.

Self-hosting

Postgres, Redis and S3 are yours to run.

Settings → Developer checks the seven things a deployment needs, and names the ones that are not answering:

1. Database
2. Redis
3. Public site URL
4. Transactional email
5. Media storage
6. Payments
7. AI provider

Run this page first when something is wrong on a fresh deployment. A missing environment variable presents itself as a hundred different symptoms elsewhere and as one red line here.

Beyond the required four, the optional list is: Stripe, the Shopify import, PostHog, Plausible, GA4, Meta, the AI providers (Google, Anthropic, OpenAI), and newsletters.

The records behind it

For anyone reading the data directly:

Webhook
WebhookDeliveryLog
ServiceApiKey
ImportRun
ImportSourceRecord
Integration          (encrypted platform credentials)

Getting started

Set the four required services first, then add only the optional ones you actually use. An unconfigured integration is hidden rather than half-present, so there is no cost to leaving one out.

If you are migrating, import an existing catalog over Shopify OAuth and read the run's error report — the skipped and failed counts are where the migration's real state is.

Then issue an API key with the narrowest scope that works, and point a webhook endpoint at the events you need.

When you are choosing a scope or deciding what to subscribe to, the question is not what would be convenient:

Grant the narrowest thing that still works, because a key you cannot read back is a key you will not audit later — and design the receiving process so a missed event costs you a delay, not a wrong number.

Related