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 a Stripe-hosted checkout page (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
    metadata: {
      key: 'value',
    }
});

data = await client.provision_subscription(ProvisionSubscriptionInput(
    **{
        "customerId": "customer-id",
        "planId": "plan-revvenu-basic",
        "resourceId": "resource-01",  # optional, required for multiple subscriptions
        "billingPeriod": "MONTHLY",   # optional, required for paid subscriptions
        "billableFeatures": [{                # optional, required for per-unit pricing
          "featureId": "feature-01-templates",
          "quantity": 2
        }],
        "addons": [                                       # optional
            {
                "addonId": "addon-extra-stuff",
                "quantity": 2
            }
        ],
        "billingCountryCode":"DK",     # optional, required for price localization
        "additionalMetaData": {               # optional
            "key": "value"
        }
    }
))

result, err := client.ProvisionSubscription(context.Background(), stigg.ProvisionSubscriptionInput{
  CustomerID: "customer-demo-01",
  PlanID: "plan-revvenu-essentials",
  BillingPeriod: Ptr(stigg.BillingPeriodMonthly),     // optional, required for paid subscriptions
  ResourceID: Ptr("resource-01"),                      // optional, required for multiple subscriptions
  BillableFeatures: []*stigg.BillableFeatureInput{     // optional, required for per-unit pricing
    {
      FeatureID: "feature-01-templates",
      Quantity:  20,
    },
  },
  Addons: []*stigg.SubscriptionAddonInput{             // optional
    {
      AddonID:  "addon-revvenu-extra-campaigns",
      Quantity: Ptr(int64(3)),
    },
  },
  BillingCountryCode: Ptr("DK"),   					           // optional, required for price localization
})

resp = client.request(Stigg::Mutation::ProvisionSubscription, {
  "input": {
    "customerId": "customer-demo-02",
    "planId": "plan-revvenu-essentials",
    "resourceId": "resource-01", # optional, required for multiple subscriptions
    "billingPeriod": "MONTHLY",  # optional, required for paid subscriptions
    "billingCountryCode":"DK",   # optional, required for price localization
    "billableFeatures": [{       # optional, required for per-unit pricing
      "featureId": "feature-01-templates",
      "quantity": 2
    }],
  }
})

var resp = stigg.mutation(
  ProvisionSubscriptionMutation.builder()
  .input(ProvisionSubscriptionInput.builder()
         .customerId("customer-demo-01")
         .planId("plan-revvenu-basic")
         .resourceId("resource-01")                     // optional
         .billingPeriod(BillingPeriod.MONTHLY)           // optional, required for paid plans
         .billableFeatures(List.of(                      // optional, required for per-unit pricing
           BillableFeatureInput.builder()
           .featureId("feature-01-templates")
           .quantity(2.0)
           .build()
         ))
         .addons(List.of(                                // optional
           SubscriptionAddonInput.builder()
           .addonId("addon-extra-stuff")
           .quantity(5)
           .build()
         ))
         .billingCountryCode("DK")                       // optional, required for price localization
         .additionalMetaData(new HashMap<>() {{
           put("key", "value");
         }})
         .build())
  .build()
);

var res = await stigg.ProvisionSubscription.ExecuteAsync(new ProvisionSubscriptionInput()
{
  CustomerId = "customer-demo-01",
  PlanId = "plan-revvenu-essentials",
  BillingPeriod = BillingPeriod.Monthly,                 // optional, required for paid plans
  BillableFeatures = new List<BillableFeatureInput>()    // optional, required for per-unit pricing
  {
    new()
    {
      FeatureId = "feature-01-templates",
      Quantity = 5
    }
  },
  Addons = new List<SubscriptionAddonInput>()            // optional
  {
    new()
    {
      AddonId = "addon-extra-stuff",
      Quantity = 5
    }
  },
});

Show Result (Node.js)

