DEV Community: CJ Avilla

Introducing the (experimental!) Stainless SQL SDK generator

CJ Avilla — Wed, 18 Feb 2026 15:09:31 +0000

If you run analytics, reconciliation, or batch jobs in PostgreSQL, pulling data from REST APIs usually means ETL scripts, intermediary services, or brittle sync pipelines. The data you need is one HTTP request away, but PostgreSQL is not designed to call HTTP endpoints as part of a query plan.

You can bolt on ad-hoc HTTP functions, but you lose typing, pagination ergonomics, and a spec-driven interface.

We built an experimental SQL SDK generator that turns an OpenAPI spec into a PostgreSQL extension that uses PL/Python for HTTP requests. Every API endpoint becomes a SQL function. Every response type becomes a composite type. (We explain why we chose SQL functions over Foreign Data Wrappers below.)

A SQL SDK enables users to query your API using standard SQL.

What you get: REST API calls as SQL functions

To show you how our SQL SDK generator works, we used a subset of the Stripe OpenAPI spec to generate an experimental SQL SDK. You can install it by cloning the extension repo and running ./scripts/repl or by manually building with make install.

Each API endpoint maps to a SQL function. Each resource maps to a PostgreSQL schema. The result is a typed interface to a REST API, accessible from any PostgreSQL client.

How it works

The extension is built on two layers:

PL/Python functions call a Stainless-generated Python SDK to handle HTTP requests, authentication, retries, request serialization, response parsing, and other networking concerns.
SQL function wrappers initialize the client, perform lenient type adaptation from Python objects to PostgreSQL composite types, and expose a typed SQL interface. A single client is initialized per session for performance.

Paginated endpoints employ SQL functions that use WITH RECURSIVE CTEs to repeatedly fetch pages using PL/Python function calls. Because the outer SQL function can be used inline, PostgreSQL can push down LIMIT clauses and stop requesting new pages once enough rows have been produced.

If pagination were implemented entirely in Python, PostgreSQL would buffer the full result set at the PL/Python boundary before applying LIMIT. By keeping auto-pagination in SQL, the query planner retains control over row consumption and can short-circuit additional HTTP requests.

The result is a standard PostgreSQL extension. Install with make install and load with CREATE EXTENSION:

CREATE EXTENSION IF NOT EXISTS plpython3u;
CREATE EXTENSION stripe;

Then configure with ALTER DATABASE.

For example, to configure an API key:

-- For persistent configuration (ensure your logs are secured):
ALTER DATABASE my_database SET stripe.secret_key = 'sk_test_...';

-- Or for a single session:
SET stripe.secret_key = 'sk_test_...';

Type-safe composite types, not `JSONB` blobs

Each API resource maps to a PostgreSQL schema. stripe_customer contains the customer composite type with typed fields: id TEXT, created BIGINT, email TEXT, livemode BOOLEAN.

The generator types fields where the spec is precise. Nested objects map to composite types, and arrays become typed arrays.

You get real column access instead of JSONB->>'field' casting:

-- Typed fields, not JSONB extraction
SELECT id, email, created, livemode
FROM stripe_customer.list()
LIMIT 10;

For complex parameters, the extension generates make_* constructor functions. The generator produces these from the OpenAPI spec, and they stay in sync when the spec changes.

What it looks like in practice

Create a customer:

SELECT *
FROM stripe_customer.create(
  email := 'jane@example.com',
  name := 'Jane Doe'
);

List customers:

SELECT id, email, name
FROM stripe_customer.list()
LIMIT 200;

The extension handles pagination automatically. A LIMIT 200 for an API that returns 100 items per page makes exactly two HTTP requests. Apply LIMIT as close to the API function call as possible so PostgreSQL can stop consuming rows once the limit is satisfied.

The real payoff is combining API data with your existing tables:

SELECT
  c.id AS stripe_id,
  c.email,
  o.total_amount,
  o.created_at
FROM stripe_customer.list() c
JOIN orders o ON o.email = c.email
WHERE o.created_at > NOW() - INTERVAL '30 days';

This query joins live Stripe customer data from the API with your local orders table. This replaces an ETL pipeline and staging tables with a single query.

Where SQL SDKs fit

SQL SDKs work well in many workflows, but they’re not a universal solution for every problem. They are most effective when you want to pull API data into analytical queries, scheduled jobs, or batch pipelines that already run inside PostgreSQL.

ETL and data sync

Combine materialized views with pg_cron for scheduled data pulls:

CREATE MATERIALIZED VIEW stripe_customers AS
SELECT id, email, name, created
FROM stripe_customer.list();

SELECT cron.schedule(        
  job_name  => 'refresh-stripe-customers',
  schedule  => '0 */4 * * *',
  command   => 'REFRESH MATERIALIZED VIEW CONCURRENTLY stripe_customers'
);

Every four hours, your database has a fresh snapshot of Stripe customers. Query it like any other table.

Business analytics

Ad-hoc queries that combine API data with your operational database: revenue reconciliation, customer segmentation, churn analysis. The queries run where the data already lives.

Batch LLM workflows

Select the latest support tickets, call an LLM classification endpoint, and write labels back to a table for downstream reporting. As LLM APIs publish OpenAPI specs, SQL SDKs make batch inference from SQL practical.

Where SQL SDKs are not a fit

SQL SDKs are not intended for low latency production OLTP paths. Each function call issues one or more HTTP requests, introducing network latency, rate limits, and remote failure modes. PostgreSQL’s planner optimizes relational operators over local data; it is not a cost based planner for REST APIs. Core SQL concepts such as predicate pushdown, join reordering, and index selectivity do not map cleanly to HTTP endpoints, so small query changes can result in additional remote calls. Use SQL SDKs for analytical and batch workloads where expressiveness and integration matter more than tail latency.

Why not generate Foreign Data Wrappers?

Generating Foreign Data Wrappers (FDWs) for APIs is appealing, but there are several drawbacks.

Performance is hard to reason about

A REST API FDW would hide the HTTP requests it makes.

The FDW has to determine which requests to make based on a query, making it a query planner for HTTP requests. A small change to a query could silently result in a less performant plan with many more HTTP requests. This would not be easy to debug.

An FDW over a REST API ends up being a leaky abstraction.
APIs are not always relational

FDWs shine when the data they’re modeling is relational. If the data an API provides is not relational, then it’s not well-suited for being represented as tables in an FDW.

Plain SQL functions work for any API.
A new interface to learn

Modeling API data in FDW tables would result in a different interface from the API and its SDKs, which means your users would have to learn a new API.

Plain SQL functions grouped by resource matches the existing structure of your API and its SDKs.

Current status: experimental

The SQL SDK generator works best with OpenAPI 3.x specifications that use standard request and response bodies and predictable pagination patterns. We generated a Stripe SQL SDK as the first example, but the generator is not Stripe-specific.

This is an experimental release. We're sharing it because we want feedback from developers who work at the intersection of APIs and databases. We're also expanding coverage and want to hear about OpenAPI specs that break the generator.

Expect breaking changes. This is not ready for production workloads. We are actively developing the generator and want to hear which use cases matter most to you.

If you’re using our SQL SDK generator in any capacity we’d love to hear from you. Let us know what you’re working on, if you run into any issues, or if you have feedback.

Try it out

The Stripe SQL SDK is available as a reference for what the generator produces. Clone the repo, run make install, load with CREATE EXTENSION stripe, and set stripe.secret_key.

Want a generated extension for your API? Sign up here to get early access and tell us which APIs you want to query from SQL. We are working toward supporting any API with an OpenAPI spec.

Sharper than ever: the Stainless C# SDK generator is now generally available

CJ Avilla — Tue, 17 Feb 2026 16:48:00 +0000

C# has a unique place in the programming language ecosystem. It powers enterprise software, AAA games, and even front-end web development through Blazor.

Our goal is to generate idiomatic SDKs that work great in all of these environments. Stainless provides high-quality C# code that takes full advantage of the language, and it feels like our SDKs are hand-crafted by an experienced .NET developer. We include things like strong typing, composition with LINQ, and good tooling support. These are things every C# developer expects.

It's a high bar, but it's one we managed to hit with the GA release of our C# SDK generator. Since launching our C# beta last summer, we've added more features while improving stability.

Key highlights

Full .NET Standard 2.0 support
Idiomatic types, conversions, and great editor tooling
Async enumerables for SSE/JSONL and auto-paging
Strong naming support
Minimal dependencies
Publishing to NuGet
File uploads and downloads
Sensible equality methods
Built-in generated tests
The ability to make raw requests when needed

Some noteworthy C# generator design decisions

Our goal is to generate idiomatic SDKs that feel at home in each language's ecosystem. We also strive to support advanced features and functionality, even if a particular language doesn't have native support for them. This approach shines through in some of the design decisions we made.

.NET Standard 2.0 support

The .NET ecosystem is splintered. Lots of people use .NET Standard, which has a limited subset of the full .NET functionality common across various .NET implementations, such as on vanilla Windows, UWP, Azure Functions 1.x, Xamarin, and many other runtimes. Others use .NET itself and have access to all of the modern features that make C# great.

The SDKs we generate have wide compatibility and provide the best developer experience possible. On .NET Standard 2.0, our SDKs are still full-featured, and have good DX even though some language features are missing.

On .NET 8 and above, our SDKs are fully idiomatic to the language, and take advantage of the available features.

We accomplished this by considering both stacks carefully as we built our generator. In many cases we were able to accomplish our goals with extensions which allowed us to create record classes that operate as normal classes on .NET Standard. In some cases we rely on preprocessor directives, although this is quite rare, and we ensure we only do this when truly required. As a result, our generated SDKs are still easy to read while supporting both stacks.

Amazing unions

Like many languages, C# does not support unions or sum types natively. There are a lot of tradeoffs when designing unions, and we don't have time to get into them all here. The bottom line is that every language has a unique set of constraints, so careful consideration is needed.

Our solution is for our unions to be backed internally by an object and a JsonElement. The object holds the union variant if one exists, and the JsonElement holds the raw JSON data from the API. This allows us to represent data that doesn’t match the union perfectly, which can be a problem if the OpenAPI schema deviates from the actual API. We have constructors for each possible variant, as well as an unknown variant constructor, which operates as an escape hatch. This can be useful for bypassing the OpenAPI schema when required.

To complement the constructors, we create implicit convertors from the variants. This keeps the DX light, as users don't need to wrap all of their unions. We also generate helper functions for switching and matching, which are inspired by the popular OneOf .NET library.

Basically, the goal was to make unions easy to use without compromising on type-safety or readability. Let’s take a look at an example below, where we have a Dealership SDK, which contains a Vehicle union with Car and Truck variants.

[JsonConverter(typeof(VehicleConverter))]
public record class Vehicle
{
    public object? Value { get; } = null;

    JsonElement? _element = null;

    // Gets the raw Json value, if the user needs it
    public JsonElement Json
    {
        get
        {
            return this._element ??=
                JsonSerializer.SerializeToElement(this.Value);
        }
    }

    // This property exists on both `Car` and `Truck`, so we
    // automatically bubble it up. We want the user to be able
    // to access it without having to destructure the union
    public long WheelsCount
    {
        get
        {
            return Match(
                car: (x) => x.WheelsCount,
                truck: (x) => x.WheelsCount
            );
        }
    }

    // For constructing a car variant
    public Vehicle(Car value, JsonElement? element = null)
    {
        this.Value = value;
        this._element = element;
    }

    // For constructing a truck variant
    public Vehicle(Truck value, JsonElement? element = null)
    {
        this.Value = value;
        this._element = element;
    }

    // For constructing an unknown variant
    public Vehicle(JsonElement element)
    {
        this._element = element;
    }

    // Helper method for picking a specific variant
    public bool TryPickCar([NotNullWhen(true)] out Car? value)
    {
        value = this.Value as Car;
        return value != null;
    }

    public bool TryPickTruck([NotNullWhen(true)] out Truck? value)
    {
        value = this.Value as Truck;
        return value != null;
    }

    // Exhaustive matching with no return type
    public void Switch(Action<Car> car, Action<Truck> truck)
    {
        switch (this.Value)
        {
            case Car value:
                car(value);
                break;
            case Truck value:
                truck(value);
                break;
            default:
                throw new DealershipSdkInvalidDataException(
                    "Data did not match any variant of Vehicle"
                );
        }
    }

    // Exhaustive matching with return type
    public T Match<T>(Func<Car, T> car, Func<Truck, T> truck)
    {
        return this.Value switch
        {
            Car value => car(value),
            Truck value => truck(value),
            _ => throw new DealershipSdkInvalidDataException(
                "Data did not match any variant of Vehicle"
            ),
        };
    }

