Skip to main content
Creates a new subscription for an existing customer.

​
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
    }
  }
}

​
Parameters

​
input
ProvisionSubscriptionInput
required
Input for provisioning a subscription

​
Return Type

Returns a ProvisionSubscriptionResult with:
FieldTypeDescription
subscriptionCustomerSubscriptionThe 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

Create paid subscription for customer on free plan.
Add subscription to additional product for existing customer.
Provision paid subscription when trial customer converts.