# 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 Rush](https://cloud.getrush.ai/run/add-automatic-tax/stripe/). Opens 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`

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

## 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

- [Handle Stripe Subscription Cancellations in a Next.js App](https://getrush.ai/run/add-subscription-cancellation/stripe/)
- [Make a Stripe Webhook Handler Idempotent](https://getrush.ai/run/add-webhook-idempotency/stripe/)
- [Find Why Customers Churned in Stripe](https://getrush.ai/run/churn-analysis/stripe/)

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

- [Add AutoThrottle to a Scrapy Project](https://getrush.ai/run/add-autothrottle/scrapy/)
- [Add Background Jobs to a Litestar App](https://getrush.ai/run/add-background-jobs/litestar/)
- [Add Oban Background Jobs to a Phoenix LiveView App](https://getrush.ai/run/add-background-jobs/phoenix-liveview/)

## Keep reading

- [What an agent can do in Stripe itself, once you connect it](https://getrush.ai/integrations/stripe/)
- [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/)
