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

# Provision Subscription

Creates a new subscription for an existing customer.

## Mutation

<CodeGroup>
  ```graphql Mutation theme={null}
  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
      }
    }
  }
  ```

  ```json Variables theme={null}
  {
    "input": {
      "customerId": "customer-123",
      "planId": "plan-pro",
      "billingPeriod": "MONTHLY"
    }
  }
  ```

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

## Parameters

<ParamField body="input" type="ProvisionSubscriptionInput" required>
  Input for provisioning a subscription

  <Expandable title="properties">
    <ParamField body="customerId" type="String" required>
      Customer reference ID
    </ParamField>

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

    <ParamField body="billingPeriod" type="BillingPeriod">
      MONTHLY, ANNUAL
    </ParamField>

    <ParamField body="resourceId" type="String">
      Resource ID for multi-resource subscriptions
    </ParamField>

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

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

        <ParamField body="quantity" type="Int" required>
          Number of addon units
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField body="startDate" type="DateTime">
      When subscription should start (defaults to now)
    </ParamField>

    <ParamField body="cancellationDate" type="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](#trial-behavior) note below.
    </ParamField>

    <ParamField body="trialOverrideConfiguration" type="TrialOverrideConfigurationInput">
      Trial period override configuration

      <Expandable title="nested properties">
        <ParamField body="isTrial" type="Boolean" required>
          Whether to apply a trial period
        </ParamField>

        <ParamField body="trialEndDate" type="DateTime">
          Specific date when the trial ends
        </ParamField>

        <ParamField body="trialEndBehavior" type="TrialEndBehavior">
          Behavior when trial ends: `CANCEL_SUBSCRIPTION` or `CONVERT_TO_PAID`
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField body="appliedCoupon" type="SubscriptionCouponInput">
      Coupon to apply to the subscription

      <Expandable title="nested properties">
        <ParamField body="couponId" type="String">
          Stigg coupon ID
        </ParamField>
      </Expandable>
    </ParamField>

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

    <ParamField body="priceOverrides" type="[PriceOverrideInput]">
      Custom pricing overrides
    </ParamField>

    <ParamField body="entitlements" type="[SubscriptionEntitlementInputV2]">
      Entitlements to provision with the subscription (for custom plans). Supports both feature and credit entitlements.

      <Expandable title="nested properties">
        <ParamField body="feature" type="SubscriptionFeatureEntitlementInput">
          Feature entitlement configuration. Common fields shown below — see the [full type reference](/api-and-sdks/api-reference/types/subscription) for all available fields.

          <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>
          </Expandable>
        </ParamField>

        <ParamField body="credit" type="SubscriptionCreditEntitlementInput">
          Credit entitlement configuration

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

            <ParamField body="amount" type="Float" required>
              Number of credits to grant per cadence
            </ParamField>

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

    <ParamField body="awaitPaymentConfirmation" type="Boolean">
      Wait for payment before activating
    </ParamField>

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

## Return Type

Returns a `ProvisionSubscriptionResult` with:

| Field          | Type                 | Description              |
| -------------- | -------------------- | ------------------------ |
| `subscription` | CustomerSubscription | The created subscription |
| `entitlements` | \[Entitlement]       | Resulting entitlements   |

## Examples

### With Trial Period

```json theme={null}
{
  "input": {
    "customerId": "customer-123",
    "planId": "plan-pro",
    "trialOverrideConfiguration": {
      "isTrial": true,
      "trialEndBehavior": "CONVERT_TO_PAID"
    }
  }
}
```

### With Addons

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

### Scheduled Start

```json theme={null}
{
  "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.

```json theme={null}
{
  "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).

```json theme={null}
{
  "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

<AccordionGroup>
  <Accordion title="Upgrade from free">
    Create paid subscription for customer on free plan.
  </Accordion>

  <Accordion title="Multi-product subscription">
    Add subscription to additional product for existing customer.
  </Accordion>

  <Accordion title="Trial conversion">
    Provision paid subscription when trial customer converts.
  </Accordion>
</AccordionGroup>

## Related Operations

* [Provision Customer](/api-and-sdks/api-reference/mutations/provision-customer) - Create customer with subscription
* [Update Subscription](/api-and-sdks/api-reference/mutations/update-subscription) - Modify subscription
* [Preview Subscription](/api-and-sdks/api-reference/mutations/preview-subscription) - Preview pricing