{
  "status": "Success",
  "checkoutUrl": "https://your-success-url.com",
  "subscription": {
    "id": "subscription-plan-basic",
    "planId": "plan-basic",
    "status": "ACTIVE",
    "addons": [],
    "customerId": "customer-demo-01",
    "resource": {
      "id": "resource-01"
    },
    "metadata": {
      "lorem": "ipsum"
    },
    "pricingType": "FREE",
    "paymentCollection": "NOT_REQUIRED",
    "latestInvoice": {
      "billingId": "invoice-01",
      "status": "PAID"
    }
  }
}

A customer can have both a non-trial and a trial subscription to different plans of the same product in parallel.
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.
When a customer already has an active subscription for a product and a new one is created, the existing subscription is automatically cancelled.
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:

Update subscription metadata
Update unit quantity for per-unit pricing (e.g., adding or removing seats)
Add or remove add-ons (only if compatible with the plan)
Update the promotion code
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'
  },
});

data = await client.update_subscription(UpdateSubscriptionInput(
  **{
    "refId": "subscription-plan-revvenu-growth-589879",
    "billableFeatures": [{
      "featureId": "feature-01-templates",
      "quantity": 2
    }],
  }
))

result, err := client.UpdateSubscription(context.Background(), stigg.UpdateSubscriptionInput{
  SubscriptionID: Ptr("subscription-plan-revvenu-essentials-dc847c"),
  BillingPeriod: Ptr(stigg.BillingPeriodMonthly),
  BillableFeatures: []*stigg.BillableFeatureInput{
    {
      FeatureID: "feature-01-templates",
      Quantity:  6,
    },
  },
  Addons: []*stigg.SubscriptionAddonInput{
    {
      AddonID:  "addon-revvenu-extra-campaigns",
      Quantity: Ptr(int64(2)),
    },
  },
})

resp = client.request(Stigg::Mutation::UpdateSubscription, {
  "input": {
    "subscriptionId": "subscription-plan-revvenu-growth-589879",
    "billableFeatures": [{
      "featureId": "feature-01-templates",
      "quantity": 2
    }],
  }
})

var resp = stigg.mutation(
  UpdateSubscriptionMutation.builder()
  .input(
    UpdateSubscriptionInput.builder()
    .subscriptionId("subscription-plan-revvenu-essentials-bum2flivze")
    .billableFeatures(List.of(
      BillableFeatureInput.builder()
      .featureId("feature-01-templates")
      .quantity(5.0)
      .build()
    ))
    .addons(List.of(                    // optional
      SubscriptionAddonInput.builder()
      .addonId("addon-extra-stuff")
      .quantity(5)
      .build()
    ))
    .build()
  )
  .build()
);

var res = await stigg.UpdateSubscription.ExecuteAsync(new UpdateSubscriptionInput()
{
  SubscriptionId = "subscription-plan-revvenu-essentials-cpzi7p2g09",
  BillableFeatures = new List<BillableFeatureInput>()
  {
    new()
    {
      FeatureId = "feature-01-templates",
      Quantity = 7
    }
  },
  Addons = new List<SubscriptionAddonInput>()
  {
    new()
    {
      AddonId = "addon-extra-stuff",
      Quantity = 5
    }
  },
});

Show Result (Node.js)

{
  "id": "subscription-plan-basic",
  "planId": "plan-basic",
  "status": "ACTIVE",
  "addons": [],
  "customerId": "customer-demo-01",
  "resource": {
    "id": "resource-01"
  },
  "metadata": {
    "key": "newValue"
  },
  "pricingType": "FREE"
}

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

data = await client.cancel_subscription(SubscriptionCancellationInput(
  **{
    "subscriptionRefId": "subscription-plan-revvenu-growth-589879",
    "subscriptionCancellationTime":  "IMMEDIATE"
  }
))

result, err := client.CancelSubscription(context.Background(), stigg.SubscriptionCancellationInput{
  SubscriptionRefID: "subscription-plan-revvenu-essentials-dc847c",
  SubscriptionCancellationTime: Ptr(stigg.SubscriptionCancellationTimeImmediate),
})

