It was a Tuesday night, and I was renaming a price in the Stripe dashboard.
A price I had already renamed in our code three weeks earlier. The deployment had gone fine. Customers were unaffected. But the internal name still said pro_v2_alpha in Stripe, and now I was scrolling through a long list of products trying to find it, clicking in, clicking the pencil icon, typing the new name, clicking save, waiting for the spinner.
Then I had to do it for the test-mode account. Then the staging account. Then I had to remember to update the seed script.
There was no diff. There was no record of what changed. Nothing was stopping me from taking the test, and live accounts drift further apart with every click.
That night I started writing gatr.
The thing I actually wanted
I wanted Stripe products and prices to live in a YAML file in my repo, and I wanted one command to make Stripe match the file.
Same shape as terraform plan / terraform apply. Same idempotency. Same "show me what's about to change before you change it." I didn't want a SaaS for it, and I didn't want to learn another DSL. Just YAML in, Stripe in lockstep out.
What I had been doing — a hand-written init_stripe.py script that POSTed to the Stripe API — was halfway there, but it had the same problem every hand-rolled IaC script has: it could create things, but it couldn't tell me what was already there, and it couldn't safely update without me reading the diff in my head.
What I built
gatr is a single Go binary. The whole input contract is a gatr.yaml and a Stripe restricted key. No server, no database, no account on my service.
project: acme
plans:
- id: pro
display_name: Pro
stripe_product_id: prod_pro
prices:
- id: monthly
stripe_price_id: price_pro_monthly_v2
amount: 2900
currency: usd
interval: month
You write that. You run gatr push. The CLI fetches the current state of your Stripe account, computes a diff, and prints it:
+ create product prod_pro "Pro"
+ create price price_pro_monthly_v2 $29.00 / month
unchanged feature.api_access
Hit y, and it applies. Run it again — the diff is empty. That's the bit I cared about the most. Re-running an apply that did real work the first time should be a no-op the second time. That's the property that makes it safe to run from CI on every PR.
What I learned in the implementation
A few things surprised me.
1. Stripe doesn't let you update price amounts. Once a price is created, the unit amount is frozen. You can only create a new price and (separately) deactivate the old one. This sounds obvious — it's there to protect existing subscribers — but it means the "diff" engine has to distinguish a soft update (rename, metadata change, tax behavior) from a hard replace (amount change). The CLI surfaces this explicitly: gatr push warns when a change would require a hard replace, and --auto-patch is the flag that says "yes, I know existing subscribers stay on the old price; create a new one."
2. Metered billing is its own world. Stripe's new Billing Meters API isn't a price field — it's a separate object that prices reference. Getting the diff engine to treat (product, price, meter) as a coordinated unit took longer than the rest of the CLI combined.
3. Idempotent isn't free. Stripe's Idempotency-Key header gets you POST-level safety, but it doesn't get you semantic safety. If your YAML changes between two runs, the second run is a different request. The actual idempotency property — "running push twice in a row produces no changes" — comes from the diff engine, not from Stripe. Most of the engineering effort sits in there.
What I didn't build
A few things I deliberately left out.
-
No SaaS layer. The CLI talks directly to Stripe. There's no "gatr account" to sign up for. If I disappear tomorrow, your
gatr.yamlis still a portable description of your Stripe billing. - No GUI. If you want a GUI, the Stripe dashboard is right there. The CLI is for the part that the dashboard is bad at.
-
No "drift detection" daemon. The CLI is run on demand — usually in CI, sometimes locally before a release. The drift you care about is "did someone click in the dashboard," and you find that out the next time you run
gatr push --dry-run.
How I use it
In the project I built it for, gatr push --dry-run runs on every PR that touches gatr.yaml. The diff gets posted as a PR comment. If the diff is empty, the PR doesn't need a billing review. If it isn't, our billing lead reviews it before merging. After the merge, gatr push --auto-approve runs from CI against staging, then against prod after a manual approval gate.
The midnight click-fests are gone.
Try it
go install github.com/EduardMaghakyan/gatr-cli/cmd/cli@latest
gatr init # pick a template
gatr validate # lint the yaml
export STRIPE_SECRET_KEY=sk_test_...
gatr push --dry-run
Or, if you already have products and prices in Stripe that you'd rather not re-declare from scratch:
gatr import --project my-app
# writes a starter gatr.yaml from your Stripe account
It's open source, MIT, no CLA: github.com/EduardMaghakyan/gatr-cli.
If you've been clicking through the Stripe dashboard to change a price and felt the same itch I did, I'd love to hear what your workflow looks like, and whether the diff engine catches the cases you care about. Issues and discussions are open.
Top comments (0)