Core concepts

Subscriptions and overage

What a paid bundle mints each period, and what happens when it runs out.

A bundle with a price is a subscription. What the end user gets for that price is a grant: an amount minted into their balance, either every period or once. Two customers on the same bundle get the same grant on the same schedule.

Attach a recurring grant to a bundle

Allotments live on the bundle. Wallet top-ups (seams users grant) are separate, always micros, never a named-credit unit. A bundle can carry several includes in its one named currency; other bundles can share that currency or use their own. See Credit systems.

seams bundles include pro monthly-credits \
  --name "Monthly credits" --unit credits --amount 30M

# SLUG              DISPLAY NAME      UNIT       AMOUNT  THEN ON DEMAND  RECURRING
# monthly-credits   Monthly credits   credits  30000000           false       true

import { Seams } from "@ourseams/sdk"

const seams = new Seams({ apiKey: process.env.SEAMS_API_KEY! })
await seams.bundles.include("pro", {
  slug: "monthly-credits",
  displayName: "Monthly credits",
  unit: "credits",
  amount: "30000000",
  price: null,
  thenOnDemand: false,
  recurring: true,
})

import os
from seams import Seams, models

seams = Seams(api_key=os.environ["SEAMS_API_KEY"])
seams.bundles.include(
    "pro",
    models.IncludeGrantRequest(
        slug="monthly-credits",
        display_name="Monthly credits",
        unit="credits",
        amount="30000000",
        price=None,
        then_on_demand=False,
        recurring=True,
    ),
)

Flag	Means
`--unit credits` · `--unit micros`	Grant your own credits, or grant money
`--amount`	How much, `30M` credits or an amount in dollars
`--price`	What this grant sells for, when it is sold separately
`--then-on-demand`	Allow overage once this grant is gone
`--no-recurring`	Mint it once at sign-up rather than every period

The order money is spent in

A call draws on the first grant that can cover it, then on-demand if you allowed it. Nothing falls through to on-demand by accident, because the last step has to be turned on.

text

monthly-tokens  30M tokens   spent
   └─ topup-credit  $4.20 left    spent
        └─ then on-demand         only if --then-on-demand

Turn overage on for one customer

On-demand is per end user, with its own ceiling, so agreeing to overage with one customer is not a change to your bundle.

seams portal on-demand alice --enable --limit 25
seams portal spending alice

await seams.subscription.onDemand({
  endUserId: "alice",
  enabled: true,
  limitMicros: "25000000",
})
await seams.subscription.show({ endUserId: "alice" })

seams.subscription.on_demand(
    end_user_id="alice",
    enabled=True,
    limit_micros="25000000",
)
seams.subscription.show(end_user_id="alice")

Grant money instead of overage

To simply add money rather than allow overage, grant it. A grant lands in the balance immediately and is spent before any overage would be. The CLI takes dollars; the SDKs take micro-dollars.

seams users grant 25.00 --user alice --reason top_up

await seams.grants.issue({
  endUsers: ["alice"],
  amountUnits: "25000000",
  reason: "top_up",
})

seams.grants.issue(
    end_users=["alice"],
    amount_units="25000000",
    reason="top_up",
)

When it runs out

The call is refused with a 402 before it reaches a provider, and the code says which ceiling stopped it. A stream already running is aborted mid-answer rather than finishing on money the customer does not have.

Code	Means
`insufficient_credit`	Available balance would not cover the reservation
`spend_limit_exceeded`	A cap or bundle spend limit is reached for this period

Credit systems

Design your own credits, packs, and plan allotments.

Worked example

Welcome credit, packs, and a monthly Pro allotment.