> ## Documentation Index
> Fetch the complete documentation index at: https://help.the-meridian.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Introduction

`@the-meridian/sdk` is the package you install **inside your own Shopify app**. It is the runtime half of Meridian: you design plans, features and automations in the dashboard, and the SDK applies them in your app's code.

```bash theme={null}
npm install @the-meridian/sdk
```

`react` and `react-dom` (>= 18) are peer dependencies, and the package needs Node 18 or newer. It ships ESM and CJS with types.

## What it gives you

| You want to | The SDK gives you |
| - | - |
| Show or hide a paid capability | [Feature gating](/features): synchronous checks in render |
| Bill for volume | [Usage tracking](/events): one `track` call per metered action |
| Sell your plans | [Pricing page](/plans): a full plan grid, rendered from your plans |
| Let a merchant manage their subscription | [Account page](/account): usage bars, raise cap, cancel |
| Wire the install once | [`createMeridianApp`](/sdk-app): webhooks, automations, subscription sync and attribution in one `afterAuth` call |
| Gate a resource route or a job | [Server client](/sdk-server-client): the same gates without React |
| Receive your Shopify webhooks | [Forwarded webhooks](/sdk-webhooks): signature verification and the host challenge |
| Credit an affiliate for an install | [Referral capture](/sdk-referrals) and [attribution](/sdk-attribution) |
| Push your own data into the CRM | [Custom field values](/custom-fields-api) |

You never implement Shopify's recurring-charge or usage-charge APIs yourself. Meridian holds the billing handshake, and the SDK is the thin layer your app calls.

<Warning>
  The billing half of that list (subscribe, cancel, raise cap, and usage overage charges) requires your app to be **hosted on Meridian**. Everything else works wherever your app runs. [What needs Meridian hosting](/sdk-hosting) draws the line precisely; read it before you plan an integration.
</Warning>

## Two entry points

<CardGroup cols={2}>
  <Card title="@the-meridian/sdk" icon="atom">
    The React surface, for the browser: the provider, the `useMeridian` hook, and the two page components.
  </Card>

  <Card title="@the-meridian/sdk/server" icon="server">
    The server surface, for Node: the app factory, the server and admin clients, webhook verification, and the referral helpers. No React.
  </Card>
</CardGroup>

The split is a security boundary: your app's secret API key is only ever read by the server entry. See [Credentials](/sdk-credentials).

## The shape of an integration

1. Your server holds `MERIDIAN_APP_ID` and `MERIDIAN_API_KEY`.
2. In your Shopify `afterAuth` hook, one call registers webhooks, fires your install automations, reports the shop's subscriptions (trials included) and attributes any affiliate referral.
3. In the loader for your app shell, you exchange the shop for a short-lived **shop token**.
4. In the browser, you mount the provider with that token. Everything below it can gate features, read usage, and drive billing.

[Quickstart](/sdk-quickstart) walks through all four with the code.

<Note>
  The SDK is not the only way in: the [Meridian MCP server](/mcp-server) exposes your Meridian workspace to an AI agent, and the [CLI](/cli) handles local development and managed developer databases.
</Note>


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