resp = client.request(Stigg::Mutation::CancelSubscription, {
  "input": {
    "subscriptionRefId": "subscription-plan-revvenu-growth-589879",
    "subscriptionCancellationTime":  "IMMEDIATE"
  }
})

var resp =
  stigg.mutation(
    CancelSubscriptionMutation.builder()
    .input(
      SubscriptionCancellationInput.builder()
      .subscriptionRefId("subscription-plan-revvenu-essentials-bum2flivze")
      .subscriptionCancellationAction(SubscriptionCancellationAction.DEFAULT)       // optional
      .subscriptionCancellationTime(SubscriptionCancellationTime.END_OF_BILLING_PERIOD) // optional
      .build())
    .build());

var res = await stigg.CancelSubscription.ExecuteAsync(new SubscriptionCancellationInput()
{
  SubscriptionRefId = "subscription-plan-revvenu-essentials-cpzi7p2g09",
  SubscriptionCancellationTime = SubscriptionCancellationTime.END_OF_BILLING_PERIOD, // optional
});

Show Result (Node.js)

{
  "id": "subscription-plan-basic",
  "planId": "plan-basic",
  "status": "CANCELED",
  "customerId": "customer-demo-01",
  "metadata": {
    "key": "newValue"
  },
  "pricingType": "FREE",
  "effectiveEndDate": "2022-09-20T10:18:06.842Z"
}

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

data = await client.get_active_subscriptions_list(GetActiveSubscriptionsInput(
  **{
    "customerId": "customer-demo-01",
    "resourceId": "resource-01",  # optional, pass it to get subscription of specific resource
  }
))

result, err := client.GetActiveSubscriptions(context.Background(), stigg.GetActiveSubscriptionsInput{
  CustomerID: "customer-demo-01",
  ResourceID: Ptr("resource-01"), // optional, pass it to get subscription of specific resource
})

resp = client.request(Stigg::Query::GetActiveSubscriptionsList, {
  "input": {
    "customerId": "customer-demo-01",
    "resourceId": "resource-01",  # optional, pass it to get subscription of specific resource
  }
})

var resp = stigg.query(
  GetActiveSubscriptionsListQuery.builder()
  .input(GetActiveSubscriptionsInput.builder()
         .customerId("customer-demo-01")
         .resourceId("resource-01") // optional
         .build())
  .build()
);

var res = await stigg.GetActiveSubscriptionsList.ExecuteAsync(new GetActiveSubscriptionsInput()
{
  CustomerId = "customer-demo-01",
  ResourceId = "resource-01", // optional
});

Show Result (Node.js)

[
  {
    "subscriptionId": "subscription-plan-pro-abc123",
    "status": "ACTIVE",
    "startDate": "2024-01-15T00:00:00.000Z",
    "endDate": null,
    "effectiveEndDate": "2025-01-15T00:00:00.000Z",
    "currentBillingPeriodStart": "2024-01-15T00:00:00.000Z",
    "currentBillingPeriodEnd": "2024-02-15T00:00:00.000Z",
    "billingPeriod": "MONTHLY",
    "additionalMetaData": {
      "internalTierId": "tier-gold"
    },
    "customer": {
      "customerId": "customer-demo-01",
      "email": "user@example.com"
    },
    "payingCustomer": {
      "customerId": "customer-demo-01",
      "email": "user@example.com"
    },
    "plan": {
      "refId": "plan-pro",
      "displayName": "Pro Plan",
      "description": "Full access to all Pro features",
      "product": {
        "refId": "product-main",
        "displayName": "Main Product",
        "downgradePlan": {
          "refId": "plan-free",
          "displayName": "Free Plan"
        }
      }
    },
    "addons": [],
    "prices": [
      {
        "billingModel": "FLAT_FEE",
        "price": {
          "billingPeriod": "MONTHLY",
          "price": {
            "amount": 99,
            "currency": "USD"
          }
        }
      }
    ],
    "totalPrice": {
      "subTotal": {
        "amount": 99,
        "currency": "USD"
      },
      "total": {
        "amount": 99,
        "currency": "USD"
      }
    },
    "trialEndDate": null
  }
]

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

