Stigg Subscriptions — Lifecycle Operations

This skill covers day-to-day subscription operations: provision, preview, update, cancel, trials, multi-subscription products, and plan-version migration (moving an existing sub from plan v1 to plan v2 after a publish).

Before You Start

Per the umbrella stigg skill: search first. Provisioning options, billing-cycle behavior, and trial-conversion semantics evolve. Open the relevant SDK / REST page (Mintlify Stigg docs MCP) before authoring.

The Operation Map

Provision a Subscription

Minimal backend call

const sub = await stigg.provisionSubscription({
  customerId: 'customer-123',
  planId: 'plan-pro',
  billingCountryCode: 'US',           // required for paid plans w/ price localization
});

The provisioning surface includes (see references/provisioning.md for the full list):

• Resource ID — required when the product allows multiple active subscriptions.
• Billing period — monthly / annual / etc., for paid plans.
• Plan configuration — unit quantities for in-advance commitment charges and variable entitlements; price overrides.
• Add-ons — list of add-ons (and quantities) compatible with the plan.
• Subscription start date — Immediately (default) / EndOfCurrentBillingPeriod (if an active paid sub already exists) / SpecificDate (past = back-dated, no immediate charge; future = activates on date).
• Free trial — applicable to paid / custom plans.
• Spend management — minimumSpend, maximumSpend.
• Discounts — applied coupons (catalog-wide or ad-hoc subscription-specific).
• Payment method — automaticallyUsePaymentMethodOnFile / generate-an-invoice / no-payment-via-Stigg.
• Billing cycle anchor — UNCHANGED (default) / NOW.
• Proration — ProrateNow / ProrateOnNextInvoice / NoProration.

Generous-entitlement rule: when a customer’s effective entitlements come from multiple sources — active subscription, add-ons, trial, promotional entitlements, additional product subscriptions — Stigg picks the most generous value across all of them. The “trial vs paid” case is just one instance of this rule; it applies whenever sources overlap.

Preview a Subscription

Before provisioning, preview the immediate and recurring invoices:

const preview = await stigg.previewSubscription({
  customerId: 'customer-123',
  planId: 'plan-pro',
  billingPeriod: 'MONTHLY',
  addons: [{ addonId: 'addon-seats', quantity: 10 }],
  couponId: 'SAVE20',                          // optional
  subscriptionId: 'sub-789',                   // optional — preview an UPDATE to an existing sub
});

Node SDK / GraphQL returns immediateInvoice and recurringInvoice with each amount as a { amount, currency } Money object (lowercase subtotal). Direct REST callers see a flatter DTO with scalar amounts and the field name subTotal (capital T). Amounts are in full dollars / units of the currency, not cents — 49 means $49.00 (Stripe convention is the opposite, this catches Stripe-savvy devs). See references/provisioning.md for the full shape and previewSubscription use cases.

Update a Subscription

Critical: updateSubscription (the GraphQL mutation) does not support changing the plan. To change a subscription’s plan, call provisionSubscription again — Stigg routes it through the right mechanism (in-place update or replace, depending on plan-type transition; see the migration matrix below).

// Update — addons, billing period, billable features, price overrides
await stigg.updateSubscription({
  subscriptionId: 'sub-123',
  addons: [{ addonId: 'addon-seats', quantity: 10 }],
  billingPeriod: 'ANNUAL',
});

// Change plan — re-provision (NOT updateSubscription)
await stigg.provisionSubscription({
  customerId: 'customer-123',
  planId: 'plan-pro',          // new plan
  // ...other provisioning fields
});

What updateSubscription directly supports (per the GraphQL mutation surface):

• Billing period (paid plans, e.g. MONTHLY → ANNUAL).
• Add-ons (replaces existing — pass the new full list).
• Billable features (in-advance commitment quantities, per-unit quantities).
• Price overrides.

Other update flows surfaced by the Stigg app UI (trial extension / shortening, spend-limit changes, coupon application, billing-cycle anchor reset, proration on the change) flow through separate SDK methods or provisionSubscription re-calls — search the docs for the specific operation.