    // These implicit operators are a lighter-weight way
    // to construct the union. Notice that we don't create one
    // for the unknown variant, as that's considered a more advanced
    // feature and in that case the user should be more explicit
    // about what they want.
    public static implicit operator Vehicle(Car value) => new(value);

    public static implicit operator Vehicle(Truck value) =>
        new(value);

    // ...snip...
}

This design delivers strong developer experience without sacrificing type safety or readability, and still allows developers to bypass the OpenAPI schema when needed.

Immutability by default

Many C# SDKs do not use immutable record classes even though mutability leaves room for logic bugs, thread-safety issues, and potentially sub-optimal performance. Part of making a great SDK is preventing these foot-guns wherever possible, so that developers can focus on building software.

Our C# SDKs use immutable record classes which are idiomatic and work around the issues above. Models are record classes, arrays use ImmutableArray, and dictionaries use FrozenDictionary. While looking at existing C# SDKs, we found a lot of prior art of people using mutable classes, like List and Dictionary, inside of supposedly immutable classes. We believe in a higher bar than this and made sure the data structures we generate are truly immutable.

Type-safe models with flexibility

A good SDK should make it difficult, but not impossible, to deviate from the OpenAPI spec. Usually, the spec is correct, and we want it to inform the type system and, by extension, the user. Pragmatically, sometimes the API deviates from its spec. Although there are numerous ways to work around this in the Stainless config, sometimes users still need to be able to use the SDK before this happens. This means our data model needs to support some amount of flexibility.

We work around this by backing our models with an internal read-only dictionary of <string, JsonElement> which holds the raw data. We immutably expose this to the user so that they can get the raw data if needed. Users can also construct models from their own dictionary, which allows them to bypass the schema when sending requests.

When the user doesn’t need to bypass the schema, they can use the C# properties we generate to access the model’s data. This makes the experience seamless, as if those properties were the actual backing data themselves.

Internally, we cache data so that the user doesn’t have to pay the JSON deserialization cost every time they access the same property. We do this in a thread-safe manner so that the end-user doesn’t have to think about it, and our models still appear entirely immutable.

Here’s what a model might look like:

[JsonConverter(typeof(JsonModelConverter<Cat, CatFromRaw>))]
// JsonModel holds RawData, which is the backing dictionary. It is
// also responsible for caching
public sealed record class Cat : JsonModel
{
    // Marked as required in the schema
    // (throws exception if missing)
    public required string FurColour
    {
        get
        {
            return this.RawData.GetNotNullClass<string>("furColour");
        }
        init { this.RawData.Set("furColour", value); }
    }

    // Marked as optional in the schema
    // (returns null if missing)
    public long? WhiskerCount
    {
        get
        {
            return this.RawData.GetNullableStruct<long>(
                "whiskerCount"
            );
        }
        init { this.RawData.Set("whiskerCount", value); }
    }

    // Constructor for object initializer syntax
    public Cat() { }

    public Cat(Cat cat)
        : base(cat) { }

    public Cat(IReadOnlyDictionary<string, JsonElement> rawData)
    {
        this._rawData = new(rawData);
    }

    // Constructor for bypassing the schema
#pragma warning disable CS8618
    [SetsRequiredMembers]
    Cat(FrozenDictionary<string, JsonElement> rawData)
    {
        this._rawData = new(rawData);
    }
#pragma warning restore CS8618

    // Constructor that allows setting all required members as
    // parameters, with the option of also using the
    // object initializer syntax
    [SetsRequiredMembers]
    public Cat(string furColour)
        : this()
    {
        this.FurColour = furColour;
    }

    // ... snip ...
}

You would instantiate the object like so:

Cat cat = new Cat()
{
    FurColour = "orange",
    WhiskerCount = 24
};

Or:

Cat cat = new Cat("orange")
{
    WhiskerCount = 24
};

Trusted by teams in production

The strongest proof of our SDK quality is real teams shipping production systems that depend on them. Here are a few companies using Stainless-generated C# SDKs today:

Our goal for this release was to make C# a first-class citizen in the Stainless ecosystem, with SDKs that feel at home in real .NET codebases. Our C# generator reflects that philosophy throughout: runtime-aware code generation, idiomatic models, strong typing with pragmatic escape hatches, and a focus on long-term maintainability over short-term convenience.

If you’d like to dig deeper, explore the changelog or start generating SDKs today by signing up for a Stainless account.

We’re excited to see what you build, and we’d love feedback from teams adding C# to their supported languages.

AgentLint: A Lighthouse Score for AI-Readiness

CJ Avilla — Mon, 16 Feb 2026 15:41:52 +0000

The users of the web are increasingly alien. Not humans. Not traditional crawlers. AI agents like ChatGPT browsing mode, Perplexity, Claude Code and Cowork, are actively navigating websites, reading docs, and trying to make sense of your content. And most sites are completely unprepared for them.

Your site might look great to a human. It might score 100 on Lighthouse. But when an AI agent shows up, it's probably drowning in nav bars, cookie banners, and markup soup.

We've seen this movie before

Think about accessibility. Before a11y tooling existed, making a site accessible felt vague and overwhelming. Then tools like axe and Lighthouse audits came along and made it concrete: here are the issues, here's how to fix them, here's your score. Suddenly accessibility was actionable.

Same story with internationalization. i18n felt like a massive lift until tooling made it systematic: extract strings, manage translations, lint for hardcoded text.

And Lighthouse itself turned "make your site fast" from a handwavy goal into a scorecard with specific, fixable items.

So here's the question: what's the equivalent for AI-agent readiness?

That's what I built AgentLint to be.

What it does

One command. That's it.

npx @cjavdev/agent-lint https://your-site.com

AgentLint crawls your site, runs rules across several categories, and gives you a score from 0 to 100 with a letter grade. It tells you exactly what's working, what's not, and what to fix specific violations.

The five categories:

Transport Can agents get your content in formats they prefer? Does your site respond to Accept: text/markdown? Is your robots.txt blocking AI crawlers?
Structure Is your HTML well-organized? Do headings follow a logical hierarchy? Do sections have anchor IDs agents can reference?
Tokens How efficient is your content for LLM context windows? Are pages bloated with repeated nav and footer content?
Discoverability Can agents find what they need? Do you have an llms.txt? A sitemap? An OpenAPI spec?
Agent Do you have agent-specific affordances like an MCP manifest or agent usage guides?

You get a clean report in the terminal, or pass --json for structured output you can pipe into CI.

Why I built it

I kept thinking about what makes a site "agent-friendly" and realized there was no standard way to audit it. Everyone was kind of guessing. Some folks were adding llms.txt files. Others were serving markdown. But nobody had a checklist, let alone a tool that could run it automatically.

I wanted something developers could just run — like Lighthouse, but for this new class of visitor. Point it at a URL, get a score, fix the red items. No config required, no setup, just answers.

So I built the tool I wished existed.

The rules that surprise people

Some of the checks are intuitive. Of course you should have a sitemap. But a few tend to catch people off guard:

Does your site serve markdown when asked? If an agent sends Accept: text/markdown, does your server respond with markdown instead of HTML? Most don't. But this is one of the easiest wins for agent-friendliness — agents much prefer consuming markdown over parsing HTML.

Do you have an llms.txt? This is a simple text file at your site root that tells AI models what your site is about, what content is available, and how to navigate it. Think of it like robots.txt but for AI rather than about AI.

Are your pages lean enough for context windows? LLMs have finite context. If your page dumps 15,000 tokens of nav, sidebar, and footer before getting to the actual content, agents are wasting their context budget on noise. AgentLint flags pages over a configurable token threshold.

How much of your content is boilerplate? If 40% of every page is the same nav and footer HTML, that's a ton of duplicate tokens agents have to process across pages. AgentLint measures this duplication rate.

Do you have an MCP manifest? The Model Context Protocol is emerging as a standard for agents to discover and interact with services. AgentLint checks if you've published one at /.well-known/mcp.json.

Try it

Seriously, just run it:

npx @cjavdev/agent-lint https://your-site.com

Or use it as a skill:

npx skills add cjavdev/agent-lint

Your site probably already does some of this stuff well. The score will tell you where you stand and what's worth improving. Most of the fixes are straightforward — adding a file here, tweaking a header there.

The project is open source at github.com/cjavdev/agent-lint. If you have ideas for new rules, find a bug, or just want to share your score, I'd love to hear from you.

The web is getting new visitors. Let's make sure they feel welcome.

Iterate on your SDKs locally with the Stainless Language Server

CJ Avilla — Thu, 12 Feb 2026 20:10:18 +0000

Stainless users configure their SDKs with two files: a stainless.yml config and an OpenAPI spec. Together, these files define how your API maps to generated SDKs, from resource structure and method naming to type definitions and pagination behavior. Getting them right is what makes the difference between a generated SDK that feels hand-written and one that feels auto-generated.

Until now, editing these files meant working in the Stainless Studio or pushing changes and waiting for build feedback. That workflow works, but there are some limitations. You make a change, trigger a build, wait for diagnostics, fix an issue, and repeat. For quick iterations on your config or spec, that loop is slower than it needs to be.

Today, we're releasing the Stainless Language Server, which brings the editing capabilities of the Studio directly into your local development environment. If you use VS Code, Cursor, Neovim, Zed, or any editor that supports the Language Server Protocol, you can now get real-time feedback on your Stainless config and OpenAPI spec as you type.

What the Language Server does

The Stainless Language Server understands the relationship between your stainless.yml and your OpenAPI spec. It knows which endpoints map to which resources, which schemas are referenced where, and what valid configuration options look like in context. That understanding powers a set of features that make local editing significantly more productive.

Real-time diagnostics and quick fixes

The language server analyzes your Stainless config and OpenAPI spec in real-time, surfacing errors, warnings, and suggestions directly in your editor. This helps you catch issues before running a build. When a diagnostic does appear, common issues come with an autofix you can apply with one click, and warning-level diagnostics can be suppressed with a single action.

It’s powered by the same diagnostic engine as Studio, so you get identical feedback locally without leaving your editor.

Intelligent completions

When editing your stainless.yml, the language server offers context-aware autocompletion. It suggests valid config keys, endpoint paths, and schema names drawn from your OpenAPI spec. If you're defining a new resource method, it will suggest available endpoints. If you're referencing a schema, it will complete from the schemas defined in your spec.

This is especially useful for large APIs. Instead of switching between your config and a long OpenAPI spec to find the right path or schema name, completions surface the options directly.

Go to definition and find all references

You can use "Go to definition" to jump from a reference in your Stainless config straight to the corresponding schema, parameter, or endpoint in your OpenAPI spec. Use "Find all references" to see where a particular schema or endpoint is used across both files.

For teams working with specs that have hundreds of endpoints, this navigation alone saves significant time. You don't need to manually search through a large YAML file to find where a schema is defined or where an endpoint is referenced.

Codelenses in your OpenAPI spec

Codelenses appear inline in your OpenAPI spec, showing which schemas and endpoints are already configured in your Stainless config. This gives you a quick visual overview of your API's SDK coverage without switching files. You can see at a glance which parts of your spec are represented in your SDKs and which aren't.

Live transformations

If you use Stainless Transforms to reshape your OpenAPI spec, the language server generates and updates your transformed spec in real-time as you edit your config. You can see the effect of each transform immediately, without running a separate build step.

Getting set up

Setup takes a few minutes. Install the Stainless CLI, initialize your workspace, and add the extension for your editor.

Install the CLI:

brew tap stainless-api/tap
brew install stl

Initialize your workspace:

stl init

This creates a .stainless/workspace.json file that the language server uses to identify your project and locate your config and spec files.

Install the editor extension:

For VS Code and Cursor, search for "Stainless" in the Extensions view and install it. The extension bundles the langauge server, so no separate LSP installation is needed.

For Neovim and other LSP-compatible editors, install the language server package globally via npm:

npm install -g @stainless-api/stainless-language-server

Then configure your LSP client to run stainless-language-server --stdio. The server activates for YAML and JSON files when it detects .stainless/workspace.json in your project. The setup guide has editor-specific configuration examples.

The local development workflow

With the language server running, the workflow for iterating on your SDK configuration looks like this:

Open your stainless.yml and OpenAPI spec in your editor
Edit your config with completions and inline validation guiding you
See diagnostics in real-time as you type, catching misconfigurations before they reach a build
Use go-to-definition to navigate between your config and spec
Review codelenses to check SDK coverage across your API
When you're satisfied, push your changes to Stainless for a full build

This is the same set of features available in the Stainless Studio, now running locally. For teams that prefer working in their own editor, or that want to use AI coding tools like Claude or Cursor alongside their Stainless config, the language server makes that possible.

