> ## 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.

# Importing subscriptions

<Warning>
  Before importing subscriptions, verify that the required customers have already been imported into Stigg.
</Warning>

## Free plans

### Using the CLI

1. To migrate subscriptions to [free plans](../../modeling-your-pricing-in-stigg/plans/defining-plan-pricing/free), create a file named `free-subscriptions.json` containing all subscriptions that you want to import. The file must follow this schema:

<CodeGroup>
  ```json JSON theme={null}
  {
    "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"
        }
      },
      // ...
    ]
  }
  ```
</CodeGroup>

2. Initiate the bulk import process:

<CodeGroup>
  ```shell shell theme={null}
  npx @stigg/bulk-import --subscriptions-file free-subscriptions.json
  ```
</CodeGroup>

### Using the API and SDKs

Use the `importSubscriptionsBulk` mutation.

<Note>
  The `importSubscriptionsBulk` mutation supports up to **1,000 subscriptions per request** and has a rate limit of **400 requests per minute**. It runs **asynchronously** and returns a `taskId` you can use to track the import status.
</Note>

## Paid plans

To migrate subscriptions to [paid plans](../../modeling-your-pricing-in-stigg/plans/defining-plan-pricing/paid/paid), repeat the below process for each subscription:

1. [Provision](/guides/quick-start-guides/creating-subscriptions) 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](https://docs.stripe.com/billing/subscriptions/cancel) the original subscription in your billing provider immediately and without prorations.

<img src="https://mintcdn.com/stigg/tWlJkHU9GfoKBEmJ/images/docs/5d9324a76008953814e09fbcf2563a6280af8d318d6683d0166a22fcb621959b-image.png?fit=max&auto=format&n=tWlJkHU9GfoKBEmJ&q=85&s=290f473afdaa97071fe4b4bb549d9350" alt="" width="2400" height="1139" data-path="images/docs/5d9324a76008953814e09fbcf2563a6280af8d318d6683d0166a22fcb621959b-image.png" />

## Custom plans

### Using the CLI

1. To migrate subscriptions to [custom plans](../../modeling-your-pricing-in-stigg/plans/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:

<CodeGroup>
  ```json JSON theme={null}
  {
    "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"
        }
      },
      // ...
    ]
  }
  ```
</CodeGroup>

2. Initiate the bulk import process:

<CodeGroup>
  ```shell shell theme={null}
  npx @stigg/bulk-import --subscriptions-file custom-subscriptions.json
  ```
</CodeGroup>

### Using the API and SDKs

Use the [`importSubscriptionsBulk`](/api-and-sdks/api-reference/mutations/import-subscriptions-bulk) mutation — see the API reference for all available fields and examples.

<Note>
  The `importSubscriptionsBulk` mutation supports up to **1,000 subscriptions per request** and has a rate limit of **400 requests per minute**. It runs **asynchronously** and returns a `taskId` you can use to track the import status.
</Note>