Forem: Jevon MacDonald

Stripe Glossary

Jevon MacDonald — Tue, 06 Dec 2022 19:20:44 +0000

Stripe Glossary available at github.com/tierrun/tier/wiki/Stripe-Glossary

Getting to know Stripe can take some time. Not only are there a lot of new concepts to learn, Stripe sometimes likes to use esoteric definitions for some things, such as "Good-better-best".

We have developed a Stripe Glossary that can be used as a reference. This is useful as you navigate Stripe's documentation and should help demystify the meaning of all these new terms you will encounter.

We will continue to update and evolve the glossary and hope it can be a useful resource for anyone who is in the process of developing their understanding of Stripe and its capabilities.

You can find the working glossary here: https://github.com/tierrun/tier/wiki/Stripe-Glossary. We welcome any suggested updates that you might have.

Here is the current list of terms, with direct links to their definitions.

Tier CLI v0.6

Jevon MacDonald — Wed, 30 Nov 2022 01:36:45 +0000

You can find the Tier CLI v0.6 here.

The v0.6 release introduces a way to manage customer data stored in stripe for any Tier managed org.

To set the email, description, name, phone, or user-defined metadata, for an org, set the new info field for /v1/subscribe request. In addition to this change, a minimum of one phase for a /v1/subscribe request is no longer required.

The new fields are:

description
name
phone
email
metadata

Additionally, the /v1/whois endpoint will now report up-to-date attributes if the query parameter include=info is present.

Both the Go and Node SDKs have been updated.

Please head over to https://tier.run/releases to check out more changes and install options. As always, brew upgrade tierrun/tap/tier works too!

If you haven't used Tier yet, these resources are a good place to get started:

Hello World! example - Step by step guide to adding Tier to your new or existing codebase

Quick Start Guide - Step by step to getting up and running with Tier.

Recipes - Example common pricing models and their corresponding Tier pricing.json representations.

CLI Reference - Documentation for the Tier command line tool.

Questions you should ask when interviewing at a startup

Jevon MacDonald — Tue, 29 Nov 2022 16:17:51 +0000

Interviews... interviews... If you've ever switched jobs then you know there can be good interviews, and there can be really bad ones. Sometimes a bad interview means it's a bad company. Sometimes it means you aren't the right hire for them.

Interviews are typically structured as a 1-way conversation. Sometimes there is a cursory "do you have any questions for me?" as the interviewer glances at their watch with a few minutes left before your time is up.

The truth is that it's very hard to stand out in an interview when you are responding to questions. The best you can hope for is to check a few boxes in an otherwise obscure and fuzzy process.

How can you turn any interview from boring to engaging? From mundane to exciting? Asking great questions!

Interviewees who ask great questions stand out from the pack and they look and sounds like leaders. Asking good questions is a skill for you to develop. For the person on the receiving end, a good question demonstrates that you have a depth of understanding, an earnest interest, and that you have leadership skills and the ability to influence.

The right questions to ask are going to be different in every situation, but there are a few that can be helpful in any situation when you are interviewing with a hiring manager.

1. What is the team culture like? Why is it like that?

You'll never get a consistent answer on this one, and sometimes it might be hard to get a truthful answer. What you are told may speak volumes about not only the company, but more importantly how the person you are asking perceives the company itself. Asking "why is it this way?" may open up a discussion about values and leadership, or you may find some subtle finger pointing going on. Keep an eye out for 🚩🚩🚩 red flags.

Tier v0.5.2

Jevon MacDonald — Wed, 23 Nov 2022 17:44:01 +0000

We just released v0.5.2, with some exciting new enhancements and features.

Switch preallocations: The tier switch -c command now preallocates switch accounts which means after the first switch account is created, subsequent uses of tier switch -c should be noticeably faster, like, complete in 10us fast! This is because it can now avoid waiting on slow API calls to Stripe.

