All jobs

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 RushOpens 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 with this body:

{
  "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.

The use case this job follows, with its automation and trigger: Turn a Linear label into a PR.

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

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

Keep reading