All jobs

Add Automatic Tax to a Stripe Checkout Subscription

Yes. An agent turns on Stripe Tax in your Checkout session, collects the address and tax ID it needs, checks the price's tax setting, 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 the subscription flow end to end before it changes it. In a Next.js app laid out like shadcn-ui/taxonomy, app/api/users/stripe/route.ts creates a Checkout session in subscription mode with payment_method_types: ["card"], billing_address_collection: "auto", the signed-in user's customer_email, one line item for proPlan.stripePriceId from config/subscriptions.ts, and the user's id in metadata; a user who is already on the plan gets a billing portal session instead. app/api/webhooks/stripe/route.ts verifies the signature with STRIPE_WEBHOOK_SECRET and, on checkout.session.completed and invoice.payment_succeeded, writes stripeCustomerId, stripeSubscriptionId, stripePriceId and stripeCurrentPeriodEnd to the users table in prisma/schema.prisma. lib/stripe.ts pins the stripe package at API version 2022-11-15, and env.mjs requires STRIPE_API_KEY, STRIPE_WEBHOOK_SECRET and STRIPE_PRO_MONTHLY_PLAN_ID. The pricing page in app/(marketing)/pricing/page.tsx shows one plan with no mention of tax.

It changes the Checkout call in three places. automatic_tax: { enabled: true } asks Stripe Tax to compute tax at checkout. billing_address_collection becomes required, because Stripe Tax needs a full address to pick a jurisdiction and auto only asks when a card rule demands it. tax_id_collection: { enabled: true } lets a business customer enter a VAT or similar number so a reverse charge applies where it should. For a user whose row already carries a stripeCustomerId, which happens when a subscription has lapsed, the route passes customer instead of customer_email together with customer_update: { address: "auto", name: "auto" }, so the address collected at checkout is saved on the customer and later invoices are taxed from it; Stripe refuses customer_update without a customer, so the two branches stay separate.

The price matters as much as the session. A price whose tax_behavior is unspecified makes a Checkout session with automatic tax fail at creation, so the agent adds a small script under scripts/ that reads STRIPE_PRO_MONTHLY_PLAN_ID with stripe.prices.retrieve and prints its tax_behavior, unit_amount and currency. Setting the behaviour is a one-time change on the price in the dashboard or with stripe.prices.update, and the agent puts the exact call in the pull request rather than running it, since whether the listed price is tax-inclusive or tax-exclusive is a pricing decision. The pricing page gets a line saying tax is added at checkout, worded for the exclusive case, with the inclusive wording in the description.

The webhook does not need to change: the subscription's current_period_end and price are what the handler already stores, and the tax amounts live on the invoice in Stripe. The repository has no test runner, so the agent runs pnpm lint and pnpm build, which type-checks the route against the stripe package's own declarations, and leaves a checklist for the reviewer's test-mode run, including a test address in a taxed region and a test VAT number.

Start it with one API call

POST https://api.phoenix.so/o/{org}/sessions with this body:

{
  "agent": "claude",
  "input": "Add automatic tax to the Stripe subscription checkout. Read lib/stripe.ts, app/api/users/stripe/route.ts, app/api/webhooks/stripe/route.ts, lib/subscription.ts, config/subscriptions.ts, env.mjs, prisma/schema.prisma, app/(dashboard)/dashboard/billing/page.tsx and app/(marketing)/pricing/page.tsx first. In the Checkout session enable automatic_tax, set billing_address_collection to required and enable tax_id_collection. When the user already has a stripeCustomerId, pass customer with customer_update address and name set to auto instead of customer_email. Add a script under scripts/ that retrieves the price in STRIPE_PRO_MONTHLY_PLAN_ID and prints its tax_behavior, and put the exact prices.update call to set it in the pull request description without running it. Add a line to the pricing page saying tax is calculated at checkout. Do not change the webhook unless the session change needs it. Run pnpm lint and pnpm build, and open a pull request with the output and a test-mode checklist for the reviewer.",
  "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/api/users/stripe/route.ts and the pricing page and adds one script. The description shows the new session body for both branches, new customer and returning customer, explains why the address became required, gives the prices.update call for tax_behavior with both values and what each means for the displayed price, and lists the test-mode steps a reviewer runs with a test card, a taxed address and a test tax ID.

The run's record keeps the lint and build output and the agent's reading of the stripe declarations for each parameter it used, so a reviewer can check that every option exists at the pinned API version. A reviewer checks the returning-customer branch against a lapsed test subscription and reads the portal configuration to make sure customers can update their address there, which is a dashboard setting and not code.

Run it on every Linear issue labelled billing

A team makes this a rule. In the Project for the repository, an automation with the prompt above and a linear trigger on linear.issue.labeled for the label billing starts a run when someone files "we need to charge VAT in the EU" or "customers ask for a tax ID on invoices". The trigger adds the issue after the prompt, so the run reads whether the issue is about tax IDs, a region or the displayed price and scopes its change to that.

Each run opens its own pull request on its own branch and links the issue. A repository whose checkout already enables automatic tax gets a description saying so and a pull request only for what the issue asks for, such as tax ID collection.

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

Why run it on Rush?

Turning on Stripe Tax is one flag, and the three things around it are what break: an address that was never collected, a price with no tax behaviour that makes every checkout fail at creation, and a returning customer whose stored address never updates. The agent reads the route and the schema in its sandbox, writes both branches, and checks each parameter against the package's own declarations at the API version the app pins, so the reviewer's test-mode run is a confirmation and not a hunt.

The pull request is one route, one script and a line of copy, so review is reading two session bodies. A company with several products on Stripe runs this on all of them at once, each in its own sandbox with its own pull request.

Frequently asked questions

Why does the address become required?

Because Stripe Tax computes tax from the customer's location and billing_address_collection: "auto" only collects an address when the card's rules require one. With required, Checkout always asks, so there is always a jurisdiction to tax in. Customers in a region with no tax registered see a zero tax line, not an error.

Why not run the prices.update call?

Because tax_behavior decides whether the price you already show is what customers pay or what they pay before tax, and once set it cannot be changed on that price. The agent reports the current value and gives the call for both choices; a person makes the choice.

Does the stored subscription data change?

No. The webhook keeps writing the subscription id, customer id, price id and period end. Tax amounts live on each invoice in Stripe, where the billing portal shows them; a later run can read total_tax_amounts from the invoice webhook if the app wants to display them.

Can this be checked without a Stripe account in the sandbox?

The code can: the build type-checks every parameter against the stripe package. A real tax calculation needs test mode with Stripe Tax enabled, which is why the pull request carries a checklist for the reviewer rather than a claimed result.

More Stripe jobs

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

Keep reading