Plan immutability: Plans are now 100% immutable, as was originally planned. To upgrade all existing Tier plans to be 100% immutable, please run tier pull | tier push - 2 times; The second should produce output saying [plan already exists], which is your confirmation the migration was successful.
Deep links: Push now outputs deep links to the corresponding prices in Stripe.
Clean command: We added the tier clean -switchaccounts command. As you might guess, it cleans up accounts in Test Mode that were created by the switch command. The full command takes a duration of time for specifying the maximum age to use when considering an account for removal. Please see tier clean -h for more information.

Please head over to https://tier.run/releases to check out more changes and install options. As always, brew upgrade tierrun/tap/tier works too!

5 things you need to know about Stripe's Test Mode

Jevon MacDonald — Thu, 17 Nov 2022 18:30:16 +0000

Stripe has two modes, Live Mode and Test Mode. Both of these represent isolated environments, and Test Mode will provide simulated responses for some requests. It's a really useful sandbox to build against as you implement your Stripe integrations. It also comes with a few gotchas.

As we encountered these issues while building Tier, we decided to create tier switch to make it easy to spin up test and preview environments.

To learn more about the switch command and how to use it to avoid these issues, please read this post and give it a try today.

Inconsistent UI

One quirk of test mode is how it shows up in the stripe Dashboard. It’s easy to miss as you move between modes.

Test Clocks will usually isolate some objects from each other in the API, however, they do not show up that way when using the UI in Test Mode.

For example, if you list all customers in the API without specifying a test clock, you will only see customers without test clocks, but in the UI, you will see all customers with and without test clocks.

To distinguish between objects with test clocks, and those without, objects associated with a test clock get orange banners and/or an icon indicating they are part of a test clock. This is helpful, but it does not show any indication of which objects are grouped together by a test clock. To see this, you’ll need a new skill to operate and see in a new dimension, as we’ll quickly see:

In the above screenshot, there are two test clocks. Which customers are on the same clock? You can probably deduce which are associated by looking at the CREATED field, but what if I advance both clocks to the same time, or what if I ran two simulations each with nearly identical timelines? It all becomes blurry in the “normal” UI mode.

The only way to find out who is associated with what clock is to drill down to the test clock’s screen.

Having to keep this in mind as you navigate around the UI requires a new mental shift. One you must enter into and switch out of rapidly to gain a sense of what you're looking at depending on the screen, and how the things you're seeing all relate to each other in this new, additional dimension.

Product and Price Debris

Products and Prices remain unisolated from subscriptions associated with a test clock, as well as with subscriptions not associated with a test clock. This means products and prices will not be cleaned up when a test clock cleans up (if you ever clean up test clocks right away or just wait for them to GC on their own).

This may not seem like a big deal, but when you’re in a trial-and-error mode, working out the kinks of your pricing model, or running an integration test, this quickly becomes a major source of friction and frustration. That is because you cannot start a new simulation in a totally clean room, so you must manually delete each product and price you modified, otherwise it may interfere with the next simulation.

Key and ID Collisions

It's important to note that deleting products and prices can not happen if they have been burned into the audit log. In this situation, you can only archive them, but their IDs and lookup keys remain. This will often cause collisions across simulations and tests.

One of my favorite things about the product and price APIs in Stripe is that you can bring your own IDs and lookup keys. This allows you to assign a unique ID or lookup key that may only be used by a single product or price, respectively, at a time.

But if you can’t delete the price or product because a subscription has burned the price into the audit log, then the next test run might get an error if attempting to create a new price with the same lookup key or product with the same ID.

We can side-step this by namespacing our keys across tests, but this means our code must be very smart and careful to not let this behavior leak into production, and know how to plumb the namespace from the request received by the user all the way to stripe, or risk clobbering or duplicating objects on write and potentially reading back the wrong one. This isn’t ideal either.

The Manual process of Deleting Test Data

With the above gotchas in mind, we probably want to think about wiping the slate clean.

Unfortunately, there is no Stripe API to start with a fresh Test Mode. To do so programmatically requires cascading delete calls to the API per object, which is a slow and error-prone process.

Even if “done right”, you’re likely to run into the problem where you can’t delete prices already burned into the audit trail (which in production is a good thing, but the reality is different for your test environments as they become impossible to clean completely).

