Automating setup
Everything you can do in the Console you can do through the API with a full-scope key. A common setup is: define plans once from a script, then let your billing code assign subscriptions when payments succeed.
Use a development environment’s key while you build. Production has its own keys and its own data.
Define features and a plan
Section titled “Define features and a plan”import { Seal0 } from "@seal0/sdk";
const seal0 = new Seal0({ apiKey: process.env.SEAL0_ADMIN_KEY! }); // full scope, server-side only
await seal0.createFeature({ key: "max_projects", name: "Projects", value_type: "number" });await seal0.createFeature({ key: "sso", name: "Single sign-on", value_type: "boolean" });
await seal0.createPlan({ key: "pro", name: "Pro" });await seal0.putDraft("pro", { max_projects: 10, sso: true });const version = await seal0.publishPlan("pro"); // version 1Keys can’t be reused. When a script may run twice, check with getFeature or getPlan first, or catch 409 feature_key_taken and 409 plan_key_taken.
Assign a subscription when a payment succeeds
Section titled “Assign a subscription when a payment succeeds”// In your payment provider's webhook handler, after verifying it:await seal0.upsertCustomer(customerId); // your own opaque ID, such as "cus_test_0001"await seal0.assignSubscription(customerId, { plan: { key: "pro" }, // no version: the latest published status: "active", current_period_start: periodStart, current_period_end: periodEnd,});Assigning replaces the Customer’s current subscription and keeps the old one in the history. On renewal, move current_period_end forward with updateSubscription.
When a payment fails or a Customer cancels
Section titled “When a payment fails or a Customer cancels”await seal0.updateSubscription(subscriptionId, { status: "past_due", grace_ends_at: graceEnd });
// Cancel at the end of the period: access continues until cancel_at.await seal0.updateSubscription(subscriptionId, { status: "canceled", cancel_at: periodEnd });See Subscriptions for which timestamps each status needs.
Give a Customer an exception
Section titled “Give a Customer an exception”await seal0.createOverride(customerId, { feature_key: "max_projects", value: "unlimited", starts_at: new Date().toISOString(), expires_at: trialEnd, // optional; omit to keep it until revoked});Retries are safe
Section titled “Retries are safe”Every SDK mutation carries an idempotency key that’s reused across retries. A webhook handled twice by your own code is a different matter: pass { idempotencyKey: event.id } so the second delivery replays the first result instead of applying it again.