Provision Subscription

Creates a new subscription for an existing customer.

Mutation

Mutation

mutation ProvisionSubscription($input: ProvisionSubscriptionInput!) {
  provisionSubscriptionV2(input: $input) {
    subscription {
      subscriptionId
      status
      startDate
      currentBillingPeriodEnd
      plan {
        refId
        displayName
      }
      addons {
        addon {
          refId
          displayName
        }
        quantity
      }
      prices {
        billingPeriod
        price {
          amount
          currency
        }
      }
      trialEndDate
    }
    entitlements {
      feature {
        refId
        displayName
      }
      isGranted
      usageLimit
      hasUnlimitedUsage
    }
  }
}

{
  "input": {
    "customerId": "customer-123",
    "planId": "plan-pro",
    "billingPeriod": "MONTHLY"
  }
}

{
  "data": {
    "provisionSubscriptionV2": {
      "subscription": {
        "subscriptionId": "sub-789",
        "status": "ACTIVE",
        "startDate": "2024-01-15T00:00:00Z",
        "currentBillingPeriodEnd": "2024-02-15T00:00:00Z",
        "plan": {
          "refId": "plan-pro",
          "displayName": "Pro Plan"
        },
        "addons": [],
        "prices": [
          {
            "billingPeriod": "MONTHLY",
            "price": {
              "amount": 99,
              "currency": "USD"
            }
          }
        ],
        "trialEndDate": null
      },
      "entitlements": [
        {
          "feature": {
            "refId": "feature-api-calls",
            "displayName": "API Calls"
          },
          "isGranted": true,
          "usageLimit": 10000,
          "hasUnlimitedUsage": false
        }
      ]
    }
  }
}

Parameters

input · ProvisionSubscriptionInput · required

Input for provisioning a subscription

Show properties

customerId · String · required

Customer reference ID

planId · String · required

Plan reference ID to subscribe to

billingPeriod · BillingPeriod

MONTHLY, ANNUAL

resourceId · String

Resource ID for multi-resource subscriptions

addons · [SubscriptionAddonInput]

Addons to include in subscription

Show nested properties

addonId · String · required

Addon reference ID

quantity · Int · required

Number of addon units

startDate · DateTime

When subscription should start (defaults to now)

cancellationDate · DateTime

Schedules cancellation at the supplied ISO 8601 datetime when the subscription is created. Must be in the future and after startDate. Trial subscriptions are supported — see the trial behavior note below.

trialOverrideConfiguration · TrialOverrideConfigurationInput

Trial period override configuration

Show nested properties

isTrial · Boolean · required

Whether to apply a trial period

trialEndDate · DateTime

Specific date when the trial ends

trialEndBehavior · TrialEndBehavior

Behavior when trial ends: CANCEL_SUBSCRIPTION or CONVERT_TO_PAID

appliedCoupon · SubscriptionCouponInput

Coupon to apply to the subscription

Show nested properties

couponId · String

Stigg coupon ID

billableFeatures · [BillableFeatureInput]

Initial quantities for pay-per-unit features

priceOverrides · [PriceOverrideInput]

Custom pricing overrides

entitlements · [SubscriptionEntitlementInputV2]

Entitlements to provision with the subscription (for custom plans). Supports both feature and credit entitlements.

Show nested properties

feature · SubscriptionFeatureEntitlementInput

Feature entitlement configuration. Common fields shown below — see the full type reference for all available fields.

Show nested properties

featureId · String · required

Feature reference ID

usageLimit · Float

Usage limit for the feature

hasUnlimitedUsage · Boolean

Whether the feature has unlimited usage

credit · SubscriptionCreditEntitlementInput

Credit entitlement configuration

Show nested properties

customCurrencyId · String · required

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

amount · Float · required

Number of credits to grant per cadence

cadence · CreditCadence · required

Credit renewal cadence: MONTH or YEAR

awaitPaymentConfirmation · Boolean

Wait for payment before activating

environmentId · UUID

Environment ID

Return Type

Returns a ProvisionSubscriptionResult with:

Field	Type	Description
subscription	CustomerSubscription	The created subscription
entitlements	[Entitlement]	Resulting entitlements

Examples

With Trial Period

{
  "input": {
    "customerId": "customer-123",
    "planId": "plan-pro",
    "trialOverrideConfiguration": {
      "isTrial": true,
      "trialEndBehavior": "CONVERT_TO_PAID"
    }
  }
}

With Addons

{
  "input": {
    "customerId": "customer-123",
    "planId": "plan-pro",
    "billingPeriod": "ANNUAL",
    "addons": [
      { "addonId": "addon-seats", "quantity": 10 },
      { "addonId": "addon-storage", "quantity": 2 }
    ]
  }
}

Scheduled Start

{
  "input": {
    "customerId": "customer-123",
    "planId": "plan-enterprise",
    "startDate": "2024-02-01T00:00:00Z"
  }
}

Scheduled Cancellation at Creation

Provision a subscription that’s already scheduled to cancel on a known future date. The subscription is created normally and the cancellation is queued for the supplied date.

{
  "input": {
    "customerId": "customer-123",
    "planId": "plan-pro",
    "cancellationDate": "2024-12-31T00:00:00Z"
  }
}

Trial behavior

Trial subscriptions accept cancellationDate. When provided, the trial’s trialEndDate is aligned to the supplied cancellationDate — so the trial ends and the subscription cancels on the same date. Use this when you want a fixed-end trial that won’t convert.

Custom Plan with Entitlements

Custom plans use the entitlements field to define what the subscription grants — this can include feature entitlements (access flags, usage limits) and credit entitlements (recurring credit allocations).

{
  "input": {
    "customerId": "customer-123",
    "planId": "plan-enterprise-custom",
    "entitlements": [
      {
        "feature": {
          "featureId": "feature-seats",
          "usageLimit": 50
        }
      },
      {
        "feature": {
          "featureId": "feature-sso",
          "hasUnlimitedUsage": true
        }
      },
      {
        "credit": {
          "customCurrencyId": "currency-api-credits",
          "amount": 100000,
          "cadence": "MONTH"
        }
      }
    ]
  }
}

Common Use Cases

Upgrade from free

Create paid subscription for customer on free plan.

Multi-product subscription

Add subscription to additional product for existing customer.

Trial conversion

Provision paid subscription when trial customer converts.

Related Operations

• Provision Customer - Create customer with subscription
• Update Subscription - Modify subscription
• Preview Subscription - Preview pricing