# Add Subscription Billing to a Shopify App

Yes. An agent adds a billing plan to your Shopify app, requires it on embedded routes, handles the subscription webhook, type-checks, builds and opens a PR.

[Run this on Rush](https://cloud.getrush.ai/run/add-app-billing/shopify-app/). Opens the console with this prompt ready to send, in a Project that has your repository.

## What the agent does

The agent reads how the app authenticates before touching billing. In an app built from Shopify/shopify-app-template-react-router, `package.json` depends on `@shopify/shopify-app-react-router` 3.0, `@shopify/shopify-app-session-storage-prisma`, React Router 7.18.2 pinned exactly, Prisma 6 and `@shopify/app-bridge-react`, with `typecheck` running `react-router typegen && tsc --noEmit`, `lint` running ESLint, and `setup` running `prisma generate && prisma migrate deploy`. `app/shopify.server.ts` calls `shopifyApp()` with the API key and secret from the environment, `ApiVersion.October26`, `authPathPrefix: "/auth"`, `PrismaSessionStorage`, `AppDistribution.AppStore` and the `expiringOfflineAccessTokens` future flag, and has no `billing` key. `app/routes/app.tsx` is the layout every embedded page shares; its loader calls `authenticate.admin(request)` and returns the API key for `AppProvider`. `app/routes/app._index.tsx` creates a snowboard product through `admin.graphql`. `shopify.app.toml` subscribes to `app/uninstalled` and `app/scopes_update` with handlers in `app/routes/webhooks.app.*.tsx`, each of which calls `authenticate.webhook(request)`. `prisma/schema.prisma` has one `Session` model on SQLite, and `.github/workflows/ci.yml` runs `tsc --noEmit`, ESLint, `prisma validate` and `react-router build` on Node 22 and 24 with npm, yarn and pnpm.

Then it adds the plan where the library expects it. A `billing` object on `shopifyApp()` keyed by plan name, such as `MONTHLY_PLAN`, with `lineItems: [{ amount, currencyCode: "USD", interval: BillingInterval.Every30Days }]`, the amount and any `trialDays` taken from the issue. The agent exports the plan constant from `shopify.server.ts` and, in the `app.tsx` loader, destructures `billing` from `authenticate.admin(request)` and calls `billing.require({ plans: [MONTHLY_PLAN], isTest, onFailure })`, where `onFailure` returns `billing.request({ plan: MONTHLY_PLAN, isTest, returnUrl })` so a merchant without an active subscription is sent to Shopify's approval page and comes back to the embedded app. `isTest` is `true` outside production, read from `NODE_ENV`, so a development store never creates a real charge. Because the check sits in the layout loader, every route under `/app` is covered without repeating it, and the webhook routes, which never pass through `app.tsx`, stay unbilled as they must.

Subscription state changes outside the app, so the agent subscribes to it. A new `[[webhooks.subscriptions]]` entry in `shopify.app.toml` for `app_subscriptions/update` points at `/webhooks/app/subscriptions_update`, and `app/routes/webhooks.app.subscriptions_update.tsx` follows the two existing handlers: `authenticate.webhook(request)`, log the topic and shop, and record the subscription's id, name and status against the shop in a new Prisma `Subscription` model, added with a migration under `prisma/migrations/` so `prisma migrate deploy` in `setup` applies it. A small `app.billing.tsx` page reads `billing.check()` and shows the active plan with a cancel action that calls `billing.cancel({ subscriptionId, isTest, prorate: true })`, linked from the `s-app-nav` in `app.tsx`.

The agent cannot install the app on a store from its sandbox, and it says so. What it runs is what CI runs: `npm run typecheck` after `react-router typegen`, `npm run lint`, `npx prisma validate` and `npm run build`, plus `prisma migrate dev` against the local SQLite file to prove the new migration applies. The pull request names the manual step left: open the app on a development store with `shopify app dev`, approve the test charge, and watch the `app_subscriptions/update` webhook arrive. It also notes that Shopify now steers new public apps toward plans configured in the Partner Dashboard rather than in code, and that this change is the in-code path the library documents for apps that need to own their plan logic.

## Start it with one API call

`POST https://api.phoenix.so/o/{org}/sessions`

```json
{
  "agent": "claude",
  "input": "Add subscription billing to this Shopify app. Read package.json, app/shopify.server.ts, app/routes/app.tsx, app/routes/app._index.tsx, the webhook routes under app/routes, shopify.app.toml, prisma/schema.prisma and .github/workflows/ci.yml first. Add a billing configuration to shopifyApp with one plan named MONTHLY_PLAN at 9.99 USD every 30 days with a 7-day trial, export the plan name, and in the app.tsx loader call billing.require for that plan with an onFailure that calls billing.request with a returnUrl back to the embedded app; set isTest from NODE_ENV so it is true outside production. Subscribe to app_subscriptions/update in shopify.app.toml and write a webhook route that authenticates the request and records the subscription id, name and status per shop in a new Prisma model with a migration. Add an app.billing.tsx page that shows the plan from billing.check and offers cancel with prorate, linked from the app navigation. Do not bill the webhook routes. Run react-router typegen, tsc --noEmit, eslint, prisma validate, prisma migrate dev and react-router build until they pass, and open a pull request that explains the billing flow, lists the manual test on a development store, and notes the Partner Dashboard pricing alternative.",
  "resources": [
    {
      "url": "https://github.com/your-org/your-app"
    }
  ]
}
```

1. **Get an API key.** In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
2. **Send the request.** POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
3. **Read what came back.** Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.

## What comes back

What comes back is a pull request that changes `app/shopify.server.ts` to add the `billing` configuration and export the plan name, changes `app/routes/app.tsx` to require the plan in its loader and link the new page, adds `app/routes/app.billing.tsx` and `app/routes/webhooks.app.subscriptions_update.tsx`, adds a `Subscription` model and migration under `prisma/`, and adds the webhook subscription to `shopify.app.toml`. The description walks the flow from first open to approval to webhook, states that `isTest` is on outside production, and lists the manual test on a development store step by step.

The run's record keeps the `typecheck`, `lint`, `prisma validate`, `prisma migrate dev` and `build` output, the same checks `ci.yml` runs, so a reviewer can see the branch passes them before the workflow matrix starts.

Before merging, a reviewer runs the app on a development store, approves the test charge, confirms the `app_subscriptions/update` row appears, and decides whether the plan belongs in code or in the Partner Dashboard's pricing, which the pull request lays out as the alternative.

## Run it on every Linear issue labelled billing

In the console, add an automation to the Project with this prompt and a `linear` trigger on `linear.issue.labeled`, filtered to the `billing` label. When someone labels an issue such as "add an annual plan at 99 USD alongside monthly", the trigger puts the issue after the prompt and the run reads the amount, interval and trial from it before touching the config. Only label changes made by a person in your Rush org fire it, and the automation starts at most `max_runs_per_hour` runs in an hour.

From your own server, the same body goes to `POST /o/{org}/sessions` with the repository in `resources` and the issue URL beside it, read through your Linear connection, and a `request_id` that is a UUID v5 of the issue id, so a retried call returns the run already started rather than a second pull request.

## Why run it on Rush?

Billing touches the one loader every embedded route shares, a webhook topic the app has never handled and a new table, and a mistake in any of them is a merchant who is charged twice or never asked. The agent reads the layout loader and the two existing webhook handlers and follows their exact shape, then runs the type check, lint, Prisma validation and build in its own sandbox with the real lockfile before anyone opens the pull request.

Everything it ran stays with the run, so the pull request can say which checks passed and which step it could not take, the live approval on a store, and the reviewer spends their time on that step instead of on whether the code compiles.

## Frequently asked questions

### Will merchants be charged during development?

No. `isTest` is derived from `NODE_ENV` and is `true` everywhere except production, so `billing.request` creates a test charge that a development store can approve without money moving. The pull request shows the line so a reviewer can confirm it.

### Why require billing in app.tsx rather than each page?

Every embedded route renders inside the `app.tsx` layout, whose loader already calls `authenticate.admin`. Putting `billing.require` there covers `app._index.tsx`, `app.additional.tsx` and any page added later in one place, while webhook routes, which never render the layout, are never asked to pay.

### What is the Partner Dashboard alternative?

Shopify now lets a public app define its plans in the Partner Dashboard instead of in code, with the merchant choosing a plan on a Shopify-hosted page. The library's `billing` configuration remains the documented path when the app needs to own plan logic, one-time purchases or usage charges, and the pull request names both so the team picks deliberately.

### Does the agent test the real approval flow?

It cannot: approving a charge needs the app installed on a store through `shopify app dev` and a person clicking approve in the admin. The pull request lists that manual test in order, and the run's record shows the type check, lint, Prisma checks and build that the agent did run.

## More Shopify app jobs

- [Add an App Proxy to a Shopify App](https://getrush.ai/run/add-app-proxy/shopify-app/)
- [Add a Checkout UI Extension to a Shopify App](https://getrush.ai/run/add-checkout-ui-extension/shopify-app/)
- [Add the Mandatory Compliance Webhooks to a Shopify App](https://getrush.ai/run/add-compliance-webhooks/shopify-app/)

## More jobs like this: Turn a Linear label into a PR

- [Enforce App Check on Firebase Callable Functions from a Linear Issue](https://getrush.ai/run/add-app-check/firebase-functions/)
- [Add Article Search to a SvelteKit App from a Linear Issue](https://getrush.ai/run/add-article-search/sveltekit/)
- [Add Asset Checks to a Dagster Project from a Linear Issue](https://getrush.ai/run/add-asset-checks/dagster/)

## Keep reading

- [How a Rush run works on your repository, from request to pull request](https://getrush.ai/cloud/)
- [Compare cloud agents, agent sandboxes and AI code review](https://getrush.ai/compare/)
- [Rush pricing: Free, Pro and Max](https://getrush.ai/pricing/)
