Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.stigg.io/llms.txt

Use this file to discover all available pages before exploring further.

​
Subscription management

​
Provisioning subscriptions

When a customer subscribes to a new plan (upgrade, downgrade, or initial subscription), a subscription needs to be provisioned in Stigg. You provide the customer ID and target plan ID. For paid subscriptions, the billing period (monthly or annually) is required. Additional optional parameters include:
  • Resource ID - required when a product supports multiple active subscriptions
  • Billable feature quantities - required for per-unit pricing
  • Add-ons - list of add-ons and their quantities
  • Promotion code - a promo code from your billing provider
  • Billing country code - ISO-3166-1 format, required for price localization
  • Checkout options - configuration for hosted checkout (success/cancel URLs, promo code collection, etc.)
  • Metadata - arbitrary key-value pairs
Behavior:
  • When payment details are required and not yet provided, Stigg redirects the customer to the billing solution’s hosted checkout page.
  • When no payment is required, the subscription is created immediately.
  • The result includes the subscription details or a checkout URL if payment is needed.
const subscription = await stiggClient.provisionSubscription({
    customerId: 'customer-demo-01',
    planId: 'plan-basic',
    billingPeriod: 'MONTHLY',                   // optional, required for paid subscriptions
    resourceId: 'resource-01',                  // optional, required for multiple subscriptions
    billableFeatures: [{
      featureId:'feature-01-templates',
      quantity: 2
    }],
    addons: [{
        addonId: 'addon-extra-stuff',
        quantity: 1,
    }],
    promotionCode: 'STIGG30', 		              // optional
    billingCountryCode:'DK',     		            // optional, required for price localization
    checkoutOptions: {                          // optional
      successUrl: "https://your-success-url.com",
      cancelUrl: "https://your-cancel-url.com",
      allowPromoCodes: true,
      collectBillingAddress: true,
    },
    metadata: {
      key: 'value',
    }
});
  1. A customer can have both a non-trial and a trial subscription to different plans of the same product in parallel.
  2. When a customer with a trial subscription for plan X creates a new subscription for the same plan, it will be created as a non-trial (paid) subscription.
  3. When a customer already has an active subscription for a product and a new one is created, the existing subscription is automatically cancelled.
  4. You can explicitly skip the trial period by providing a skip-trial flag.

​
Updating subscriptions

Update an existing subscription without creating a new one, keeping the original start date and billing cycle. You can:
  1. Update subscription metadata
  2. Update unit quantity for per-unit pricing (e.g., adding or removing seats)
  3. Add or remove add-ons (only if compatible with the plan)
  4. Update the promotion code
  5. Update the billing period
When integrated with a billing solution, modifying quantities or add-ons generates a prorated invoice. 
const subscription = await stiggClient.updateSubscription({
  subscriptionId: 'subscription-plan-basic',
  billableFeatures: [{
    featureId:'feature-01-templates',
    quantity: 3
  }],
  promotionCode: "STIGG30", // optional
  addons: [
    { addonId: 'extra-api-calls', quantity: 5 }
  ],
  metadata: {
      key: 'newValue'
  },
});

​
Canceling subscriptions

Cancel a subscription by its ID. Cancellation behavior (immediate or end of billing period) is determined by the product’s configuration. 
await stiggClient.cancelSubscription({
    subscriptionId: 'subscription-plan-basic'
});

​
Canceling scheduled updates

Cancel all scheduled updates or pending payment updates for a given subscription. 
await stiggClient.cancelSubscriptionScheduledUpdates({
  subscriptionId: 'subscription-plan-essentials',
  status: SubscriptionScheduleStatus.Scheduled, // or SubscriptionScheduleStatus.PendingPayment
});

​
Listing active subscriptions

Retrieve a list of a customer’s active subscriptions. For products that support multiple active subscriptions, pass one or more resource IDs to filter by resource. 
const subscriptions = await stiggClient.getActiveSubscriptionsList({
  customerId: 'customer-demo-01',
  resourceId: 'resource-01', // optional, pass it to get subscription of specific resource
});

​
Getting a specific subscription

Retrieve extended details for a single subscription, including plan details, add-ons, pricing, payment collection status, and the latest invoice. 
const subscription = await stiggClient.getSubscription({
  subscriptionId: 'subscription-01',
});

​
Listing subscriptions with filtering

Query subscriptions with rich filtering, sorting, and cursor-based pagination. Useful for admin dashboards, audits, and reporting. Supported filter operators include equality, inequality, inclusion, and exclusion for strings and enums, as well as comparison operators for dates. Filters support logical AND/OR composition. Sortable fields include creation date, customer ID, environment ID, product ID, resource ID, and status. 
const subscriptions = await stiggClient.getSubscriptions({
  filter: {
    and: [
      { customerId: { eq: "customer-demo-01" } },
      { status: { in: ["ACTIVE", "IN_TRIAL"] } }
    ]
  },
  sorting: [{ field: "createdAt", direction: "DESC", nulls: "LAST" }],
  paging: { first: 25 }
});

​
Subscription migration

Migrate subscriptions to the latest plan and add-on version on a subscription-by-subscription basis, to prevent SKU sprawl from grandfathering.
When the current subscription price differs from the latest published version, the customer will be charged or credited the prorated difference.
await stiggClient.migrateSubscriptionToLatest({
  subscriptionId: "subscription-id",
  subscriptionMigrationTime: SubscriptionMigrationTime.EndOfBillingPeriod, // optional
});