Keep the babies. Ignore the bath water.

When you hit that “Delete Test Data” button, you’re potentially erasing the artifacts of valuable lessons learned. Lessons that could be used to refer back to as you experiment with new approaches to your pricing and billing.

To keep these for reference, a common approach is to simply sign up for a new Stripe account. Maybe we call it “test2”, but this comes with new problems:

Extra API keys to manage
Extra login credentials to manage

This also does not fix the problem of throwing out our history, because this new account could end up with data as valuable as the previous, so away we go again to sign up for a new Stripe account, and then again, and so on.

We can delay decluttering our account drop-down by triaging all of those accounts until another day.

Continuous Integration

It isn’t hard to imagine getting into a situation where changing a price or a product in the “Holy” CI Stripe account wreaks havoc on CI. This usually happens because the once “pristine” account is now out of whack according to the code expecting Stripe to look another way.

If engineering was already sheepish about making changes to the pricing model, this just further adds ammo to their argument against it, because no one wants to breathe on that code, for fear of breaking it.

Make the `switch`

Tier is your new set of power tools for Stripe. By using the switch command, you can avoid the 5 gotchas of test mode and gain the power of a PriceOps-compatible approach to monetization while building powerful new workflows on top of Stripe. This gives you the best of both worlds: The power of Tier and the reliability and reach of Stripe.

With Tier, you get powerful features such as switch along with our SDKs, metering, and feature flagging style entitlement checking.

If you aren't already a Tier user, you can get started quickly and easily.

Tier: Like Terraform, for Stripe

Jevon MacDonald — Sun, 13 Nov 2022 19:17:16 +0000

We are proud to share Tier CLI, a tool that lets you define and manage your SaaS application's pricing model following best PriceOps practices.

Pricing is the most effective lever to unlock SaaS performance. However, attempts to iterate on pricing are too often hamstrung by complicated workflows, ad hoc conventions, and hidden cross-organization dependencies.

Tier helps you to define a single source of pricing truth that can be safely and easily updated, with a simple json definition optimized for SaaS use cases. This keeps everything aligned as you find the best product-market fit.

Why we are building Tier

We are building Tier to bring sanity to the process of implementing and modifying software pricing.

It's a common pattern to build an app, API or service without any built-in logic to manage pricing, plans or customer access. At some point, it's time to charge money for your product. Eventually, you have to make a change to that pricing, either by modifying the features it grants access to or changing the price or both. Without a single source of truth, a change anywhere means making changes everywhere.

Building something maintainable

Typically there is no single point of truth for pricing in software. Do you know where to look to see which of your users are paying, what they are entitled to access, and how they will be impacted by future changes? Most of us don't.

If you are at this stage, you may be familiar with the different products out there:

Subscription Management tools
Configure Price Quote
Payment gateways
Metering services

Your app or service also likely has some type of user authentication and authorization service. You may be using a feature flagging service to manage feature enablement for end users.

Most of the time you will end up writing custom connectors between these tools. Keeping track of which tool holds the authoritative data for any given request is unwieldy.

Configuration is the foundation for a safe system

As part of this release, we are also sharing more about pricing.json and our overall configuration-driven approach to Price Operations.

Our goal is to make software price operations safe, easy and reliable.

Safe

All pricing configurations are immutable and versioned within Tier. Once pushed, a plan version and its associated data cannot be changed. This protects against one system being updated, while another gets out of sync.

Easy

Streamlined interfaces are available for pricing configuration, processing and publishing.

Reliable

A pricing change or packaging reconfiguration will not be applied unless it can be done successfully.

Introducing Tier CLI

Today's release is the Tier CLI. A powerful tool to manage your Stripe account using PriceOps patterns.

The Tier CLI will interface directly with your Stripe account in order to reliably manage your product, pricing, subscription and metering data.

You can then use a Tier SDK to implement usage limits and metering in your app or service.

Our design goal is to make using the Tier CLI easier than using Stripe itself. With the SDK implemented, you will be able to make pricing changes without having to make code changes.

