> ## Documentation Index
> Fetch the complete documentation index at: https://docs.opensubs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Update the platform

> Four commands in order, about ten minutes, safe to re-run.

OPENSUBS PLATFORM

10 min

You received this repository with your license, and `git pull` is how our releases reach your copy. An update is four commands, run in a terminal at your repository root, in this order:

```bash theme={"dark"}
git pull
npm run merchant:migrate
npm run merchant:functions
cd app && vercel deploy --prod
```

The order is the one rule: database first, app last. After one-time prep, the steps below walk through one command each.

> [!NOTE]
>
> **You can't break it by re-running.** Every command skips what's already done; applied migrations stay applied. Interrupted halfway, run the same command again and it picks up where it stopped.

**1. One-time prep**

* Create a Supabase personal access token at [supabase.com/dashboard/account/tokens](https://supabase.com/dashboard/account/tokens).
* Put two lines in the `.env` file at your repository root: the token, and your project ref (the `<ref>` in `https://<ref>.supabase.co`). The update scripts read them automatically.

```bash theme={"dark"}
SUPABASE_ACCESS_TOKEN=sbp_xxxxxxxx
SUPABASE_PROJECT_REF=yourprojectref
```

> [!TIP]
>
> **Checkpoint:** `.env` shows both lines.

**2. Get the new version**

```bash theme={"dark"}
git pull
```

* Read `CHANGELOG.md` for the version you pulled; anything needing manual attention is flagged under **Action required**.

**3. Apply the database migrations**

```bash theme={"dark"}
npm run merchant:migrate
```

* Applies every pending migration to your Supabase project, in order. To preview first, run `npm run merchant:migrate -- --dry-run`: it lists what would apply and changes nothing.
* A one-time `adopted ... (ledger row only)` line is normal bookkeeping; nothing to do.

> [!TIP]
>
> **Checkpoint:** running it again reports `0 pending`.

**4. Deploy the webhook functions**

```bash theme={"dark"}
npm run merchant:functions
```

* Redeploys your Supabase Edge Functions, where Shopify's webhooks land. If the changelog asks for just one, add `-- --only` plus the name, like `-- --only orders-webhook`.

> [!TIP]
>
> **Checkpoint:** the command finishes without errors.

**5. Redeploy the app, last**

```bash theme={"dark"}
cd app && vercel deploy --prod
```

* First time only: run `vercel link` from `app/` and pick your existing OpenSubs project.
* If your Vercel project is connected to your repository, skip the command: `git push` and Vercel rebuilds on its own.
* Last on purpose: at startup the app checks that every migration its code expects is applied. Deploy before migrating and it refuses API traffic with a 503 reading **Database schema out of date**, naming the missing migrations ([When an alert opens](https://docs.opensubs.com/platform-v2/run/when-an-alert-opens.md)).

> [!TIP]
>
> **Checkpoint:** the deploy finishes and the admin opens clean.

> [!NOTE]
>
> **Two things also get newer versions over time. One updates itself; one needs a click.**
>
> * **API versions update with the platform.** The versions used to talk to Shopify and your providers move forward as part of this procedure; there is nothing to set. Check **Settings > Operational health**, panel **Integration connections**: every version row should read **Current**. A Shopify row reading **Update available** or **Unsupported** means run this update: **Update available** is the routine pre-update state, **Unsupported** means do it soon.
> * **Your provider accounts update with a click.** The pieces setup created inside them (SendGrid email templates, Klaviyo flows, the Gorgias sidebar widget) are not touched by this procedure. When a newer version ships, that provider's card on **Settings > Integrations** shows **Update available**: click **Update to latest**.

![The Shopify version rows before an update: Update available, resolved by running this procedure.](https://mintcdn.com/opensubs-docs/T6NpYT9MdOxqnOk5/images/platform-v2/run/40-shopify-version-rows.png?fit=max\&auto=format\&n=T6NpYT9MdOxqnOk5\&q=85\&s=c5436772a4b7d97fc75908bd14882c33)

![A provider card with an update waiting: the Update available badge and the Update to latest button.](https://mintcdn.com/opensubs-docs/T6NpYT9MdOxqnOk5/images/platform-v2/run/39-update-to-latest.png?fit=max\&auto=format\&n=T6NpYT9MdOxqnOk5\&q=85\&s=a7ac59fc1eb367e4c1779ee4d95b48e4)

> [!NOTE]
>
> **If a step fails.**
>
> * A migration that fails partway resumes on the next run, skipping what already applied.
> * The same migration failing twice is your stop sign: don't force it or hand-edit the database; hand the error text to whoever runs your code.
> * A 503 right after an update means you deployed before migrating: run the migrate step, then reload.
> * Updates roll forward, never back: undoing one means restoring the database from Supabase's Point-in-Time Recovery (**Project > Database > Backups**) and redeploying the previous build from Vercel.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.