Try it out

The Stainless Language Server is available now. Install the VS Code extension or the npm package and check out the documentation for detailed setup instructions. If you run into issues or have feedback, reach out to support@stainless.com.

Stainless CLI generator: your API, now with `--help`

CJ Avilla — Mon, 09 Feb 2026 16:14:14 +0000

You can now generate a command line tool for your API directly from your OpenAPI spec with Stainless. Enable the CLI target in the Studio to generate a command line interface with proper argument parsing, automatic pagination, and the documentation features developers expect.

Command line tools are one of the fastest ways for developers (and agents!) to interact with APIs. They're scriptable, composable, and ideal for quick experimentation and iteration. Building a high-quality CLI tool that people actually want to use, however, requires a lot of work. You need to get a lot of things right, like output formatting, pagination, shell completions, manpages, cross-platform distribution, and more. Due to the amount of time and effort that’s normally required, many API providers either don’t provide a CLI or only provide a minimal, watered-down tool that developers find wanting.

With today's release, Stainless makes supporting the CLI easier than ever. You can generate a CLI tool from the same spec that powers your SDKs and keep everything in sync automatically.

Go, CLI, Go!

Under the hood, when we generate a CLI tool for your API, it’s actually a wrapper around your Go SDK.

A common question among our earliest CLI users was, “why Go?” It’s a great question! We chose Go for several reasons, but most of them boil down to the high performance and ease of distribution Go provides.

Go compiles to native binaries with no external runtime dependencies and near-instant startup time. Your users don't have to have Go installed, all they see is a fast, efficient, and native executable.

Go also has excellent cross-compilation support, which makes it easy for you to ship builds for macOS, Linux, and Windows across multiple architectures. That makes distribution straightforward for you, and installation easy for your users.

What you get

Every CLI tool we generate follows a resource-based structure that mirrors your API:

your-project [resource [sub-resource...]] method-name --method-arg value

For example, with an API that manages people, using the CLI would look like this:

# Retrieve a person by ID
your-project people retrieve --id 123

# Create a new person
your-project people create --job "President" \
    --name.full-name "Abraham Lincoln" \
    --name.nickname "Abe Lincoln"

# List all people (paginated automatically)
your-project people list

Method names and flags use kebab-case, the --help flag gives you full documentation for any command, and man pages are generated automatically so man your-project will work out of the box for your end users.

Shell completions are included for Bash, Zsh, fish, and PowerShell, and the CLI also works on Windows using the standard --flag=value syntax.

Argumentative arguments

Argument parsing is one of those problems that looks simple until you try to create a polished implementation. Shell scripting has many quirks that make complex payloads awkward. JSON requires nested quoting that's easy to mess up. If you want tab completion and proper --help documentation, your flags need to be defined statically (which rules out infinitely nested paths like --messages.0.content.0.text).And so on.

We spent a lot of time working through the tradeoffs. The design we landed on optimizes common cases, but handles complex structures with grace when you need them.

Pass simple values with intuitive syntax familiar to command line users:

your-project users create --name "Alice" --role admin

Use dot notation for nested objects up to two levels deep:

your-project people create \
    --name.first "Abraham" \
    --name.last "Lincoln" \
    --address.city "Springfield"

For anything deeper, or for complex polymorphic types, pass YAML or JSON inline:

  # YAML
  your-project people create \
      --name 'first: Abraham, last: Lincoln'

  # JSON
  your-project people create \
      --name '{"first": "Abraham", "last": "Lincoln"}'

Pass array values with repeated flags:

your-project users update --tag admin --tag reviewer --tag owner

Pipe full payloads via stdin. JSON and YAML both work:

your-project people create <<YAML
name:
  full_name: Abraham Lincoln
  nickname: Honest Abe
job: President
YAML

You can also combine piped input with flags. Flags override values from stdin, which is useful for templating:

cat base-user.json | your-project users create --role admin

Built for AI agents

CLI tools make great interfaces for agents.

When an agent uses raw HTTP, it has to construct headers, manage authentication, serialize request bodies, and parse responses. A CLI takes care of all of that: authentication is handled using environment variables, request bodies become flags, and responses come back as structured JSON. All by default!

And, perhaps most critically, a CLI tool is self-documenting. An agent can run --help to discover what's available.

We tested this with a CLI generated for the Spotify API. Claude Code ran --help to discover the available commands, constructed valid requests, and parsed the responses without needing external documentation.

https://www.youtube.com/watch?v=sXH3WBYMKFw

The same properties that make CLIs good for humans also apply to agents:

Predictable structure: resource method --flag value
Self-documenting: --help on every command
Good error messages: clear feedback when something's wrong and suggestions for mistyped command names or flags
Standard conventions: kebab-case flags, JSON output, meaningful exit codes

Robust distribution

Building a binary is one thing, but distributing it across platforms, setting up package managers, and keeping versions in sync with your API changes is quite another.

The Stainless CLI generator plugs into the same release flow as your other Stainless SDKs. When you merge a release PR, we use GoReleaser to automatically build binaries for macOS (arm64 and amd64), Linux (arm64, amd64, 386), and Windows (arm64, amd64, 386), and each release publishes to GitHub with all compiled binaries.

For macOS users, we support Homebrew out of the box. Configure your tap repository and Stainless keeps the formula updated automatically. Your users can install your CLI with a single command:

brew install your-org/tools/your-project

We're also working on support for more package managers, like npm.

Get started today

Enable the CLI target in your Stainless config alongside your Go SDK:

targets:
  go:
    # ...
  cli:
    binary_name: your-project

Check out our CLI generator docs for more details on setup and configuration. If you have any feedback, please reach out to support@stainless.com. We'd love to hear what you think!

How to generate a TypeScript SDK from your OpenAPI spec

CJ Avilla — Mon, 09 Feb 2026 15:47:45 +0000

If you maintain a public API, you've probably faced the same question: how do you help developers (and agents) integrate quickly without forcing them to hand-craft HTTP requests, parse JSON responses, and handle edge cases on their own?

The answer is a platform, not a single artifact. SDKs, documentation, and other tools work together to shape how developers experience your API.

This guide focuses on one component: the TypeScript SDK. For JavaScript and TypeScript developers, it is often the deciding factor between choosing your API or moving on to a competitor with better tooling.

This guide covers how to generate a TypeScript SDK from an OpenAPI specification. It covers the traditional approaches, where they fall short, and how to produce a production-ready SDK that feels hand-crafted.

Why a TypeScript SDK matters for your API

Without an SDK, developers must:

Read your API documentation and manually construct HTTP requests
Handle authentication headers, query parameter serialization, and request body formatting
Parse responses and map them to their own types
Implement error handling, retries, and pagination logic from scratch
Keep their integration code updated as your API evolves

A well-designed TypeScript SDK eliminates all of this. Developers get type-safe methods with autocomplete, compile-time error checking, and built-in handling for common patterns.

Integration time drops significantly.

The payoff is faster adoption and fewer support tickets, especially when something goes wrong. Strong TypeScript types make it easier for developers and agents to detect, understand, and recover from incorrect usage.

The traditional approach: OpenAPI Generator

The legacy starting point is the open-source OpenAPI Generator. It supports dozens of languages, including TypeScript, and can scaffold a client library from your spec in minutes.

Here's the typical workflow:

# Generate a TypeScript SDK using the fetch template
openapi-generator-cli generate \
  -i path/to/openapi.yaml \
  -g typescript-fetch \
  -o ./generated-sdk

This produces a functional SDK with TypeScript interfaces for your models and a client class with methods for each endpoint.

For internal tools or quick prototypes, this works. For a public-facing SDK that represents your product, the limitations become apparent quickly.

Where basic code generation falls short

Generic, non-idiomatic code. The templates produce functional output, but method names, class structures, and patterns don't always match what TypeScript developers expect. The code feels generated, not designed.

Missing advanced features. Real APIs need pagination, retries with exponential backoff, and structured error handling. OpenAPI Generator doesn't include these. Your users must implement them manually, which leads to inconsistent behavior across integrations.

Manual maintenance burden. Every time your API changes, you re-run the generator, manually bump versions, and publish to npm. There's no built-in handling for breaking changes or automated release workflows. The onus is entirely on your team.

Limited customization. Tweaking the output requires forking Mustache templates, which quickly becomes a maintenance project of its own.

We designed Stainless for teams that run into these limits. It takes the same OpenAPI input, but optimizes for production SDKs rather than scaffolding. The table below compares the two approaches.

Feature	OpenAPI Generator	Stainless
Error Handling	Basic (`ResponseError`, `FetchError`, `RequiredError`)	Rich hierarchy with many specific error types
Retry Logic	None built-in	Exponential backoff with jitter, Retry-After support
Pagination	Returns raw paginated response	Auto-pagination with async iterators
Streaming (SSE)	Not supported	Full SSE parser with `Stream` class
API Ergonomics	Verbose method names, single object params	Clean method names, positional + optional params
Type Safety	Good (`FromJSON` / `ToJSON` transforms)	Excellent (strict mode, exactOptionalPropertyTypes)
Middleware Support	Pre/post/onError middleware	Request options per-call
File Uploads	Basic FormData/Blob	`Uploadable` type (`File`, `Response`, `ReadStream`)
Documentation	JSDoc from OpenAPI spec	Rich TSDoc with code examples
Raw Response Access	Via ApiResponse wrapper	`.asResponse()` and `.withResponse()`
Environment Config	`basePath` in Configuration	Multiple named environments and env vars
Module System	Single export pattern	Dual ESM/CJS with conditional exports

How to generate a TypeScript SDK from OpenAPI with Stainless: the recommended approach

Stainless generates TypeScript SDKs from OpenAPI that follow idiomatic language conventions and include production features like retries, pagination, and structured errors by default.

This approach comes from experience building large-scale SDK platforms, including work on Stripe’s SDK infrastructure, where maintaining high-quality, hand-crafted SDKs across many languages required far more than mapping endpoints to methods.

Getting started

You can create a new project from an OpenAPI spec in about one minute:

Sign up for Stainless. Create an account at app.stainless.com using your GitHub account, then create an organization for yourself or your company.
Create a project. Create a new Stainless project for your API by providing an OpenAPI spec. You can paste a URL to a hosted spec, upload a file, or start from an example such as the Petstore API.

Note: A Stainless project represents a single API. From one project, you can generate and manage multiple SDKs in different languages, along with related artifacts such as documentation sites, CLIs, MCP servers, or Terraform providers, all driven from the same OpenAPI spec.

Once you create the project project, Stainless generates a TypeScript SDK and opens it in the Studio inside the dashboard. Stainless also invites you to a GitHub repository containing the generated SDK code.

What you get out of the box

The generated TypeScript SDK includes retry logic, streaming, pagination, and error handling that you would otherwise build and maintain yourself. Here's what that looks like in practice, using the OpenAI Node SDK as an example.

Zero dependencies. Stainless uses the built-in fetch API for HTTP requests. The SDK works in Node.js, Deno, Bun, Cloudflare Workers, Vercel Edge Runtime, and modern browsers without pulling in a single dependency.

Full type safety. Every model, request, and response is fully typed. Developers get autocomplete for all parameters and compile-time validation of their API calls:

import OpenAI from 'openai';

const client = new OpenAI(); // Uses OPENAI_API_KEY env var by default

const response = await client.responses.create({
    model: 'gpt-5.2',
    instructions: 'You are a coding assistant that talks like a pirate',
    input: 'Are semicolons optional in JavaScript?',
});

console.log(response.output_text);

Streaming (SSE). For APIs that support Server-Sent Events, the SDK provides a Stream class with async iteration built in. No manual SSE parsing required:

const stream = await client.responses.create({
    model: 'gpt-5.2',
    input: 'Say "Sheep sleep deep" ten times fast!',
    stream: true,
});

for await (const event of stream) {
    console.log(event);
}

Auto-pagination. List endpoints return async iterators that handle page tokens automatically. Developers don't need to write pagination logic:

// Automatically fetches more pages as needed.
for await (const job of client.fineTuning.jobs.list({ limit: 20 })) {
    console.log(job);
}

// Or work with a single page at a time:
let page = await client.fineTuning.jobs.list({ limit: 20 });
for (const job of page.data) {
    console.log(job);
}

Automatic retries. The SDK automatically retries for connection errors, 408 timeouts, 429 rate limits, and 5xx server errors with exponential backoff. Developers can configure this globally or per-request:

// Configure the default for all requests:
const client = new OpenAI({
    maxRetries: 0, // default is 2
});

// Or override per-request:
await client.chat.completions.create(
    { model: 'gpt-5.2', messages: [{ role: 'user', content: 'Hello!' }] },
    { maxRetries: 5 },
);