"With the SDK implemented, you will be able to make pricing changes without having to make code changes."

By using pricing.json, the Tier CLI and our SDKs, you can begin safely and reliably applying pricing changes to your products and services. You can also request current limits for metered features, and report usage to stripe. The CLI will act as a sidecar in order to gracefully manage communication with Stripe.

Thank You!

We've spent a lot of time with many eager customers in the last 8 months. These testers have given us an endless amount of insight and have helped us continually improve our design and implementation of Tier, the Tier CLI and our SDKs.

There is much more coming that we are eager to share with you!

Jevon, Blake and Isaac.

Tier Hello World Demo

Jevon MacDonald — Tue, 01 Nov 2022 23:08:12 +0000

This is an example application that shows using Tier to integrate
pricing, in a way that makes it possible to implement best
PriceOps practices with a trivial amount
of effort.

The example app is exceedingly simple, but the principles are
flexible enough to easily be put into practice in much more
complicated applications.

All of the code for this demo is available on GitHub, at
tierrun/tier-node-demo.

The App

The application we'll be monetizing is a simple temperature
conversion app. If you give it a Fahrenheit temperature, it'll
convert it to Celsius, and vice versa. This is provided via a
simple site built on express.

To see the app as it exists before adding any Tier integration,
check out the pre-tier
branch.

Nothing Up Our Sleeves

Nothing described here relies on any services running on
https://tier.run, or anything at all other than Stripe.

You can think of Tier as a very fancy Stripe client that manages
metadata and connections. It sets up your system so that the
path of least resistance is also the path of optimum
PriceOps.

Setting Up Tier

First, we'll have to install the Tier
binary. On macOS machines, you
can do this with Homebrew:

brew install tierrun/tap/tier

Binaries for major architectures can be found on
GitHub.

You can also install it using go version 1.19 or later:

go install tier.run/cmd/tier@latest

Once it's installed, use the tier connect command to give Tier
access to your Stripe account. By default, Tier will only work
on test mode Stripe data, using a restricted key with permissions
that you can easily lock down.

Alternatively, you can set the STRIPE_API_KEY in the
environment, if you have a key that you'd like Tier to use.

Installing Tier SDK

In the app, we install the Tier SDK by running:

npm install tier

f32b5b4

Create Pricing Model

We create a pricing model by writing a pricing.json
file.

The pricing model is a simple free/pro scheme. Free accounts get
10 free temperature conversions per month, then they have to upgrade.

Pro accounts cost $10 per month, and get 100 conversions per
month included with that base price. Beyond that, they will be
charged $0.01 per conversion.

To do this, we define two plans in our pricing.json file with the
appropriate tiers. We're calling the feature feature:convert.

{
  "plans": {
    "plan:free@1": {
      "title": "Convert (free)",
      "features": {
        "feature:convert": {
          "title": "Temperature Conversions",
          "tiers": [
            {
              "upto": 10,
              "price": 0
            }
          ]
        }
      }
    },
    "plan:pro@1": {
      "title": "Convert (Pro)",
      "features": {
        "feature:convert": {
          "title": "Temperature Conversions",
          "tiers": [
            {
              "base": 1000,
              "price": 0,
              "upto": 100
            },
            {
              "price": 1
            }
          ]
        }
      }
    }
  }
}

The most important part is that plans are named like
plan:<name>@<version>, and features start with feature:. But
if you try to do something against the rules, Tier will give you
an error telling you what's wrong.

When we want to change this scheme, we can add a new
plan (or a new version of the free or pro plan). Any
customers still on the old version will be unaffected.

3f6e7cf

The `/pricing` Page

In order to create a nice little two-column page showing the plan
options, we can pull the highest version of each plan with the
tier.pullLatest() method, and hand that object off to our
template
to turn into HTML. I'm using EJS in this example, because it's
so dead simple to throw together an example like this, but you
can of course do the same thing with React, nunjucks, or any
other templating system.

