Overview

Importing your existing data into Stigg is a key milestone in the integration process. This guide will walk you through the process step-by-step, ensuring a smooth transition and uninterrupted operations.

Entities that can be imported

1. Customers
2. Subscriptions
3. Usage data

Data should be imported to Stigg according to the above order.

Prerequisites

• Your pricing has been modeled in Stigg.
• NodeJS must be installed.
• Obtain the Server API key of the environment that you'd like to import the data to.
• Export the above Server API key as an environment variable:

export STIGG_SERVER_API_KEY='<SERVER-API-KEY>'

Importing customers

Using the CLI

Create a file called customers.json that contains all the customers that will be imported to the environment.

The file should be in the following schema:

{
  "customers": [
    {
      "customerId": "lorem-ipsum",
      "email": "[email protected]", // optional
      "name": "Lorem-ipsum", // optional
      "billingId": "cus_MvdQq1bVD1BQHe", // optional - if an existing customer in Stripe
      "paymentMethodId": "pm_1N04AHEdaKWoSZ0OgP78RflV", // required for paid customers
      "updatedAt": "2022-01-01T00:00:00.000Z", // optional - indicates the last update of the customer. In case there's already existing customer that was updated after that date, it will skip import this customer
      "metadata": { // optional - set metadata for the customer
        "isTest": "true",
      },
    },
    // ...
  ],
}

Initiate the bulk import process:

npx @stigg/bulk-import --customers-file customers.json

Using the API and SDKs

Using the importCustomerBulk endpoint.

Importing subscriptions

🚧

Before importing subscriptions, ensure that the relevant customers have been imported to Stigg.

Free plans

Using the CLI

To migrate subscriptions to free plans, create a file called free-subscriptions.json that contains all of the subscriptions that should be imported.

The file should be in the following 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

Using the importSubscriptionBulk endpoint.

Paid plans

To migrate subscriptions to paid plans, repeat the below process for each subscription:

1. 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.
2. 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 called custom-subscriptions.json that contains all of the subscriptions that should be imported.

The file should be in the following 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
      "subscriptionEntitlements": [ // optional - required custom entitlements)
        { "featureId": "feature-seats", "usageLimit": 10 },
        { "featureId": "feature-projects", "usageLimit": 25 },
      ],
      "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

Using the importSubscriptionBulk endpoint.

Importing feature usage

🚧

Importing feature usage is supported only for metered features with a Calculated Usage meter type

🚧

Before importing feature usage, ensure that the relevant customers have been imported to Stigg.

Using the CLI

Create a file called usage.json that contains all the features' up-to-date usage.

The file should be in the following schema:

{
  "usages": [
    {
      "customerId": "lorem-ipsum",
      "resourceId": "site-1", // optional - required for multiple subscriptions product
      "featureId": "feature-seats",
      "usage": 5
    }
    // ...
  ]
}

Initiate the bulk import process:

npx @stigg/bulk-import --usage-file usage.json

📘

The import function is idempotent; therefore, attempting to import usage multiple time will yield the same result.

Using the API and SDKs

Leverage the reportUsageBulk endpoint while passing the updateBehavior: UsageUpdateBehavior.SET property in each of the usage reports.