Before importing subscriptions, verify that the required customers have already been imported into Stigg.
Free plans
Using the CLI
- To migrate subscriptions to free plans, create a file named
free-subscriptions.json containing all subscriptions that you want to import. The file must follow this schema:
{
"subscriptions": [
{
"customerId": "lorem-ipsum",
"planId": "plan-1",
"resourceId": "site-1", // optional - required for multiple subscriptions product
"startDate": "2022-01-01T00:00:00.000Z", // optional - used for backdating
"endDate": "2022-01-01T00:00:00.000Z", // optional - end date for the subscription
}
],
"additionalMetaData": { // optional - set metadata for the subscription
"isTest": "true"
}
},
// ...
]
}
- Initiate the bulk import process:
npx @stigg/bulk-import --subscriptions-file free-subscriptions.json
Using the API and SDKs
Use the importSubscriptionsBulk mutation.
Paid plans
To migrate subscriptions to paid plans, repeat the below process for each subscription:
- Provision a subscription in Stigg with the start date of the subscription that currently exists in your billing provider and include the
billingInformation.isBackdated: true property. Doing so will create the subscription as backdated in the billing provider and ensure that customers will be billed again for the subscription starting from the next billing period. You may optionally sync additional metadata for the subscription that’s synced to the billing provider to indicate that this is a migrated subscription by passing the billingInformation.metadata property when provisioning the subscription Stigg.
- Cancel the original subscription in your billing provider immediately and without prorations.
Custom plans
Using the CLI
- To migrate subscriptions to custom plans, create a file named
custom-subscriptions.json containing all subscriptions that you want to import.
Custom plan subscriptions can optionally include entitlements to define the specific access each customer gets. Each item in the entitlements array must contain either a feature or a credit key — not both:
- Feature entitlements — set usage limits for features (e.g., number of seats or projects).
- Credit entitlements — grant a recurring credit allowance for a specific currency. The imported credits appear as recurring credit grants on the customer’s subscription. The
cadence field determines the grant renewal period: MONTH or YEAR.
The file must follow this schema:
{
"subscriptions": [
{
"customerId": "lorem-ipsum",
"planId": "plan-1",
"resourceId": "site-1", // optional - required for multiple subscriptions product
"startDate": "2022-01-01T00:00:00.000Z", // optional - used for backdating
"endDate": "2022-01-01T00:00:00.000Z", // optional - end date for the subscription
"entitlements": [ // optional - override plan entitlements per customer
{
"feature": {
"featureId": "feature-seats", // feature ID as defined in Stigg
"usageLimit": 10 // usage limit for this customer
}
},
{
"feature": {
"featureId": "feature-projects",
"usageLimit": 25
}
},
{
"credit": {
"customCurrencyId": "currency-api-credits", // credit currency ID as defined in Stigg
"amount": 50000, // credits granted per period
"cadence": "MONTH" // renewal period: "MONTH" or "YEAR"
}
}
],
"addons": [ // optional - set subscription addons
{ "addonId": "addon-1", "quantity": 6 },
{ "addonId": "addon-2", "quantity": 3 },
],
"additionalMetaData": { // optional - set metadata for the subscription
"isTest": "true"
}
},
// ...
]
}
- Initiate the bulk import process:
npx @stigg/bulk-import --subscriptions-file custom-subscriptions.json
Using the API and SDKs
Use the importSubscriptionsBulk mutation — see the API reference for all available fields and examples.