Note: beware that this is definitely some demo magic. We're just sorting the plan versions lexically, but in practice, you'll probably want a config or some other system to say what the "public" version of any given plan is, so you don't end up with something like plan:free@zzzZZZ:final2.final.latest.final. The tier.pullLatest() method is marked as "experimental" in the Node SDK for this reason, we expect to add more utility in this area soon.

The important part is that we're not reading the file from
disk, or hard-coding the plan details into our app. Instead, we
pull from the single source of truth, and let that drive the rest
of the system.

c0a7859

Subscribing Users To Plans

Stripe doesn't really have a concept of a "plan". There are
Products which have Prices, and multiple Price objects can be
attached to a customer's subscription.

Each of those Price objects has a unique identifier. So, if you
want to treat multiple "Prices" as a "plan", you
have to keep track of them to use the right ones when creating a
subscription. As you add more tracked features, and test more
different iterations of packaging them up into plans for
customers, the complexity increases geometrically.

Thankfully, using Tier, we can just do:

await tier.subscribe(org, plan)

All of the Price objects associated with the plan
will be attached automatically.

The org is an opaque string that identifies the customer. It
must start with org:, and it must be unique, but you can use
whatever identifier you use for customers in your system already.
These are all perfectly acceptable: org:user@email.com,
org:beefcafebad1d3a, org:213415-221321-4321. There's
(almost) never any reason to deal with the Stripe Customer ID.

The plan is the plan:<name>@<version> from your
pricing.json model. You should not hard code this! In the
demo, you'll note that we get it from a POST request when the
user clicks the "Subscribe" button on the programmatically
generated pricing page.

No matter how many versions of your plans you have, the plan identifier is
all you need to create the correct subscription for your customer.

Note: you can still create subscriptions using Tier that mix
and match any prices and entitlements you like. We'll cover
that in a future "advanced usage" blog post, as it's out of
scope for a "Hello, World" app such as this.

ecb1cf1

Reporting Usage

Just like with subscriptions, rather than having to track Price objects
to know how to report feature usage to Stripe, using Tier, we just need
the org:... identifier and the feature name from your pricing model.

await tier.report(org, 'feature:convert')

The default count is 1, but if you want to report more than 1 of
something, you can just pass n as the third argument:

await tier.report(org, 'feature:morethanone', 100)

In this demo, we're reporting feature usage right at the point
of delivery. For many use cases, that's perfectly fine. But,
for example, if you're tracking download bandwidth or some other
high-volume metric, you can of course roll that up and report it
in a batch at any cadence that makes sense for your application.

The caveat, of course, is that the usage data you pull from Tier
won't be fully up to date if you haven't yet updated it.

18bfb50

Limiting Access

We said that users on the free account can only get 10
conversions per month. In order to make sure they haven't gone
over (and that they're on a plan that has access to the feature
at all!) we can call the tier.limit method, like this:

const usage = await tier.limit(org, feature)

This method will return an object with used and limit fields,
which you can check to see whether the feature should be enabled.

Again, there's no need to keep track of Customer or Price
objects, or even know what plan a user is subscribed to. Just
check whether they have access to the feature, and if so, give
them the feature.

920f8c1

Changing Plans

You can try out changing the pricing model any time you like, as
often as you like:

tier push pricing-2.json

When you do this, the /pricing page gets updated with the new
version of the plan, but importantly, the customer's plan isn't
changed. With Tier, grandparenting in your existing userbase is
the default, so you never have a situation where you try a
different price, and make everyone upset.

In fact, you could even have multiple versions of a plan living
side by side, and see which one encourages better user behavior
or gets better conversions.

Collecting Payment Info

For this, we still will need to go direct to Stripe, so that the
user can submit their credit card information directly to Stripe
from their browser, using stripe.Elements.

Thankfully, the tier.whois(org) method will give us their
Stripe Customer ID.

cd8b1ae

That's it!

In this demo, we took a working application and monetized it,
without ever having to worry about managing Stripe object
identifiers, and any future change to our pricing model is
trivial.

There's a lot more documentation available on the Tier website. Try it out, and let us know what you think!