Configuring, publishing, and keeping SDKs in sync

Beyond what's generated out of the box, Stainless handles the operational side of SDK management:

SDK configuration. A stainless.yaml file controls how your API maps to SDK methods: resource grouping, pagination schemes, method naming, and more. The dashboard includes an LSP-powered editor with autocomplete and inline documentation.

Automated publishing. Connect your npm account and new SDK versions publish automatically when your API spec changes. Stainless supports secure OIDC-based trusted publishing through GitHub Actions.

Automated regeneration. A GitHub Action in your API repository keeps SDKs in sync automatically: open a PR that changes your spec and Stainless previews the SDK diff; merge it and release PRs are opened across all your SDK repos.

Real-world examples

Stainless generates the official, production SDKs for several major API providers, collectively handling millions of API calls daily:

OpenAI Node SDK: millions of weekly downloads
Anthropic TypeScript SDK: powers Claude integrations
Lithic Node SDK: card issuing and payment processing
Modern Treasury Node SDK: payment operations platform

Conclusion

Basic code generation tools work for internal tools or prototypes. For a public SDK that represents your product, you need production-ready features: zero dependencies, full type safety, built-in pagination and retries, and automated publishing.

Stainless generates TypeScript SDKs with these features built in. The result is faster adoption, fewer support tickets, and a stronger API platform.

Ready to generate your TypeScript SDK? Get started with Stainless or read the documentation to learn more.

Is the VCR plugged in? Common Sense Troubleshooting For Web Devs

CJ Avilla — Wed, 10 Jul 2024 16:41:17 +0000

The summers of 6th through 8th grade were incredible. I grew up in North Lake Tahoe and would ride bikes with my brothers and neighborhood kids from daybreak til the streetlights came on. We'd make home videos of us attempting BMX tricks (think Baby-Gap version of the X-Games). We recorded using our family's mini-DV camcorder.

Dad would help connect the camcorder to the VCR and the TV and walk through the labyrinth of VRC remote buttons and menus so that we could transfer the videos to VHS. In the summer of 1997, my dad shared a critically important process with me that I've never forgotten and has been an invaluable framework for troubleshooting ever since. He said, "If the VCR isn't working, you should first check if it's plugged in. Start from the most foundational component (the wall receptacle), then follow the path to the next component in the chain. Ideally, isolating each component and link will ensure all pieces are working as expected. Intuit how the underlying systems work and how they interact."

See, Dad is a genius-level engineer. He ran a commercial refrigeration and appliance business for my entire childhood (which I was lucky enough to learn from). He built houses from the ground up, reincarnated cars, and was a master of all things mechanical, electrical, woodworking, and (to his chagrin) plumbing.

Customers would call and say, "My ice machine isn't making ice." Several times I'd go on jobs with him and watch him use a multimeter to test the voltages at the wall, the switch, the fans, the compressors. Is the electrical all working as expected? What about the water supply? He'd check the inlet valves, pressure, float, and door switches. Is the evaporator working as expected? Are the evaporator coils all frosty, are the condenser coils transferring heat as expected, and so-on. What about the control board? He'd isolate the problem to a single component and replace or repair it. He'd test the system and iterate until it harvested ice as expected.

Once you've isolated a specific component, you can repeat the same process for it itself. Is the component getting power? Is it receiving and/or sending the right signals that are compatible with the other components in the system? Is it damaged?

Tools for Troubleshooting

Dad has a truck full of tools: multimeters, manifold gauges, infrared thermometers (laser guns!). You too, will benefit from collecting tools to help you isolate and identify problems.

In 2011, I spent the year in Afghanistan building tactical networks that ran over fiber optics, satellite, ethernet, and radio.

A lot of my job was configuring Cisco routers and switches. The best troubleshooting tools for that job were ping, traceroute, nslookup, dig and show commands. I'd start by pinging the next hop, the next hop, and the next hop. If the pings were successful, I'd traceroute to the destination to see if the packets followed the expected path. If the packets were not following the expected path, I'd use the show commands to inspect the routing tables and check if RIP, OSPF, and BGP were doing their job correctly. Check the interface status and the logs.

For web development, the best troubleshooting tools are:

1. Logs and Print Statements:

Logs are the most important tool for troubleshooting. Logs are like the black box on an airplane. They record everything that happens in your application. They can tell you what happened, when, and sometimes why it happened. Logs are the first place you should look when something goes wrong. One school of thought is to add tons of print statements to your code to help you understand what's happening. Learn puts p and JSON.pretty_generate in Ruby and the console.log in JavaScript to print out the state of variables and the code flow. Also, use your own logging and learn about log levels to get the right information into your production logs.

2. Debuggers:

Debuggers are tools that allow you to pause the execution of your code and inspect the state of your application. You can set breakpoints in your code and step through it line by line. Debuggers are useful for understanding how your code executes and identifying the bugs' root cause. Some like print statements, and some like debuggers. I like both. I'm kinda old school for debugging ruby, and I like to use byebug. In JavaScript, I like to use debugger or the browser's built-in break statements.

Use step, next, continue, p and puts and l= to print where you are again:

require 'byebug'

def sum(a, b)
  byebug
  a + b
end

def subtract(a, b)
  a - b
end

def multiply(a, b)
  a * b
end

def my_cool_math_thing(a, b)
  byebug
  answer1 = sum(a, b)
  answer1 + subtract(a, b) + multiply(a, b)
end

my_cool_math_thing(1, 2)

3. Browser Developer Tools: Browser developer tools are built into every modern web browser. They allow you to inspect the HTML, CSS, and JavaScript of a web page, as well as monitor network requests, view console logs, and debug JavaScript. Browser developer tools are essential for debugging client-side issues.

4. REPLs: REPL stands for Read-Eval-Print Loop. A REPL is an interactive programming environment that allows you to write and execute code in real time. REPLs are useful for quickly testing code snippets and exploring language features. You can use the console in your browser's developer tools as a client side REPL and your server side framework likely has a built in REPL (e.g. rails console). Using the REPL, you can experiment with bits of code quickly to see how they behave.

5. Automated Tests: Unit tests are automated tests that verify the behavior of a small unit of code in isolation. I like to write unit tests for every bug reported by a user. This way, I can reproduce the bug in a controlled environment and verify that the fix works as expected and that we wont see a regression. There are many different JavaScript test frameworks like Jest, cypress, mocha, and jasmine. We use Rspec and Minitest for unit and integration tests in our rails application.

6. Git Bisect: I've only used this a handful of times in my career, but it can be very handy to identify when a bug was introduced. You start by telling git that the current commit is bad and an earlier commit is good. Git will then checkout a commit in the middle of the range. You test the commit and tell git if it's good or bad. Git will then checkout a commit halfway between the last and current commit. You repeat this process until you find the commit that introduced the bug. It's sort of binary search through history to find a bug.

7. Static Code Analysis: Static code analysis tools analyze your code without executing it. They can identify potential bugs, security vulnerabilities, and code smells. I like to use linters like Rubocop and ESLint to catch syntax errors and enforce code style.

