Skip to content

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.

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 1

Keys 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.

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
});

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.