ShipRev keeps identity, subscriptions, metering and entitlements on one customer record: the buyer organization. An end user signs in as a member of it, it holds the subscription, your backend rules on its entitlements, and its usage is counted against the allowance its plan grants. This page names every object involved, in three layers, and follows one request through them.
The object model
The same relations as text:
Your side
Your organization ──▶ Application (project_id)
├──▶ Sign-in gate ──▶ brand domains
└──▶ SDK and API keys
What you sell (per application)
Product ──▶ Plan ──▶ Plan version ──▶ Entitlement rule ──▶ Capability
Your buyers (per application)
Buyer organization (organization_id)
├──▶ Members (end-user accounts)
├──▶ Subscription ──▶ Plan version
├──▶ Wallet
├──▶ Invoices
└──▶ Entitlement snapshot ──▶ Ruling (in your process)
Usage event ──▶ Buyer organization, CapabilityYour side
These belong to you and your team. On ShipRev Cloud you manage them in the developer console and in each application's operator console.
| Object | What it is | In the API and the SDK |
|---|---|---|
| Your organization | Your team. Members are invited and hold one of four roles, owner, admin, member or viewer, for all of your applications or for one | Roles OWNER, ADMIN, MEMBER, VIEWER |
| Application | One product you sell, with its own end users, plans and payments. On ShipRev Cloud it runs in the region it was created in, which cannot be changed later | A project: project_id |
| Sign-in gate and brand domains | The sign-in configuration your end users go through, served on a domain of yours. A gate serves one application by default; it can instead serve several of your applications, so that one sign-in covers them | Picked from the host name each request arrives on |
| SDK and API keys | Machine credentials. The SDK key is the one credential your backend needs; management API keys are for your own systems. Both can be created, narrowed to one application, rotated and revoked | Scope SDK for the SDK key |
Your team and your end users are kept apart: the operator console does not accept end-user credentials, and your end users' sign-in does not accept your team's.
What you sell
You describe what you sell once per application, in the operator console or through the Management API.
| Object | What it is | In the API and the SDK |
|---|---|---|
| Product | What a plan sells: a base product, or an add-on to one | Product type base or add-on |
| Capability | A key your code rules on and reports, such as report_exports. It is either counted or simply granted, and has an overage policy: what happens beyond the allowance | capability_key; type count or boolean; overage policy block, allow and bill, or prompt to upgrade |
| Plan | A tier of a product, such as Pro, or an add-on plan bought on top of one | Plan type primary or add-on |
| Plan version | The price, currency and billing interval of a plan, with its entitlement rules. A published version is read-only: a change is a new version, and existing subscribers stay on the version they subscribed to | version |
| Entitlement rule | What one plan version grants for one capability: an allowance, and whether it resets every month or never | Allowance and reset interval |
When a payment account is connected, publishing a plan version creates the matching product and price on your Stripe account.
Your buyers
These are created as your end users sign up, subscribe and use your product. Every one of them belongs to a buyer organization.
| Object | What it is | In the API and the SDK |
|---|---|---|
| Buyer organization | One customer of your application. Signing up creates an account, a buyer organization and the membership between them; an end user who signs up from an invitation joins the inviting organization instead | organization_id, in session tokens, rulings and usage events |
| Members | The end-user accounts in a buyer organization. One account can belong to several organizations and switch between them | account_id |
| Session token | What ShipRev issues to an end user who signs in. It names the account, the buyer organization and the application; your backend verifies it | TokenClaims from verifyToken() |
| Subscription | The buyer organization's subscription to one plan version | subscription_id |
| Invoices | One record for each payment collected on the subscription, paid or failed. A record is not changed after it is written | Invoice records |
| Wallet | A prepaid balance the buyer organization tops up, with its transaction history | One wallet per buyer organization |
| Usage event | One report of consumption from your backend: which organization, which capability, how much, when | reportUsage(), usage_event_id |
| Reservation | An amount held before work whose cost is known only afterwards, then confirmed or released; an unsettled one is reclaimed when it expires | reserve(), confirm(), release() |
| Entitlement snapshot | What the buyer organization may use right now: for each capability, the allowance of the current period and what is used. The Server SDK keeps the snapshots of all your buyer organizations in memory, as the mirror | snapshot_revision |
| Ruling | The answer to "may this organization do this now?", made by the Server SDK in your process from the mirror | Ruling: allowed, remaining, limit, source, reason |
One request, from sign-in to the usage count
Follow an end user who exports a report in your product:
- Sign-in. The end user signs in on your brand domain, through the hosted page or the React components. ShipRev issues a session token for their account, their buyer organization and your application.
- The request. Your frontend calls your backend with
Authorization: Bearer <session token>. - Who is calling. Your backend verifies the token with
verifyToken(), locally, and readsorganization_idfrom the claims. It never takes the organization from anything else the caller sends. - May they do it. Your backend calls
adjudicate()for that organization and the capabilityreport_exports. The Server SDK rules from the organization's snapshot in its mirror: the snapshot follows from the organization's subscription, the plan version it is on, and that version's entitlement rules. - Do the work and report it. If the ruling allows it, your backend does the export and calls
reportUsage()with the sameorganization_id. - The count. Your application's region counts the event against the organization's allowance for
report_exports. Later rulings show what is left inremaining.
When the organization's subscription changes, for example to a plan with a larger allowance, the region pushes the change and the Server SDK refreshes that organization's snapshot without a restart of your process. Where the rules run explains the mirror, the push and what happens while the region is unreachable; Backend and the Server SDK has the code.