Scheduled updates replace, don’t queue: a new update overrides any pending scheduled update and applies immediately (documented for the Stigg app UI; SDK behavior generally matches — confirm in your SDK’s docs).

Detailed flow + patterns: references/updates.md.

Cancel a Subscription

Via @stigg/node-server-sdk (which translates to the cancelSubscription GraphQL mutation):

await stigg.cancelSubscription({
  subscriptionId: 'sub-789',                              // Node SDK uses subscriptionId
  subscriptionCancellationTime: 'END_OF_BILLING_PERIOD',  // or 'IMMEDIATE' / 'SPECIFIC_DATE'
  // endDate: '2026-06-01T00:00:00Z',                     // required when SPECIFIC_DATE
  // subscriptionCancellationAction: 'DEFAULT',           // or 'REVOKE_ENTITLEMENTS'
  // prorate: false,
});

Field-name note: Node SDK uses subscriptionId. Python / Go / Ruby / Java / .NET SDKs and the raw GraphQL mutation use subscriptionRefId. Direct REST takes the ID in the URL path.

subscriptionCancellationTime:

subscriptionCancellationAction:

States after cancel: CANCELED (already ended) or CANCELLATION_SCHEDULED (pending).

Direct REST users (calling https://api.stigg.io/api/v1 via curl): the unprefixed REST field names are cancellationTime, cancellationAction, endDate, prorate. Same enum values.

Trials

Trials apply to paid and custom plans. The plan defines the default trial; provisioning can override it.

• Provision with trial — pass trial config at provision time.
• Convert trial → paid — provision a paid subscription on top; Stigg starts the paid plan at the trial end.
• Trial expired without conversion — fires the trial.expired event; trigger win-back from your app.
• One trial per customer per product in self-served flows (admin overrides exist).
• Customers who already paid are not eligible for another self-serve free trial.

Detailed mechanics + examples (in-app upgrade, trial with add-ons): references/trials.md.

Multiple Active Subscriptions Per Customer

For multi-tenant products (workspaces / projects / apps), a single customer holds many subscriptions, scoped by resourceId:

const sub = await stigg.provisionSubscription({
  customerId: 'customer-123',
  resourceId: 'workspace-abc',
  planId: 'plan-team',
});

Once enabled (it’s a product-level setting, fixed at product creation):

• Pass resourceId on every relevant call — provision, update, entitlement check, usage report, paywall widget.
• The customer can have separate plans on each workspace, all paid with the same payment method.
• Trial vs paid: at most one active trial and one active non-trial subscription per (customer, resource) pair.
• Combine with single-instance products (set the other product to “single active subscription”) to model “account + sub-accounts” / “platform + app instances” — e.g., Webflow’s account + per-site model.

Once a product has any subscriptions, you cannot toggle multi-active on/off. Decide at product creation.

Plan-Version Migration (Catalog v1 → v2)

When a plan is republished, existing subscriptions stay on the old version unless migrated. Routine, ongoing operation.

Catalog-side publish flow (drafts, version policy, what triggers grandfathering) lives in stigg-pricing-modeling/references/plans.md. This section is the subscription-side migration mechanics.

Two migration mechanisms, picked automatically by Stigg based on the plan-type transition:

Triggering migration:

• UI: open the subscription, ⋮ → Migrate to latest → pick Immediately or At end of current period.
• Programmatic: the migrate-subscription mutation / SDK method. Allows gradual rollout.

If migration is immediate and the customer’s current price differs from the latest published price, Stigg auto-charges or credits the prorated amount.

Detailed migration reference: references/plan-version-migration.md.

When NOT to Use This Skill

• Modeling features / plans / add-ons → stigg-pricing-modeling.
• Runtime entitlement checks / usage reporting → stigg-entitlements.
• Strategic advice on pricing models → stigg-pricing-expert.

Common Mistakes