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

# Import Subscriptions Bulk

Imports multiple subscriptions in a single bulk operation. Supports free, paid, and custom plans — including feature and credit entitlements for custom plans.

## Mutation

<CodeGroup>
  ```graphql Mutation theme={null}
  mutation ImportSubscriptionsBulk($input: ImportSubscriptionsBulkInput!) {
    importSubscriptionsBulk(input: $input)
  }
  ```

  ```json Variables theme={null}
  {
    "input": {
      "subscriptions": [
        {
          "customerId": "customer-123",
          "planId": "plan-free"
        },
        {
          "customerId": "customer-456",
          "planId": "plan-enterprise-custom",
          "startDate": "2024-01-01T00:00:00Z",
          "entitlements": [
            {
              "feature": {
                "featureId": "feature-seats",
                "usageLimit": 50
              }
            },
            {
              "credit": {
                "customCurrencyId": "currency-api-credits",
                "amount": 100000,
                "cadence": "MONTH"
              }
            }
          ],
          "addons": [
            { "addonId": "addon-support", "quantity": 1 }
          ]
        }
      ]
    }
  }
  ```

  ```json Response theme={null}
  {
    "data": {
      "importSubscriptionsBulk": "task-id-12345"
    }
  }
  ```
</CodeGroup>

<Note>
  The mutation returns a task ID. The import runs asynchronously — subscriptions are created in the background. Individual subscriptions that fail validation are skipped without blocking the rest of the batch.
</Note>

## Parameters

<ParamField body="input" type="ImportSubscriptionsBulkInput" required>
  Input for bulk subscription import

  <Expandable title="properties">
    <ParamField body="subscriptions" type="[ImportSubscriptionInput!]" required>
      Array of subscriptions to import

      <Expandable title="nested properties">
        <ParamField body="customerId" type="String" required>
          Customer reference ID. The customer must already exist in Stigg.
        </ParamField>

        <ParamField body="planId" type="String" required>
          Plan reference ID to subscribe the customer to
        </ParamField>

        <ParamField body="resourceId" type="String">
          Resource ID — required for multi-subscription products
        </ParamField>

        <ParamField body="startDate" type="DateTime">
          Subscription start date (for backdating). Defaults to now.
        </ParamField>

        <ParamField body="endDate" type="DateTime">
          Subscription end date
        </ParamField>

        <ParamField body="billingPeriod" type="BillingPeriod">
          `MONTHLY` or `ANNUALLY`
        </ParamField>

        <ParamField body="subscriptionId" type="String">
          Custom subscription ID. Auto-generated if omitted.
        </ParamField>

        <ParamField body="billingId" type="String">
          External billing provider subscription ID (e.g. Stripe subscription ID)
        </ParamField>

        <ParamField body="unitQuantity" type="Float">
          Unit quantity for per-unit pricing
        </ParamField>

        <ParamField body="entitlements" type="[SubscriptionEntitlementInputV2]">
          Variable entitlements for the subscription (custom plans only). Each item must contain exactly one of `feature` or `credit`. Replaces the deprecated `subscriptionEntitlements` field.

          <Expandable title="nested properties">
            <ParamField body="feature" type="SubscriptionFeatureEntitlementInput">
              Feature entitlement — grants access to a feature with an optional usage limit.

              <Expandable title="nested properties">
                <ParamField body="featureId" type="String" required>
                  Feature reference ID
                </ParamField>

                <ParamField body="usageLimit" type="Float">
                  Usage limit for the feature
                </ParamField>

                <ParamField body="hasUnlimitedUsage" type="Boolean">
                  Whether the feature has unlimited usage
                </ParamField>

                <ParamField body="resetPeriod" type="EntitlementResetPeriod">
                  Usage reset period: MONTH, WEEK, YEAR, or DAY
                </ParamField>
              </Expandable>
            </ParamField>

            <ParamField body="credit" type="SubscriptionCreditEntitlementInput">
              Credit entitlement — creates a recurring credit grant on the subscription.

              <Expandable title="nested properties">
                <ParamField body="customCurrencyId" type="String" required>
                  Credit currency reference ID (e.g. `"currency-api-credits"`)
                </ParamField>

                <ParamField body="amount" type="Float" required>
                  Number of credits granted per period
                </ParamField>

                <ParamField body="cadence" type="CreditCadence" required>
                  Credit renewal cadence: `MONTH` or `YEAR`
                </ParamField>
              </Expandable>
            </ParamField>
          </Expandable>
        </ParamField>

        <ParamField body="charges" type="[ChargeInput]">
          Additional one-time feature or credit charges

          <Expandable title="nested properties">
            <ParamField body="type" type="ChargeType" required>
              `FEATURE` or `CREDIT`
            </ParamField>

            <ParamField body="id" type="String" required>
              Feature ID or custom currency ID
            </ParamField>

            <ParamField body="quantity" type="Float" required>
              Usage limit (for features) or credit amount (for credits)
            </ParamField>
          </Expandable>
        </ParamField>

        <ParamField body="addons" type="[SubscriptionAddonInput]">
          Addons to include in the subscription

          <Expandable title="nested properties">
            <ParamField body="addonId" type="String" required>
              Addon reference ID
            </ParamField>

            <ParamField body="quantity" type="Int">
              Number of addon units (defaults to 1)
            </ParamField>
          </Expandable>
        </ParamField>

        <ParamField body="billableFeatures" type="[BillableFeatureInput]">
          Initial quantities for pay-per-unit features
        </ParamField>

        <ParamField body="additionalMetaData" type="JSON">
          Metadata to attach to the subscription
        </ParamField>

        <ParamField body="updatedAt" type="DateTime">
          Last update timestamp of the source subscription. If Stigg already has a subscription for this customer and plan that was updated after this date, the import is skipped.
        </ParamField>

        <ParamField body="salesforceId" type="String">
          Salesforce record ID
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField body="integrationId" type="String">
      Associate the import with a specific billing integration
    </ParamField>

    <ParamField body="environmentId" type="UUID">
      Environment ID
    </ParamField>
  </Expandable>