8. Error Messages and Stack Traces: Unfortunately, most error messages look like the villain in a bad action movie. They are scary! Big red letters, often with cryptic language. But, error messages are your best friend. They tell you what went wrong and where it went wrong. They can be cryptic, but they often contain valuable information that can help you identify the root cause of a bug. Stack traces are like a map of the failed code execution path. They show you the sequence of function calls that led to the error. This is your map of all the components that need to be checked -- in order! Usually, I trust that third-party code is working as expected (that's like the wall receptacle, power is probably on, but sometimes you need to check the breaker panel). Do yourself a favor and set up some error monitoring and alerting tools in production so you know when an error happens for a user. We use Sentry at work and I've used Rollbar in the past.

9. Database Management Tools: If you're working with a database, you'll have tools to manage and query the database. Web dev is often CRUD (Create, Read, Update, Delete) data from a database. The database is often the lowest common denominator in the stack. You can use a database management tool to inspect the data in the database, run queries, and check for errors. You can also use the database management tool to check the status of the database server and ensure that it's running as expected. Learn enough SQL to be able to answer some basic questions -- (I still recommend SQL Zoo!). If you're using rails rails dbconsole is a shortcut to log into your database interface and start querying. Recently, I've been wrestling with some Redis memory issues and have found the redis-cli to be invaluable and have learned just enough to be dangerous.

How many users have an email with test in it?
What does the weather_days table look like?

Some redis-cli basics, for ya!

10. LLMs and StackOverflow: Learning to ask the right questions of your search engine (Google, GitHub, or StackOverflow) or LLM chat tool like ChatGPT or Claude can help you find solutions faster. The more mature your stack, the more likely there are to be other people who've run into the exact same problem you have and asked about it or created issues on GitHub. As Jon Stuart jokes about prompt engineering, it can pay to become a good "types-question-guy."

Combat Lifesaver Course

In Army basic training, we learned several basic life-saving skills like CPR, applying tourniquets, and treating for shock. In the heat of the moment, it's easy to forget the basics and get lost in the chaos. Many topics in basic training use absurdly simple frameworks so that you can remember them in the heat of the moment. For example, when you find a casualty, you're supposed to remember the ABCs: Airway, Breathing, Circulation.

A. Check their airway, is it clear? If not, clear it.
B. Check their breathing, are they breathing? If not, give them mouth-to-mouth.
C. Check their circulation, do they have a pulse? If not, stop the bleeding (apply a tourniquet) and elevate their legs.

Simple frameworks are easy to remember and can be applied in the heat of the moment. They're also easy to teach and can be applied to various problems. When your site goes down, what are your ABCs?

Side rant: shouldn’t basic life-saving courses be free to the public?! Someone make that happen!

Accelerated Learning Through Troubleshooting

In software engineering, encountering and resolving bugs is not merely an inconvenient part of the development process; it is a critical component that drives rapid skill enhancement and professional growth. I have a theory that the frequency and variety of bugs you encounter directly correlate with the speed at which a software engineer improves. My weaker theory is that this also leads to writing better, more durable code.

As an App Academy instructor, I was lucky enough to accelerate my learning by supporting web development students. While working through the curriculum, they would encounter new bugs and errors that would stump them and other TAs, and I'd get to help find and solve bugs. This experience multiplexed the opportunities for me to encounter new and different (sometimes creative and bewildering) errors and spend all day troubleshooting instead of simply building on my own and only encountering the bugs I created. I learned 6-8 times as much in about 2 years than I had in the previous 5 combined.

Diverse problems required varied approaches and solutions (e.g. comment out half the code), which broadened my problem-solving toolkit.

It deepened my understanding -- I had to understand how different components interact, leading to a more profound grasp of the entire stack.

I learned to anticipate potential issues and write more robust, maintainable code to avoid similar bugs in the future.

The experience built intuition and pattern recognition, helping identify root causes quickly.

For instance, do you want to know the most common root cause for bugs in web applications? SPELLNIG!

Because spelling is one of the most common errors, I prefer to use barewords over @instance_variables in Ruby (thanks Avdi). This way, if I misspell a variable, Ruby will raise an error instead of creating a new variable. Also, a decent reason to use TypeScript over JavaScript and linting tools like ESLint. This is a simple example of how I've learned to write more robust code through troubleshooting.

Tips and Tricks

Walk the path of the request and response - this is the way. Start from the most foundational component (the client) and follow the path to the next component in the chain (the server). Ideally, isolate each component and link to ensure all pieces work as expected. Intuit how the underlying systems work and how they interact with each other.

1. Client: Is the client sending the request as expected? Is the request being sent to the correct endpoint? Is the request being sent with the correct headers and body?

Make a change to the client code, refresh the page, and verify that you’re changing the code you think you are. (common error is making a change locally but then looking at prod or something).
Add console log statements to the top of the JavaScript files you expect to be executing, are those printed to the dev console?
Is the code to execute the request as expected? Use the browser's debugger to find the code that makes the request. Set breakpoints and inspect the request object before it's sent.
Use the browser's developer tools to inspect the request and response.
Look in the server logs to see if the request is being received.

2. Server: Is the server receiving the request as expected? Is the server sending the response as expected?

- Look in the server logs to see if the request and the expected URL, headers, and request body are being received.
- Is the expected server code executing?
  - Is the route defined that knows how to pick which code should execute based on the request path?
  - Is the code that should be executing actually executing?

3. Anywhere:

Follow the control flow, is the execution following the right branches of conditionals?
Are methods being called with the expected arguments?
Did the function return the expected value?
Are the types of objects the expected types?
Are responses from APIs and Libraries formatted as your code expects?
Are credentials and constants and environments what you expect?
Should the message be passed to the class or an instance?
Is this pointing at what you expect in JavaScript?

Call Your Shots

In pool (like the billiards kind), the badasses call their shots by naming which pocket and which balls will fall before they hit the cue ball. In software engineering, you should say what you expect to happen before you refresh the page or run a test.

If all this sounds obvious, you've been blessed with a good teacher at some point. But, it's also easy to forget when you're in the thick of a problem. It's easy to forget to check if the VCR is plugged in.

Offer free trials without an upfront payment method using Stripe Checkout

CJ Avilla — Wed, 15 Feb 2023 19:13:37 +0000

Follow along to learn how to use Stripe Checkout to collect a customer's information and start a free trial without requiring payment details. Let's get started!

Today we're going to start from a Stripe Sample, a prebuilt example with some simple views, a couple of server routes, and a webhook handler:

stripe samples create checkout-single-subscription trials

We'll use Ruby for our server, but you should be able to follow along in your favorite server-side language.

Use the arrow keys to navigate: ↓ ↑ → ← 
? What server would you like to use: 
    java
    node
    php
    python
↓ ▸ ruby

In the root of our new trials directory, you'll notice a file called sample-seed.json. We can use the Stripe CLI to execute the API calls in this seed fixture to create products and prices. If you haven’t already installed the Stripe CLI, follow the instructions in the documentation, then run the fixture:

stripe fixtures sample-seed.json

New products: starter and professional

That fixture creates two new products called starter and professional. Each product has 2 related Prices – one for monthly and one for annual. From the Stripe Dashboard, we can grab the monthly Price ID for the starter product. This price is configured to collect $12 per month, and we’ll pass this as an argument to the API call when creating the Checkout Session. Want to learn more about modeling your business with Products and Prices? Have a look at this past article.

Now we can open up our server directory and update the .env file with our new Price IDs. The .env file should look like this but have your Price IDs and API keys:

BASIC_PRICE_ID="price_1MbOQMCZ6qsJgndJy04BjDxe"
DOMAIN="http://localhost:4242"
PRO_PRICE_ID="price_1MbOQOCZ6qsJgndJrpCrN3KK"
STATIC_DIR="../client"
STRIPE_PUBLISHABLE_KEY="pk_test_vAZ3g..."
STRIPE_SECRET_KEY="rk_test_51Ece..."
STRIPE_WEBHOOK_SECRET="whsec_9d75cc1016..."

Next, we’ll install dependencies for the server.

bundle install

We can start the Sinatra server with ruby server.rb and visit localhost:4242.

Selecting the starter plan redirects the customer to Stripe Checkout, where they will enter payment details. Notice that nothing about this page signals that we're on a trial yet. That's because we have not modified the params for creating the Checkout Session to start a trial without payment method upfront.

Configuring the Checkout Session for trials

From the /create-checkout-session route, we're creating a Checkout Session and redirecting. We have an entire Checkout 101 series for you to get up to speed quickly. It's available in the documentation or here on YouTube. Here’s the code for reference:

post '/create-checkout-session' do
  begin
    session = Stripe::Checkout::Session.create(
      success_url: ENV['DOMAIN'] + '/success.html?session_id={CHECKOUT_SESSION_ID}',
      cancel_url: ENV['DOMAIN'] + '/canceled.html',
      mode: 'subscription',
      line_items: [{
        quantity: 1,
        price: params['priceId'],
      }],
    )
  rescue => e
    halt 400,
        { 'Content-Type' => 'application/json' },
        { 'error': { message: e.error.message } }.to_json
  end

  redirect session.url, 303
end

When we create the Checkout Session, we can pass a hash into subscription_data. This allows us to configure the subscription created by Stripe Checkout. Inside of subscription_data we can set trial_period_days to an integer number of days that we want to offer a trial. We also want to set payment_method_collection to if_required so we don’t require payment details upfront.

Here’s the new API call for creating Checkout Sessions:

session = Stripe::Checkout::Session.create(
  success_url: ENV['DOMAIN'] + '/success.html?session_id={CHECKOUT_SESSION_ID}',
  cancel_url: ENV['DOMAIN'] + '/canceled.html',
  mode: 'subscription',
  line_items: [{
    quantity: 1,
    price: params['priceId'],
  }],
  subscription_data: {
    trial_period_days: 14,
  },
  payment_method_collection: 'if_required',
)

Now, the button to start a subscription on the starter plan redirects customers to the Stripe-hosted checkout page. Rather than needing to enter payment details upfront, customers only need to enter their email address. This starts a free 14-day trial and then collects $12 per month after that, assuming the customer sets up payment details.

I recommend using the customer portal to enable customers to add and update payment methods on file. To see the customer portal in action, click the manage billing button on the success page after subscribing. The API call to create a customer portal session is simple; you need only specify the customer. I prefer storing the ID of the customer alongside the authenticated user, but you can also pull the customer’s ID from the Checkout Session object directly:

session = Stripe::BillingPortal::Session.create({
  customer: checkout_session.customer,
  return_url: return_url
})
# Redirect to session.url

Emailing customers when trials end

At the end of a trial, you’ll want the customer to convert to paid and enter their payment details. One way to encourage customers to come back onto your site to enter their card is to email them just before the trial ends. Stripe offers a feature to automatically email customers when trials end with the Billing scale plan. Sign up for Billing scale and configure your email settings here. Alternatively, you can listen for the trial_will_end webhook notification and send your email with a link to the customer portal.

You’ll find this view in your Stripe dashboard under Settings > Customer portal. Customers can follow the customer portal link URL to manage their billing from the portal.

post '/webhook' do
  # You can use webhooks to receive information about asynchronous payment events.
  # For more about our webhook events check out https://stripe.com/docs/webhooks.
  webhook_secret = ENV['STRIPE_WEBHOOK_SECRET']
  payload = request.body.read
  if !webhook_secret.empty?
    # Retrieve the event by verifying the signature using the raw body and secret if webhook signing is configured.
    sig_header = request.env['HTTP_STRIPE_SIGNATURE']
    event = nil

    begin
      event = Stripe::Webhook.construct_event(
        payload, sig_header, webhook_secret
      )
    rescue JSON::ParserError => e
      # Invalid payload
      status 400
      return
    rescue Stripe::SignatureVerificationError => e
      # Invalid signature
      puts '⚠️  Webhook signature verification failed.'
      status 400
      return
    end
  else
    data = JSON.parse(payload, symbolize_names: true)
    event = Stripe::Event.construct_from(data)
  end

  if event.type == 'customer.subscription.trial_will_end'
    customer_portal = "https://billing.stripe.com/p/login/test_7sIcQT9yjgqxewEdQQ"
    puts "Email customer #{customer_portal}"
  end

  content_type 'application/json'
  {
    status: 'success'
  }.to_json
end

You might be wondering how we can test that our billing logic will work as expected at the end of the 14-day trial. Test Clocks are purpose-built for testing these scenarios. To learn more about Test Clocks, check out this video. This snippet shows how you would create a test clock, create a new customer with reference to the clock, then use that customer with the Checkout Session:

    test_clock = Stripe::TestHelpers::TestClock.create(
      frozen_time: Time.now.to_i,
    )
    customer = Stripe::Customer.create(
      test_clock: test_clock.id,
    )
    session = Stripe::Checkout::Session.create(
      customer: customer.id,
      success_url: ENV['DOMAIN'] + '/success.html?session_id={CHECKOUT_SESSION_ID}',
      cancel_url: ENV['DOMAIN'] + '/canceled.html',
      # mode: 'subscription',
      mode: 'payment',
      line_items: [{
        quantity: 1,
        # price: params['priceId'],
        price: 'price_1MRMnoCZ6qsJgndJJ9JrzPgs',
      }],
      subscription_data: {
        trial_period_days: 14,
      },
      payment_method_collection: 'if_required',
    )

Next steps

Now you know how to offer free trials without payment methods upfront using Stripe Checkout. There are several benefits to this approach, chief among them increased conversion because of a lower bar of entry. You might also want to specify whether to cancel or pause the subscription if the customer didn’t provide a payment method during the trial period. No matter what your subscription use case, you can now build it with Checkout.

About the author

CJ Avilla (@cjav_dev) is a Developer Advocate at Stripe, a Ruby on Rails developer, and a YouTuber. He loves learning and teaching new programming languages and web frameworks. When he’s not at his computer, he’s spending time with his family or on a bike ride 🚲.

Handling webhooks for Stripe Connect

CJ Avilla — Thu, 26 Jan 2023 05:00:00 +0000

Did you know that you can build automations that trigger when events happen on your Stripe account? These automations are typically implemented by listening for webhook event notifications (POST requests) sent to a special route on your server called a webhook handler. While not strictly required, it’s a best practice to use webhooks for many parts of a Stripe Connect integration, including onboarding.

Background

We’ll use the term “platform account” or “platform” to talk about the Stripe Account that you will use to build your application. A “connected account” is another Stripe Account for your user that you will be facilitating payments on behalf of. We’ll also talk about “end-customers,” the customers buying from your users. To learn more about picking the right connected account types, or charge flows (direct vs. destination vs. separate charge and transfer), see the previous articles in this series.

Differences between direct account webhooks and Connect webhooks

To set up a webhook handler, you'll add a route to your server, then create a webhook endpoint in Stripe that points at your public endpoint. There are two types of webhook endpoints that you can configure:

Direct or Account webhook endpoints (events from your platform account)
Connect webhook endpoints (events from accounts connected to your platform)

There are some nuanced differences between the two:

Webhook event notifications for Connect events include the related account’s ID in the payload, but payloads for Direct endpoints do not include your own platform account ID. Here’s an example of a Connect event, which you can tell by the account field being present:

{
  "id": "evt_mCtVEgOX48Guwy",
  "livemode": true,
  "object": "event",
  "type": "customer.created",
  "account": "acct_HzrXqpz4WWwqUx",
  "pending_webhooks": 2,
  "created": 1349654313,
  "data": {...}
}

How to create a Connect webhook handler

You’ll likely need to set up two separate webhook endpoints in Stripe for your integration. You can either create two separate routes on your server (e.g., /webhooks and /connect-webhooks) or use the same route that handles event notifications for both webhook event types. You only create one Connect endpoint for all connected accounts on your platform – no need to create a new endpoint for each connected account. In this article, we’ll focus on the Connect details. If you’re new to webhooks check out the videos and find an example webhook endpoint implementation in the dashboard when creating a new webhook endpoint.

Note that each webhook endpoint you create has its own unique webhook signing secret to verify the POST request came from Stripe’s servers. We’ll see later that using the Stripe CLI for development will give you a special shared webhook signing secret that works for two endpoints.

Let’s look at a couple of examples:

When a new Payout is created, a payout.created event fires, and the payload includes an arrival_date. We can build an automation to email the connected account holders to let them know when to expect their payout to be deposited. We’ll handle this event in our Connect webhook handler.
When a new Payment is collected from an end-customer, a payment_intent.succeeded event fires, letting us know we need to fulfill the order. Assuming we’re using destination charges, this fires on your platform account.

Option 1 - Implement with two separate routes

This approach is simple and gives you good separation between your Connect webhook event handling logic and your account webhook event handling logic.

Both live and testmode events are sent to your production Connect webhook endpoints. This is so you can build test workflows for connected accounts that are connected through live mode. This means you should always check the livemode property of the event notification to ensure the event is in the correct mode.

app.post('/connect-webhook', bodyParser.raw({type: 'application/json'}), (request, response) => {
  const sig = request.headers['stripe-signature'];  
  const endpointSecret = 'whsec_YOUR_CONNECT_ENDPOINT_SECRET';

  let event;

  // Verify webhook signature and extract the event.
  // See https://stripe.com/docs/webhooks/signatures for more information.
  try {
    event = stripe.webhooks.constructEvent(request.body, sig, endpointSecret);
  } catch (err) {
    return response.status(400).send(`Webhook Error: ${err.message}`);
  }

  // We only want to run these automations for livemode…
  if (event.livemode) {
    if (event.type === 'payout.created') {
      const payout = event.data.object;
      const connectedAccountId = event.account;
      sendPayoutComingSoonEmailToConnectedAccountUser(connectedAccountId, payout);
    }
  }

  response.json({received: true});
});

app.post('/webhook', bodyParser.raw({type: 'application/json'}), (request, response) => {
  const sig = request.headers['stripe-signature'];  
  const endpointSecret = 'whsec_YOUR_DIRECT_WEBHOOK_SECRET';

  let event;

  // Verify webhook signature and extract the event.
  // See https://stripe.com/docs/webhooks/signatures for more information.
  try {
    event = stripe.webhooks.constructEvent(request.body, sig, endpointSecret);
  } catch (err) {
    return response.status(400).send(`Webhook Error: ${err.message}`);
  }

  if (event.type === 'payment_intent.succeeded') {
    const paymentIntent = event.data.object;
    // event.account is undefined since this is an event from a direct webhook endpoint.
    fulfillOrder(paymentIntent);
  }

  response.json({received: true});
});

Option 2 - Reuse the same route for both webhook event types

It can be convenient to reuse the same webhook endpoint for all Stripe use-cases. You might even want to reuse the same webhook endpoint across multiple third-party integrations. I want to share one trick for verifying webhook signing secrets when you have multiple: nesting verification for the second signature in the catch block of the first.

app.post('/webhooks', bodyParser.raw({type: 'application/json'}), (request, response) => {
  const sig = request.headers['stripe-signature'];  
  const connectEndpointSecret = 'whsec_YOUR_CONNECT_ENDPOINT_SECRET';
  const directEndpointSecret = 'whsec_YOUR_DIRECT_WEBHOOK_SECRET'
  let event;

  // Verify webhook signature and extract the event.
  // See https://stripe.com/docs/webhooks/signatures for more information.
  try {
    event = stripe.webhooks.constructEvent(request.body, sig, connectEndpointSecret);
  } catch (err) {
    if (err.type == 'StripeSignatureVerificationError'){
      try {
        event = stripe.webhooks.constructEvent(request.body, sig, directEndpointSecret);
      } catch (err2) {
        return response.status(400).send(`Webhook Error: ${err2.message}`);
      }
    } else { 
      console.error(`Webhook error: ${err.message}`);
    }
  }

  // We only want to run these automations for livemode...
  if (event.livemode) {
    if (event.type === 'payout.created') {
      const payout = event.data.object;
      const connectedAccountId = event.account;
      sendPayoutComingSoonEmailToConnectedAccountUser(connectedAccountId, payout);
    }
  }

  if (event.type === 'payment_intent.succeeded') {
    const paymentIntent = event.data.object;
    // event.account is undefined since this is an event from a direct webhook endpoint.
    fulfillOrder(paymentIntent);
  }

  response.json({received: true});
});

How to build and test webhooks locally with the Stripe CLI

For Stripe to send a POST request to your server, you need a publicly accessible URL. There are a couple of alternatives when working on building and testing webhooks locally. You could use a tunneling tool like ngrok, but we recommend using the Stripe CLI, a purpose-built tool for helping with all aspects of building your integration.

The Stripe CLI comes with the listen command that creates a direct connection between your local running server and Stripe. When events fire on your Stripe account (or connected accounts) those are forwarded to your local running webserver.

To get started with the Stripe CLI, first install it, then run stripe login to authenticate with your Stripe Account.

Then, run the listen command:

stripe listen --forward-to localhost:4242/webhook --forward-connect-to localhost:4242/connect-webhook -–latest

forward-to specifies the URL for the direct webhook handler
forward-connect-to specifies the URL for the connect webhook handler

If you are re-using the same route for both direct and connect webhook events, then you would run:

stripe listen --forward-to localhost:4242/webhook --forward-connect-to localhost:4242/webhook -–latest

latest tells the CLI to create a webhook endpoint that generates events based on the most recent API version. This is important when using strongly typed SDKs like stripe-java and stripe-dotnet which are pinned to specific API versions. By default, a webhook endpoint will be created with your Stripe Account’s default API version. If that is different from the API version your SDK is pinned to, then the SDK will not be able to properly deserialize the event payload.

That starts a listener and prints out the webhook signing secret:

In my case, the signing secret is whsec_9d75cc10168ca3f518f64a69a5015bc07222290a199b27985efe350c7c59ecde.

To see events fire, we can either take actions in our application or the Stripe dashboard that result in the event types we want to test. A simpler and more streamlined approach to testing is to use the Stripe CLI’s built-in fixtures via the trigger command. trigger runs one or many API calls to Stripe to result in a given event firing and subsequently being delivered to your webhook handlers.

We can trigger the payment_intent.succeeded event on our platform account like so:

stripe trigger payment_intent.succeeded

That creates and confirms a payment intent. Notice the logs under the stripe listen output show us the HTTP status code, request method and URL, and the ID of the events firing:

We can also trigger events on connected accounts by passing the --stripe-account option with the ID of the connected account. Here’s an example for triggering a payout.created event for a connected account with ID acct_1KPRf02R4eodYxfv:

stripe trigger payout.created --stripe-account acct_1KPRf02R4eodYxfv

You can also use the Stripe for VS Code extension, a thin UI wrapper around the Stripe CLI.

Recommendations

Store the event payload

One of the best practices when working with webhooks is to store the event payloads for later use. This is especially useful when working with Stripe Connect webhooks, as it allows you to re-process the events in case of errors or if you need to debug a specific event. I like to store event payloads in a database table with the raw payload in a JSON column and a few useful columns like processing status, processing errors, event ID, event source, and Stripe account ID.

By keeping a record of all events, you will have a historical record of all events that occurred in your platform, which gives you a full understanding of the events that have taken place, regardless of the outcome of the webhook event handler.

Only subscribe to events that you're using today

To improve your integration's performance, only subscribe to the webhook events you need, not all of them. This reduces the number of requests your webhook handler must handle. Also, if your server does not respond with 2XX status codes, Stripe will retry sending events for several days. This could result in a DDOS by the thundering herd of events received when your server comes back online.

You can easily subscribe to the events you need by selecting them in the webhooks settings in your Stripe Dashboard, or by using the Stripe API to configure your webhook endpoints. It's also important to keep in mind that webhook events can change over time, so it's a good idea to periodically review your webhook event subscriptions to ensure that you're still handling the events that are important to your integration.

You can even filter for specific event types when using the Stripe CLI listen command using the --events flag: \

stripe listen --forward-to localhost:4242/webhook --forward-connect-to localhost:4242/webhook --latest --events checkout.session.completed,account.updated

Respond immediately and then process the event with a background job

When building your webhook handler, it's important to respond immediately to the webhook event notification to avoid timing out and decrease latency. One approach is to immediately respond to the webhook event notification with a 200 status code, and then process the event in a background job. This allows your webhook handler to quickly acknowledge receipt of the event and free up resources to handle other incoming requests, while the background job can take the time needed to process the event.

Background jobs are especially useful when the event processing requires heavy computation, calls to external services, or database operations, which can take longer to complete. Additionally, it also allows you to handle events asynchronously, which improves the scalability and fault-tolerance of your webhook handler. There are several libraries available, like Bull, Celery, etc., which can help you set up background jobs in your application.

Here’s an example using bull with a redis server to queue and process Stripe webhook event notifications in the background. We’ll start by creating a queue and giving it a function that will execute for each event, then when we receive a request to the webhook endpoint, we’ll enqueue a new event to be processed with Q.add():

const Queue = require('bull');
const redisHost = process.env.REDIS_HOST || '127.0.0.1';
const redisPort = process.env.REDIS_PORT || 6379;
const queueName = 'stripe_webhooks';

// A queue for the jobs scheduled based on a routine without any external requests
const Q = new Queue(queueName, { redis: { port: redisPort, host: redisHost } });

Q.process(function (event, done) {
  // We only want to run these automations for livemode...
  if (event.livemode) {
    if (event.type === 'payout.created') {
      const payout = event.data.object;
      const connectedAccountId = event.account;
      sendPayoutComingSoonEmailToConnectedAccountUser(connectedAccountId, payout);
    }
  }

  if (event.type === 'payment_intent.succeeded') {
    console.log('💰 Payment captured!');
  } else if (eventType === 'payment_intent.payment_failed') {
    console.log('❌ Payment failed.');
  }

  done(null, { t2: jobData.value * 2, t3: jobData.value * 3 });
});

app.post('/webhooks', bodyParser.raw({type: 'application/json'}), async (request, response) => {
  const sig = request.headers['stripe-signature'];  
  const connectEndpointSecret = 'whsec_YOUR_CONNECT_ENDPOINT_SECRET';
  const directEndpointSecret = 'whsec_YOUR_DIRECT_WEBHOOK_SECRET'
  let event;

  // Verify webhook signature and extract the event.
  // See https://stripe.com/docs/webhooks/signatures for more information.
  try {
    event = stripe.webhooks.constructEvent(request.body, sig, connectEndpointSecret);
  } catch (err) {
    if (err.type == 'StripeSignatureVerificationError'){
      try {
        event = stripe.webhooks.constructEvent(request.body, sig, directEndpointSecret);
      } catch (err2) {
        return response.status(400).send(`Webhook Error: ${err2.message}`);
      }
    } else { 
      console.error(`Webhook error: ${err.message}`);
    }
  }

  await Q.add(event)

  response.json({received: true});
})

Conclusion

In this article, you learned how to build automations with Stripe Connect webhooks. You read how to test and develop locally using Stripe CLI's listen command, and how to verify webhook signatures to secure your webhook endpoint. If you’re following along with the series, we’ll use our new Stripe Connect webhook handlers in a future edition about onboarding connected accounts, so stay tuned!

About the author

Taking a cut with Stripe Connect

CJ Avilla — Tue, 24 Jan 2023 05:00:00 +0000

There are several ways to take a cut, or collect a commission on the payments flowing through your Stripe integration. In the previous articles in this series, you learned how to decide between Standard, Express, and Custom accounts types, and about the different funds flows (also known as charge types) that you can implement with Stripe Connect. Here, you’ll learn approaches to collecting a portion of the proceeds as revenue for your platform.

There are four primary ways to earn money with your platform:

Collecting application fees with direct or destination charges
Withholding a small amount of the payment when transferring funds to the connected account with destination charges or separate charges and transfers
Use Account debits to collect a one-off payment from a connected account
Collecting a recurring payment from your users as customers of your platform

Application fees

The first solution for taking a cut is to use application fees with direct or destination charges. Soon after the direct charges funds flow was released, Stripe added support for “fee splitting” with the application_fee_amount parameter. The application_fee_amount parameter can be included in an API call to create payment-related objects like a PaymentIntent or Checkout Session. Application fees are first class objects in the API and represent funds going from the connected account to the platform.

You can use the API to query for Application fees. Or you can view them from your platform dashboard – you’ll see the fees collected under Payments > All Payments > Collected fees.

Your users who have access to the Standard dashboard can see the breakdown of Stripe fees and application fees in their dashboard:

Direct charges with application fees

Here’s an example of adding an application fee of $3.21 to a direct charge for $40 to the connected account with ID acct_1LuN62ClUWl50Go4:

curl https://api.stripe.com/v1/payment_intents \
  -u sk_test_abc123: \
  -d amount=4000 \
  -d currency="usd" \
  -d payment_method=pm_card_visa \
  -d confirm=true \
  -d application_fee_amount="321" \
  -H "Stripe-Account: acct_1LuN62ClUWl50Go4"

As soon as the direct charge is complete, application and stripe fees are collected from the amount and the connected account’s pending balance increases by the net amount:

Destination charges with application fees

Here’s an example of adding an application fee of $3.21 to a destination charge for $40 to the connected account with ID acct_1KPRf02R4eodYxfv:

curl https://api.stripe.com/v1/payment_intents \
  -u sk_test_abc123: \
  -d amount=4000 \
  -d currency="usd" \
  -d payment_method=pm_card_visa \
  -d confirm=true \
  -d application_fee_amount="321" \
  -d "transfer_data[destination]=acct_1KPRf02R4eodYxfv"

Recall that a destination charge combines two actions: collecting payment on the platform account, then creating a transfer that moves money to the connected account. Here’s what the flow looks like with application fees:

From the platform account’s dashboard, you’ll find the collected fees in the same place as those collected with direct charges, here’s what it looks like in this scenario:

If your user has access to the Express dashboard, this is how they would see the fee when they log-in:

Separate charge and transfer application fees

Application fees are not supported for the separate charge and transfer funds flow. Instead, you’ll need to use one of the other approaches that we’ll outline next.

Reasons to consider using application fees to take a cut:

You use direct charges
Your users need to understand the amount the platform account collects and see that as a separate fee
You need to query the API for the list of fees you’ve collected

Transfer a smaller amount

The second solution for taking a cut is to transfer an amount less than the total payment to the connected account. You can use this with destination charges or separate charges and transfers. This approach is less explicit about the fee being collected from the platform. No objects are explicitly created representing the amount you, the platform, are collecting. Furthermore, connected accounts will only see the amount transferred into their account without any breakdown of application fees.

Destination charge with smaller transfer

Here's an example of collecting a destination charge for $40 and then transferring $35 to the connected account with ID acct_1KPRf02R4eodYxfv:

curl https://api.stripe.com/v1/payment_intents \
  -u sk_test_abc123: \
  -d amount=4000 \
  -d currency="usd" \
  -d payment_method=pm_card_visa \
  -d confirm=true \
  -d "transfer_data[amount]=3500" \
  -d "transfer_data[destination]=acct_1KPRf02R4eodYxfv"

Notice that instead of passing the application_fee_amount, we include a new transfer_data[amount] parameter with the amount we want transferred to the destination connected account.

From your platform dashboard, you’ll see links to the relevant transfer, the amount transferred, and the destination connected account where the transfer was sent:

The connected account will see that they received a payment of $35 and they don’t see any fees. Original charge amount is not shared, and this may make reporting more difficult as it does not create an application fee object.

Separate charge and transfer smaller amount

When using separate charges and transfers, you make the API call to create the payment related object, and the API call to create the transfer, so you can transfer less than the payment total. Since the most common use-case for SCT is to split payments across several connected accounts, for this example we’ll use a food delivery service example where we’ll collect a $40 payment, then send $10 to the driver’s connected account and $23 to the restaurant’s connected account.

First, we’ll collect a $40 payment from the end customer to our platform using a transfer_group:

curl https://api.stripe.com/v1/payment_intents \
  -u sk_test_abc123: \
  -d amount=4000 \
  -d currency=usd \
  -d payment_method=pm_card_visa \
  -d confirm=true \
  -d transfer_group=demo-03

The payment from the platform dashboard perspective appears as any payment collected outside of the context of Connect:

Then, using the ID of that payment intent’s latest charge as the source transaction, we’ll create a transfer for $10 to the driver’s connected account (acct_1KPRf02R4eodYxfv).

curl https://api.stripe.com/v1/transfers \
  -u sk_test_abc123: \
  -d amount=1000 \
  -d currency=usd \
  -d destination=acct_1KPRf02R4eodYxfv \
  -d transfer_group=demo-04 \
  -d source_transaction=ch_3MRIjjCZ6qsJgndJ0s4F8WUP

Next, we’ll send a second transfer of $23 to the restaurant’s connected account acct_1KP8JM2ROgShXwm9.

curl https://api.stripe.com/v1/transfers \
  -u sk_test_abc123: \
  -d amount=2300 \
  -d currency=usd \
  -d destination=acct_1KP8JM2ROgShXwm9 \
  -d transfer_group=demo-04 \
  -d source_transaction=ch_3MRIjjCZ6qsJgndJ0s4F8WUP

Again from the platform dashboard, we can see the transfer:

Here’s a diagram of the food delivery use-case. Again, the end customer pays $40, then the driver receives $10 and the restaurant receives $23. After paying the Stripe fees, the platform keeps $5.54.

To understand what was included in the transfer, you’ll need to look under Balances > Transfers then drill into the specific transfer which has links to the source transaction and the payment created on the destination connected account. \

Reasons to consider transferring a smaller amount:

You need to make transfers to several connected accounts
You don’t want your users to see the application fee amounts or to know how much the original charge was for
You do not need to query for the list of fees collected and will build your own reporting solution

Collect a one-time payment using account debits

There are a handful of use-cases where you might need to move money one-time from the connected account to your platform. You might need to recover funds for a previous refund, correct an error on the connected account’s balance, or as a one-time fee for your products or services. With Connect, your platform can debit the Stripe balance of an Express or Custom account using one of two methods: charge or transfer.

Collect a one-time payment from a connected account with a Charge

Using the lower-level Charges API (not PaymentIntents), you can use the connected account as the source and create a charge that will collect payment from the connected account to your platform:

curl https://api.stripe.com/v1/charges \
  -u sk_test_1234: \
  -d "amount"=1500 \
  -d "currency"="usd" \
  -d "source"="acct_1LuN62ClUWl50Go4"

Collect a one-time payment from a connected account with a Transfer

Recall that a Transfer moves money from one Stripe account to another. Most of the time, we use Transfers indirectly with destination charges, or directly with separate charge and transfer to move money from the platform to the connected account. In this scenario, we’ll create a Transfer to move money from the connected account back to the platform.

This time, we need to use the Stripe-Account header set to the ID of the connected account. This means we’re creating the Transfer on the connected account (acct_1LuN62ClUWl50Go4) and the destination is the platform (acct_1EceeUCZ6qsJgndJ).

curl https://api.stripe.com/v1/transfers \
  -u sk_test_4eC39HqLyjWDarjtT1zdp7dc: \
  -H "Stripe-Account: acct_1LuN62ClUWl50Go4" \
  -d "amount"=1500 \
  -d "currency"="usd" \
  -d "destination"="acct_1EceeUCZ6qsJgndJ"

Note that account debits only work for Express and Custom account types and there are several other restrictions you’ll need to review in the documentation.

Reasons to consider using account debits:

One-off payments from the connected account to the platform

Collect recurring payments from your users as customers

While the title of the article references taking a cut or commission on payments you facilitate, you might want to monetize your platform without commissions. Let's say you want to collect $10 USD each month from your users, owners of the connected accounts with Stripe Billing. This is not possible if you only have the connected account. You’ll need to collect payment details, create a Customer, and create a Subscription instead.

When integrating with Stripe's Billing APIs for recurring payments, it's important to keep in mind that creating a Subscription requires having a Customer object, and you cannot use the connected account for this. A Customer and an Account are completely separate objects in Stripe's API, and there is no way to turn one into the other or "share" information between them.

The most common approach for platforms using Billing is to create a separate Customer object and handle all the Billing logic like payment method updates, handling payments, and proration using Subscriptions. To mitigate the confusion between the Account and the Customer objects for your users, you can use metadata on both the Customer and Account to track the association.

If you’re interested in taking this approach, take a look at the SaaS fundamentals series to get started.

Consider collecting payment from your users as customers if:

You want to collect $N each month
You do not want to collect a small part of each transaction

Conclusion

Your approach to taking a cut from payments your platform facilitates will depend on a number of factors. Here’s a summary of my recommendations:

If you want your users to see the fees collected, use application fees with the application_fee_amount parameter for direct or destination charges.

If you want to obfuscate the charge or fee totals, use transfers with amounts less than the payment total.

If you want to charge a fixed monthly fee, or a usage based amount every month, create platform customers for each of your users and charge them with a Stripe Billing subscription.

About the author

Picking the right charge type for your Stripe Connect platform

CJ Avilla — Mon, 23 Jan 2023 16:23:15 +0000

Stripe Connect is a set of APIs for routing payments between multiple parties. Connect can collect payments from end customers and send that money to connected accounts. There are several options for moving money, sometimes called funds flows or charge types. In this article, we'll explore the different options: Direct, Destination, and Separate Charges and Transfers (SCT).

Choosing the correct charge type for your integration can significantly impact user experience, responsibility for chargebacks and risk management, and reporting. We'll compare and contrast the different flows, highlighting their key features, use cases, and potential pitfalls. We'll also cover which connected account configurations work best with each funds flow. Whether you're a seasoned developer or new to Stripe Connect, this guide will give you the information you need to decide which suits you.

Background

We'll use the term "platform" or "platform account" to refer to the Stripe account you're using to build your platform or marketplace. The "connected account" is the Stripe Account of your user, the person or the business you are enabling. When a payment is collected from an end customer, that payment can only "settle" on one account, which is sometimes referred to as the merchant of record or the settlement account. The settlement account's details are the ones that appear on the end customer's statement. Money can also move between Stripe accounts via either Transfers or Application Fees. These mechanisms allow you to split payments between one or many recipients and to collect fees during the transaction.

Direct charges

Direct charges were introduced as the first Connect funds flow, and it's the easiest to reason about. Direct charges allow platforms to collect payments from end customers, with the payment going directly to a particular connected account.

Characteristics of direct charges:

Stored on the connected account - we say the connected account is the settlement merchant.
The connected account pays Stripe processing fees.
The connected account is responsible for handling disputes and managing refunds. The platform can help, but the end responsibility lies on the connected account.
Most compatible with accounts with access to the Standard dashboard.
Customers directly transact with your user, often unaware of your platform's existence.
A single connected account (your user) is involved in the transaction.
You, the platform, may be insulated from fraud and disputes, depending on who is responsible for losses on the connected account. For Standard, Stripe manages fraud and losses on the connected account.
Suitable for platforms that are infrastructure providers for other businesses (ex. Shopify or Squarespace)
Only supported for connect accounts with the card_payments capability

Direct charges are made by adding a Stripe-Account header to an API call when creating payment-related objects like PaymentIntents or Checkout Sessions. For example, one of the connected accounts for my platform has ID acct_1LuN62ClUWl50Go4. Here's an example API call to create a PaymentIntent for $20 USD using a direct charge that will flow into the connected account:

curl https://api.stripe.com/v1/payment_intents \
  -u sk_test_abc123: \
  -d amount=2000 \
  -d currency=usd \
  -d payment_method=pm_card_visa \
  -d confirm=true \
  -H "Stripe-Account: acct_1LuN62ClUWl50Go4"

Because direct charges are distributed across connected accounts on your
platform, it can be challenging to query for and report on aggregate statistics
related to direct charges. As a platform owner, you have to go to each
connected account and see the direct charges made on that account.

There are several reasons why you should avoid using Direct charges with
Express or Custom account types:

Addressing disputes becomes increasingly tricky through the dashboard.

The Express dashboard does not support dispute management, so you, as the
platform, will need to handle disputes for Express accounts or build dispute
management in your own platform dashboard. This involves building complex state
management to collect evidence and submit it.

When you're starting out and only have a couple connected accounts, it's
relatively easy to check each account for the necessary charge and then address
a dispute. However, finding the correct charge and dispute becomes more
challenging as your business scales.

You, as the platform, have to cover negative balances of your Express and Custom accounts.

Refunds and disputes for Direct Charges come from the connected account's balance, and Stripe fees (which are paid by the connected account for Direct Charges) are not returned, making it more likely for a connected account to have a negative balance. You are responsible for your Express and Custom accounts' negative balances, so Stripe has to hold a reserve from your available balance to cover the negative balances across your connected accounts. You can read more about reserve balances in the documentation.

Direct charges require more work to manage Radar Rules across all connected accounts.

Your platform account Radar rules only apply to your charges, not charges
directly created on connected accounts. This is a problem because Direct
Charges use the connected account's rules, and Express and Custom accounts
cannot set their own Radar rules, so you, as the platform, would need to
configure the rules for every connected account.

Example use-cases for Direct charges:

An e-commerce platform like Shopify or Squarespace
An accounting platform that enables invoice payments like Freshbooks

Destination charges

The second Stripe Connect funds flow we'll discuss is destination charges. Destination charges allow platforms to create a charge and a transfer object with one API call. Instead of using the Stripe-Account header, you make an API call to create a payment-related object with the transfer_data.destination set to the connected account's ID. This creates an atomic transaction, where the charge and transfer are made at the same time.

This one API call will create the payment on the platform, then create a transfer moving $20 USD to the destination account.

curl https://api.stripe.com/v1/payment_intents \
  -u sk_test_abc123: \
  -d amount=2000 \
  -d currency=usd \
  -d payment_method=pm_card_visa \
  -d confirm=true \
  -d "transfer_data[destination]=acct_1LuN62ClUWl50Go4"

Characteristics of destination charges:

The charge is on the platform account
Best funds flow for Express and Custom account types
Customers transact with your platform for products or services provided by your user
A single connected account is involved in the transaction
The platform can reverse the transfer independently of refunds/disputes on the charge
The platform has more control but is more involved in the flow of funds
Suitable for platforms that are a unified business
Uses the Stripe payment fee pricing of the platform
Allows the platform to share customers and their payment methods across connected accounts

Example use-cases for destination charges:

A ride-hailing service like Lyft
A services platform like Thumbtack
Platforms for creators
Tipping and affiliate marketing programs

In this example, you, the platform, still pay the Stripe processing fees. Still, the entire amount was sent to the connected account, so your platform is "out" the processing fees in this example. Stay tuned for the next article, where we'll talk about application fees and approaches to splitting the payment between your platform and the connected account so that you can take a cut.

Separate Charges and Transfers (SCT)

Separate charges and transfers were introduced to collect payment and transfer proceeds at different times. This funds flow is only supported if both your platform and the connected account are in the same region. For example, both in Europe or both in the U.S.

Using separate charges and transfers requires at least 2 API calls. One to create the payment-related object like a PaymentIntent or Checkout Session, then a second to create a Transfer to move money from the platform to one or more connected accounts. You can even create several Transfers to split a payment between several connected accounts.

First, we'll collect payment from the end customer to our platform (note that this does not use the Stripe-Account header):

curl https://api.stripe.com/v1/payment_intents \
  -u sk_test_abc123: \
  -d amount=2000 \
  -d currency=usd \
  -d payment_method=pm_card_visa \
  -d confirm=true \
  -d transfer_group=demo-01

Then, we'll transfer part or all of those funds to the connected account:

curl https://api.stripe.com/v1/transfers \
  -u sk_test_abc123: \
  -d amount=2000 \
  -d currency=usd \
  -d destination=acct_1LuN62ClUWl50Go4 \
  -d transfer_group=demo-01

(If you're curious about the transfer_group parameter, stay tuned!)

Characteristics of SCT:

The charge is stored on the platform
The platform pays the Stripe processing fees
Express or Custom account types work best because it gives the platform more flexibility, for instance, when it comes to handling fraud and disputes
It should only be considered after ruling out destination charges

SCT is ideal in any of these instances:

Multiple connected accounts are involved in the transaction
A specific connected account isn't known at the time of charge
Transfer can't be made at the time of charge

Example use-cases for SCT:

An e-commerce marketplace that allows a single shopping cart for goods sold by multiple businesses
A delivery service, like Instacart, that needs to split a payment between a store (the source of the items being delivered) and a delivery person

Transfer group

Think carefully about the 2 API calls we just made. If we leave out the transfer_group parameter, there is no way to know which payment is related to the transfer. Another issue you'll encounter with those API calls is related to pending funds. Depending on the payment method used, funds could take a while to "settle" into an account. By default, you can only transfer funds that have been settled. So enter two new API parameters that we can use to address these issues: transfer_group and source_transaction.

The transfer_group parameter is used to associate charges with transfers. It is primarily used for reporting purposes, allowing you to query all transactions by transfer group through the API.

Let's update our API calls to include a transfer group:

curl https://api.stripe.com/v1/payment_intents \
  -u sk_test_abc123: \
  -d amount=2000 \
  -d currency=usd \
  -d payment_method=pm_card_visa \
  -d confirm=true \
  -d transfer_group=demo-01

curl https://api.stripe.com/v1/transfers \
  -u sk_test_abc123: \
  -d amount=2000 \
  -d currency=usd \
  -d destination=acct_1LuN62ClUWl50Go4 \
  -d transfer_group=demo-01

⚠️ Note that for transfer groups, you must be configured to use manual payouts or a combination of automatic payouts and the source_transaction parameter to ensure the platform has sufficient funds to cover the transfer.

You can group multiple charges with a single transfer or multiple transfers with a single charge. You can also perform transfers and charges in any order.

Source transaction

The source transaction parameter helps transfer pending funds, allowing you, the platform, to make a PaymentIntent and immediately create a transfer, even if the charge is still pending.

You can use this parameter to transfer funds from a charge before they are
added to your available balance. A pending balance will transfer immediately
but the funds will not become available until the original charge becomes
available. See the Connect documentation for
details.

curl https://api.stripe.com/v1/transfers \
  -u sk_test_abc123: \
  -d amount=2000 \
  -d currency=usd \
  -d destination=acct_1LuN62ClUWl50Go4 \
  -d transfer_group=demo-01 \
  -d source_transaction=ch_3MPoP2CZ6qsJgndJ1u1Uhi01

Note that you'll need to pass the ID of the underlying Charge, not the ID of the PaymentIntent.

Conclusion

Stripe Connect provides a range of funds flows that you can use to route payments between multiple parties. Each has different use cases, advantages, and drawbacks. Direct charges are the easiest to implement but are limited to Standard account types and have difficulty with dispute management and reporting. Destination charges are ideal for Express and Custom account types and provide more control. Finally, separate Charges and Transfers (SCT) require at least two API calls and are best used when multiple connected accounts are involved in the transaction. I recommend weighing the advantages and disadvantages of each funds flow and deciding which is best for your integration. Also, be sure to account for reserves and use transfer_group and source_transaction where applicable.

The charge-type decision comes down to a few factors:

Who does the end customer think they are doing business with? I.e., who's the settlement merchant that will appear on the statement.
- As a Lyft passenger, I expect to be doing business with Lyft and not the driver. (SCT or Destination)
- As a customer buying shoes from a Shopify store, I expect to be doing business with the store. (Direct)
Will the payment need to be split among multiple recipient connected accounts? (SCT)
Who should pay the Stripe fees?

About the author

Standard vs. Express vs. Custom account types for Stripe Connect

CJ Avilla — Fri, 06 Jan 2023 21:50:12 +0000

In this series, you’ll learn all about Stripe Connect, the set of Stripe APIs and tools for building a platform or marketplace to route payments between multiple parties.

If you’re using Stripe Connect, you’ll need to create an account (called a "connected account") for each user who collects payments with (or accepts payouts from) your platform. You’ll do this every time a user signs up for your platform. The type of account you choose for your user will determine the development work required for the Stripe integration you need to build (options range from Stripe-hosted to completely custom) and what operational responsibilities you’ll have (like handling chargebacks and supporting your users). It’s possible to mix and match account types for your platform if you are solving for different use-cases or segments. There are three account types to choose from with Connect, each designed for different needs: Standard, Express, and Custom. We’ll first compare and contrast the integration effort and operational overhead, then close with some recommendations.

💰 Keep in mind, there is an additional cost for using Express or Custom account types.

Integration effort

When it comes to integration effort, Standard and Express accounts are the most straightforward options with Standard accounts requiring the least amount of work to integrate. However, if you want more control over the user experience, you may want to consider Custom accounts. While Custom accounts allow you to whitelabel the entire experience, they require significantly more development effort to implement.

Here are more details about the integration requirements for each account type:

Onboarding

Stripe-hosted onboarding supports all account types. The hosted onboarding integration requires at least two API calls.

Create a connected Account. Note that you can pre-populate many account details if you like the user’s website, support phone number, mailing address, etc. that way, they don’t need to re-enter those details when onboarding.
```
const account = await stripe.accounts.create({type: 'standard'});
```

Create an Account Link that redirects the user through the Stripe hosted onboarding flow:

const accountLink = await stripe.accountLinks.create({
  account: account.id,
  refresh_url: 'https://example.com/reauth',
  return_url: 'https://example.com/return',
  type: 'account_onboarding',
});
// redirect to accountLink.url

Connect Onboarding makes it easy to onboard merchants to your platform by providing conversion-optimized, pre-built user interfaces. This means you can easily get your merchants set up without having to worry about the complexity of building your own identity verification and onboarding flows. Plus, Connect Onboarding helps you minimize compliance and operational issues.

I recommend using Connect Onboarding for all account types. It’s worth calling out that you can technically build your own custom onboarding flow for Custom accounts and use the API to update details about the account and check for a list of additional verification requirements. Localizing a custom form and nailing all of the identity verification flows for multiple countries is quite a heavy lift so unless you have significant engineering resources, I would default to using Connect Onboarding.

Automatic updates for new compliance requirements

Global compliance requirements and rules do change over time. For Standard and Express accounts, Stripe will proactively reach out and collect information about your accounts whenever requirements change.

If you’re using Custom account types with a bespoke onboarding flow and haven’t integrated with Connect Onboarding, you’ll need to invest development resources to make updates as compliance requirements change over time. However, if you use Connect Onboarding for Custom accounts, you can easily collect onboarding and verification information from your users and save yourself the hassle of constantly updating your onboarding form. Plus, Connect Onboarding can help you stay up-to-date with the latest compliance requirements without any extra effort on your part. Just make sure to follow best practices for communicating changes to your users, as outlined in the guide for Custom accounts.

Integration effort is one the most heavily weighted factors when deciding which Stripe Connect account type to choose. Most startup and growth companies have the bandwidth and resources to implement and maintain Standard and Express accounts. If you don’t have a team of engineers to dedicate significant bandwidth to maintaining a Custom integration, I recommend Standard or Express.

Operational responsibilities

Another important consideration is who handles the operational responsibility day to day. For instance, are you the platform liable for fraud and disputes related to payments for a connected account? What type of dashboard can the connected account access to view payments, issue refunds, handle disputes, and update their information? Who is responsible for supporting connected account users when questions arise? Some of the following details differ depending on the charge type (direct vs destination) which we’ll cover in another article. Just know that one charge type may have different operational requirements than another charge type.

Fraud and dispute liability

If you’re trying to decide between Standard and Express accounts, this is likely the tie breaker.

For Standard accounts, the connected account owner (your user) is responsible for dealing with fraud and disputes*. For Express and Custom accounts, you as the platform are ultimately responsible for dealing with fraud and disputes.

Understanding the dispute process and how to handle fraud is part of any online business. Standard accounts are more suited for experienced online businesses, whereas Express accounts are ideal for businesses at any level of experience.

*this may shift depending on the charge type used.

Dashboard access

Standard accounts are conventional Stripe accounts where the account holder (your user) is able to log in to the Dashboard and can process charges on their own. If you want to obfuscate the relationship between the connected account holder and their end user for any reason, Standard is likely not a good fit.

Express accounts can only use the Express Dashboard, a simplified Stripe-hosted interface. From the Express Dashboard, your users can view their available balance, see upcoming payouts, and track their earnings in real time. The Express Dashboard does not have all of the same features as the Standard Dashboard.

Custom accounts do not have access to a Stripe-hosted dashboard. You’ll need to build custom interfaces into your application for your users to handle any operational tasks related to running their business.

User support

All support questions about a Custom connected account are handled by you, the platform. For Standard and Express accounts, some questions can be answered by Stripe and others will be handled by the platform. For instance, as identity verification requirements shift and change, Stripe will proactively reach out to your users to ensure the information on file stays compliant with local regulations.

Recommendations

Absent a compelling reason for a bespoke integration and lots of resources to build and maintain a Custom Connect integration, I would default to either Standard or Express. Assuming the platform I’m building is open to handling fraud and disputes, the platform decision between Standard and Express comes down to the relationship I expect users to have with end customers. Will my users, the owners of the connected accounts, need a long standing relationship with their customers or will their relationship be one-off, and transactional in nature? If so, do I expect my customer base to be savvy enough (or teachable enough) to handle fraud and disputes and trusted with the ability to charge the end customer manually. If I’m working with online business savvy folks who maintain long-running relationships with their end customers, I’d choose Standard. If I’m working with any internet user who has a one-off relationship with end customers or if I want to prevent them from charging end customers, then I’d lean towards Express.

DEV Community: CJ Avilla

Introducing the (experimental!) Stainless SQL SDK generator

What you get: REST API calls as SQL functions

How it works

Type-safe composite types, not JSONB blobs

What it looks like in practice

Where SQL SDKs fit

ETL and data sync

Business analytics

Batch LLM workflows

Where SQL SDKs are not a fit

Why not generate Foreign Data Wrappers?

Current status: experimental

Try it out

Sharper than ever: the Stainless C# SDK generator is now generally available

Key highlights

Some noteworthy C# generator design decisions

.NET Standard 2.0 support

Amazing unions

Immutability by default

Type-safe models with flexibility

Trusted by teams in production

AgentLint: A Lighthouse Score for AI-Readiness

We've seen this movie before

What it does

Why I built it

The rules that surprise people

Try it

Iterate on your SDKs locally with the Stainless Language Server

What the Language Server does

Real-time diagnostics and quick fixes

Intelligent completions

Go to definition and find all references

Codelenses in your OpenAPI spec

Live transformations

Getting set up

The local development workflow

Try it out

Stainless CLI generator: your API, now with `--help`

Go, CLI, Go!

What you get

Argumentative arguments

Built for AI agents

Robust distribution

Get started today

How to generate a TypeScript SDK from your OpenAPI spec

Why a TypeScript SDK matters for your API

The traditional approach: OpenAPI Generator

Where basic code generation falls short

How to generate a TypeScript SDK from OpenAPI with Stainless: the recommended approach

Getting started

What you get out of the box

Configuring, publishing, and keeping SDKs in sync

Real-world examples

Conclusion

Is the VCR plugged in? Common Sense Troubleshooting For Web Devs

Tools for Troubleshooting

Combat Lifesaver Course

Accelerated Learning Through Troubleshooting

Tips and Tricks

Call Your Shots

Offer free trials without an upfront payment method using Stripe Checkout

New products: starter and professional

Configuring the Checkout Session for trials

Emailing customers when trials end

Next steps

About the author

Handling webhooks for Stripe Connect

Background

Differences between direct account webhooks and Connect webhooks

How to create a Connect webhook handler

Option 1 - Implement with two separate routes

Option 2 - Reuse the same route for both webhook event types

How to build and test webhooks locally with the Stripe CLI

Recommendations

Store the event payload

Only subscribe to events that you're using today

Respond immediately and then process the event with a background job

Conclusion

About the author

Type-safe composite types, not `JSONB` blobs