ShipRev Blog https://shiprev.dev/blog Notes on the design behind ShipRev: identity, subscriptions, metering and entitlements on one customer record. en Designing Identity, Subscriptions, Metering and Entitlements Around One Database Transaction https://shiprev.dev/blog/four-domains-single-transaction https://shiprev.dev/blog/four-domains-single-transaction Sat, 10 Oct 2026 00:00:00 GMT ShipRev Core Invariants Why ShipRev is designed to keep the four pieces of commercial state for a SaaS product in one process and one PostgreSQL database, written to in one transaction. A SaaS team that sells several plans with quotas usually keeps the state behind them in several places: a sign-in service, a payment provider, a usage counter and its own code.

ShipRev is designed to hold that state on one customer record, in one process and one database, so that a change to one of the four is written in the same transaction as the others. Here is how the four are meant to fit together:

  1. Catalog and tiers: products, capabilities and the tiers that bundle them, published as versions.
  2. Subscriptions: subscription state, invoices and prepaid balances, connected to your own Stripe account.
  3. Metering: usage events recorded against each customer, with reservations that are confirmed or released.
  4. Identity: end users, the organizations they belong to, and the boundary between one customer's data and another's.

Changes to configuration, subscriptions and entitlements are designed to be recorded in an append-only change log, so that each change can be traced afterwards.

ShipRev has not been released. This post describes its design, not a product you can use today.

]]> Why Distributed Billing and Metering Strain Under AI Agent Workloads https://shiprev.dev/blog/why-single-process-operational-plane https://shiprev.dev/blog/why-single-process-operational-plane Sat, 10 Oct 2026 00:00:00 GMT ShipRev Architecture A look at how separate usage meters, payment webhook queues and tenant auth services can drift apart under concurrent agent workloads, and the single-transaction design ShipRev takes instead. When engineers start building SaaS products around autonomous AI agents, the default instinct is to decompose the commercial side into separate services:

  • A payment provider for payment collection and subscription state;
  • A hosted identity service for multi-tenant organizations;
  • A time-series or analytics database for raw token metering;
  • HTTP webhooks and background workers to wire them together.

Where the asynchronous design strains

In a product driven by people clicking through a UI, this architecture often holds up, because requests arrive at human speed. Agent workloads behave differently:

  1. An agent workflow can start many tool calls at once;
  2. Each call can consume tokens and third-party API credits at the same time;
  3. Webhooks from a payment provider arrive after a delay you do not control;
  4. By the time a webhook marks a customer as out of quota, concurrent calls may already have spent more than the plan allows.

The single-transaction design

ShipRev is designed to address this failure mode by keeping the catalog, subscriptions, metering and identity in one process and one PostgreSQL database:

  • Balance checks and usage deductions are designed to run in the same database transaction;
  • Entitlements are designed to be read from the same records as the subscriptions that grant them.

ShipRev has not been released. This post describes its design, not a product you can use today.

]]>