</ParamField>

## Return Type

Returns a `String` — the task ID for the asynchronous import operation.

## Examples

### Free plan subscription

```json theme={null}
{
  "input": {
    "subscriptions": [
      {
        "customerId": "customer-123",
        "planId": "plan-free"
      }
    ]
  }
}
```

### Custom plan with feature and credit entitlements

Custom plans use the `entitlements` field to define per-customer access — this can include feature entitlements (usage limits) and credit entitlements (credit allowances).

```json theme={null}
{
  "input": {
    "subscriptions": [
      {
        "customerId": "customer-456",
        "planId": "plan-enterprise-custom",
        "startDate": "2024-01-01T00:00:00Z",
        "entitlements": [
          {
            "feature": {
              "featureId": "feature-seats",
              "usageLimit": 50
            }
          },
          {
            "feature": {
              "featureId": "feature-sso",
              "hasUnlimitedUsage": true
            }
          },
          {
            "credit": {
              "customCurrencyId": "currency-api-credits",
              "amount": 100000,
              "cadence": "MONTH"
            }
          }
        ],
        "addons": [
          { "addonId": "addon-premium-support", "quantity": 1 }
        ]
      }
    ]
  }
}
```

## Common Use Cases

<AccordionGroup>
  <Accordion title="Migrate from another billing system">
    Import existing subscriptions during migration to Stigg. Use `startDate` for backdating and `billingId` to link to the existing billing provider subscription.
  </Accordion>

  <Accordion title="Bulk onboard enterprise customers">
    Import custom plan subscriptions with per-customer entitlements — different seat limits, project counts, and credit allocations for each customer.
  </Accordion>

  <Accordion title="Seed a staging environment">
    Quickly populate a staging or testing environment with subscriptions for QA.
  </Accordion>
</AccordionGroup>

## Related Operations

* [Provision Subscription](/api-and-sdks/api-reference/mutations/provision-subscription) — Create a single subscription
* [Update Subscription](/api-and-sdks/api-reference/mutations/update-subscription) — Modify an existing subscription
* [Create Credit Grant](/api-and-sdks/api-reference/mutations/create-credit-grant) — Grant credits outside of a subscription