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

# Shopify plugin

> Read and manage products, variants, inventory, collections, orders and customers in a Shopify store, and verify the webhooks Shopify sends.

Use **Shopify** through Corsair: one client, typed API calls, and incoming webhooks.

Connecting a store asks for its `*.myshopify.com` domain plus one of two
credentials, all stored on the account:

* **Client ID and Client secret** of a Dev Dashboard app (every app created
  since January 2026). The plugin exchanges them for an Admin API token with
  the client credentials grant, keeps the token with its expiry, renews it
  five minutes before Shopify's 24-hour limit, and renews once more if
  Shopify rejects it early with a 401. Nothing has to be replaced by hand:
  `pnpm corsair setup --plugin=shopify --tenant=acme shop_domain=<store>.myshopify.com client_id=<id> client_secret=<secret>`.
* **Admin API access token** (`shpat_…`) from an app made with the old
  admin-created custom app flow. Those tokens do not expire:
  `pnpm corsair setup --plugin=shopify --tenant=acme api_key=<token> shop_domain=<store>.myshopify.com`.
  A token and domain can also be passed as `key` and `shopDomain` in the
  plugin options.

When the client ID and secret are set they win: the API key slot then holds
the token the plugin minted. A token or app without a domain fails before the
call, because every request URL is built from it.

To make a Dev Dashboard app, open dev.shopify.com, create the app, add a
version with the scopes the operations you call need (`read_products`,
`write_products`, `read_orders`, `write_orders`, `read_customers`,
`write_customers`, `read_inventory`, `write_inventory`), release it, and
install it on the store. Copy the Client ID and Client secret from the app's
Settings. The client credentials grant only works when the app and the store
belong to the same organisation in the Dev Dashboard: if a call fails with
`shop_not_permitted`, create the store from the Dev Dashboard's Dev stores
page; `app_not_installed` means the app is not installed on the store yet.

A Dev Dashboard app also needs protected customer data access before it can
read customers. Request it in the Partner Dashboard (partners.shopify.com,
your app, API access, Protected customer data): pick the reasons, and the
Name, Email, Phone and Address fields you need. Apps that are not on the App
Store get it without review. Until then Shopify refuses every query that
touches the Customer object, so `customers.list` and `customers.get` fail with
"This app is not approved to access the Customer object".

The Admin API is GraphQL and versioned quarterly. This plugin calls
`2026-10`, the newest stable version. Shopify throttles by calculated query
cost and reports the result in the response body rather than a header, so a
throttled call arrives as HTTP 200 with a `THROTTLED` code; the plugin reads
the cost bucket and waits long enough to cover the query before retrying.

A mutation that the store rejects also answers HTTP 200, with the reason in
`userErrors`. The plugin treats a populated `userErrors` as a failure, so a
caller is never told a write succeeded when it did not.

With object access granted but a field such as Name or Email not selected,
Shopify returns the customer rows with those fields nulled and an
`ACCESS_DENIED` error beside the data. The plugin accepts that partial result
and logs a warning rather than failing the call, so `customers.list` still
returns ids, order counts and spend. The `Customer` object's `displayName` is the one exception: asking for
it returns no data at all, so this plugin never selects it and callers build a
name from `firstName` and `lastName`.

Webhook deliveries are JSON and signed with `X-Shopify-Hmac-Sha256`. Set the
app's signing secret as the plugin's webhook secret. Verification runs over
the raw request body, so the handler must receive a `rawBody`.

**What you get:**

* 28 typed API operations
* 1 incoming webhook event types

## Setup

**1. Install**

```bash npm theme={null}
npm install corsair @corsair-dev/shopify better-sqlite3
npm install --save-dev @types/better-sqlite3
```

```bash yarn theme={null}
yarn add corsair @corsair-dev/shopify better-sqlite3
yarn add --dev @types/better-sqlite3
```

```bash pnpm theme={null}
pnpm install corsair @corsair-dev/shopify better-sqlite3
pnpm install --save-dev @types/better-sqlite3
```

```bash bun theme={null}
bun add corsair @corsair-dev/shopify better-sqlite3
bun add --dev @types/better-sqlite3
```

**2. Add the plugin**

```ts corsair.ts theme={null}
import Database from 'better-sqlite3';
import { createCorsair } from 'corsair';
import { shopify } from '@corsair-dev/shopify';

export const corsair = createCorsair({
	plugins: [
		shopify(),
	],
	database: new Database('corsair.db'),
	kek: process.env.CORSAIR_KEK!,
	multiTenancy: true,
	hub: {
		projectApiKey: process.env.CORSAIR_API_KEY!,
		signingSecret: process.env.CORSAIR_SIGNING_SECRET!,
	},
});
```

With `multiTenancy: true`, scope calls with `corsair.withTenant(id)`. See [Quick start](https://docs.corsair.dev/quick-start.md) for KEK + Hub keys, and [Multi-tenancy](https://docs.corsair.dev/concepts/multi-tenancy.md) for account isolation.

**3. Choose authentication**

> [tab] API Key (Recommended)
>
> Store the Shopify API key before the first call: `pnpm corsair setup --plugin=shopify --tenant=acme api_key=<your-key>` (leave out `--tenant` without `multiTenancy`), or pass it as `key` in the plugin options. With Hub, each tenant enters their own key on the connect page. See [API key auth](https://docs.corsair.dev/concepts/api-key).
>
> ```ts theme={null}
> shopify()
> ```
>
> More: [API Key](https://docs.corsair.dev/concepts/api-key)

**4. Connect a tenant**

Mint a connect link and send the tenant to it. Hub hosts the page and delivers the result to your app — see [Connect / OAuth](https://docs.corsair.dev/management/connect).

```ts theme={null}
const { connectUrl } = await corsair.manage.connect.createLink({
	plugin: 'shopify',
	tenantId: 'acme',
});
// redirect the user's browser to connectUrl
```

## Example API calls

**`products.list`**

```ts theme={null}
const tenant = corsair.withTenant('acme');
await tenant.shopify.api.products.list({});
```

**`products.update`**

```ts theme={null}
const tenant = corsair.withTenant('acme');
await tenant.shopify.api.products.update({});
```

See the full list on the [API](https://docs.corsair.dev/plugins/shopify/api.md) page.

## Webhooks

Shopify puts the topic in the X-Shopify-Topic header and signs the raw body with X-Shopify-Hmac-Sha256. One handler covers every supported topic and the header selects the payload schema.

```ts theme={null}
shopify({
    webhookHooks: {
        shopify: {
            receive: {
                after: async (ctx, result) => {
                    // result.data.topic names the delivery, e.g. orders/create
                }
            },
        },
    },
})
```

Mount your framework handler once (see [Frameworks](https://docs.corsair.dev/frameworks/next.md)), then point the provider at that URL. Full event list: [Webhooks](https://docs.corsair.dev/plugins/shopify/webhooks.md). Concepts: [Webhooks](https://docs.corsair.dev/concepts/webhooks.md), [Hooks](https://docs.corsair.dev/concepts/hooks.md).

## What's next

> [card] [API reference](https://docs.corsair.dev/plugins/shopify/api.md)
>
> Every `shopify.api.*` operation with input and output types.

> [card] [Webhooks](https://docs.corsair.dev/plugins/shopify/webhooks.md)
>
> Event paths, payloads, and `webhookHooks` examples.

> [card] [Connect / OAuth](https://docs.corsair.dev/management/connect)
>
> createLink, Hub delivery, and tenant connect flows.

> [card] [Use with agents](https://docs.corsair.dev/mcp-adapters/mcp-adapters)
>
> Expose this plugin's operations as MCP tools.


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