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

mutation ImportSubscriptionsBulk($input: ImportSubscriptionsBulkInput!) {
  importSubscriptionsBulk(input: $input)
}

{
  "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 }
        ]
      }
    ]
  }
}

{
  "data": {
    "importSubscriptionsBulk": "task-id-12345"
  }
}

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.

Parameters

ImportSubscriptionsBulkInput

required

Input for bulk subscription import

Show properties

[ImportSubscriptionInput!]

required

Array of subscriptions to import

Show nested properties

String

required

Customer reference ID. The customer must already exist in Stigg.

String

required

Plan reference ID to subscribe the customer to

String

Resource ID — required for multi-subscription products

DateTime

Subscription start date (for backdating). Defaults to now.

DateTime

Subscription end date

BillingPeriod

MONTHLY or ANNUALLY

String

Custom subscription ID. Auto-generated if omitted.

String

External billing provider subscription ID (e.g. Stripe subscription ID)

Float

Unit quantity for per-unit pricing

[SubscriptionEntitlementInputV2]

Variable entitlements for the subscription (custom plans only). Each item must contain exactly one of feature or credit. Replaces the deprecated subscriptionEntitlements field.

Show nested properties

SubscriptionFeatureEntitlementInput

Feature entitlement — grants access to a feature with an optional usage limit.

Show nested properties

String

required

Feature reference ID

Float

Usage limit for the feature

Boolean

Whether the feature has unlimited usage

EntitlementResetPeriod

Usage reset period: MONTH, WEEK, YEAR, or DAY

SubscriptionCreditEntitlementInput

Credit entitlement — creates a recurring credit grant on the subscription.

Show nested properties

String

required

Credit currency reference ID (e.g. "currency-api-credits")

Float

required

Number of credits granted per period

CreditCadence

required

Credit renewal cadence: MONTH or YEAR

[ChargeInput]

Additional one-time feature or credit charges

Show nested properties

ChargeType

required

FEATURE or CREDIT

String

required

Feature ID or custom currency ID

Float

required

Usage limit (for features) or credit amount (for credits)

[SubscriptionAddonInput]

Addons to include in the subscription

Show nested properties

String

required

Addon reference ID

Int

Number of addon units (defaults to 1)

[BillableFeatureInput]

Initial quantities for pay-per-unit features

JSON

Metadata to attach to the subscription

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.

String

Salesforce record ID

String

Associate the import with a specific billing integration

UUID

Environment ID

Return Type

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

Examples

Free plan subscription

{
  "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).

{
  "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

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.

Bulk onboard enterprise customers

Import custom plan subscriptions with per-customer entitlements — different seat limits, project counts, and credit allocations for each customer.

Seed a staging environment

Quickly populate a staging or testing environment with subscriptions for QA.

Provision Subscription — Create a single subscription
Update Subscription — Modify an existing subscription
Create Credit Grant — Grant credits outside of a subscription

Overview

SDKs

Queries

Mutations

Types

Import Subscriptions Bulk

Mutation

Parameters

Return Type

Examples

Free plan subscription

Custom plan with feature and credit entitlements

Common Use Cases

​Mutation

​Parameters

​Return Type

​Examples

​Free plan subscription

​Custom plan with feature and credit entitlements

​Common Use Cases

​Related Operations

Mutation

Parameters

Return Type

Examples

Free plan subscription

Custom plan with feature and credit entitlements

Common Use Cases

Related Operations