data = await client.get_subscription(GetSubscriptionInput(
  **{
    "subscriptionId": "subscription-01",
  }
))

// Not available in the Go SDK — use the GraphQL API directly

resp = client.request(Stigg::Query::GetSubscription, {
  "subscriptionId": "subscription-01",
})

var resp = stigg.query(
  GetSubscriptionQuery.builder()
  .input(GetSubscriptionInput.builder()
         .subscriptionId("subscription-01")
         .build())
  .build()
);

var res = await stigg.GetSubscription.ExecuteAsync(new GetSubscriptionInput()
{
  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 }
});

data = await client.get_subscriptions(GetSubscriptionsInput(
  **{
    "filter": {
      "and": [
        { "customerId": { "eq": "customer-demo-01" } },
        { "status": { "in": ["ACTIVE", "IN_TRIAL"] } }
      ]
    },
    "sorting": [{ "field": "createdAt", "direction": "DESC", "nulls": "LAST" }],
    "paging": { "first": 25 }
  }
))

result, err := client.GetSubscriptions(context.Background(), stigg.GetSubscriptionsInput{
  Filter: &stigg.SubscriptionsFilterInput{
    And: []*stigg.SubscriptionsFilterInput{
      {CustomerID: &stigg.StringFieldComparison{Eq: Ptr("customer-demo-01")}},
      {Status: &stigg.SubscriptionStatusFilterComparison{In: []string{"ACTIVE", "IN_TRIAL"}}},
    },
  },
  Sorting: []*stigg.SubscriptionSort{{Field: "createdAt", Direction: "DESC", Nulls: Ptr("LAST")}},
  Paging:  &stigg.CursorPaging{First: Ptr(int64(25))},
})

resp = client.request(Stigg::Query::GetSubscriptions, {
  "filter": {
    "and": [
      { "customerId": { "eq": "customer-demo-01" } },
      { "status": { "in": ["ACTIVE", "IN_TRIAL"] } }
    ]
  },
  "sorting": [{ "field": "createdAt", "direction": "DESC", "nulls": "LAST" }],
  "paging": { "first": 25 }
})

var resp = stigg.query(
  GetSubscriptionsQuery.builder()
  .filter(SubscriptionsFilterInput.builder()
    .and(List.of(
      SubscriptionsFilterInput.builder()
        .customerId(StringFieldComparison.builder().eq("customer-demo-01").build())
        .build(),
      SubscriptionsFilterInput.builder()
        .status(SubscriptionStatusFilterComparison.builder()
          .in(List.of(SubscriptionStatus.ACTIVE, SubscriptionStatus.IN_TRIAL))
          .build())
        .build()
    ))
    .build())
  .sorting(List.of(SubscriptionSort.builder()
    .field(SubscriptionSortFields.CREATED_AT)
    .direction(SortDirection.DESC)
    .nulls(QuerySortNulls.LAST)
    .build()))
  .paging(CursorPaging.builder().first(25).build())
  .build()
);

var resp = await stigg.GetSubscriptions.ExecuteAsync(new GetSubscriptionsInput()
{
  Filter = new SubscriptionsFilterInput()
  {
    And = new List<SubscriptionsFilterInput>()
    {
      new() { CustomerId = new StringFieldComparison() { Eq = "customer-demo-01" } },
      new() { Status = new SubscriptionStatusFilterComparison() { In = new List<SubscriptionStatus> { SubscriptionStatus.Active, SubscriptionStatus.InTrial } } }
    }
  },
  Sorting = new List<SubscriptionSort>() { new() { Field = SubscriptionSortFields.CreatedAt, Direction = SortDirection.Desc, Nulls = QuerySortNulls.Last } },
  Paging = new CursorPaging() { 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
});

Integration guides

Quick start guides

I want to...

Subscription management