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

Creates a new customer and optionally provisions an initial subscription in a single operation.

## Mutation

<CodeGroup>
  ```graphql Mutation theme={null}
  mutation ProvisionCustomer($input: ProvisionCustomerInput!) {
    provisionCustomer(input: $input) {
      customer {
        customerId
        name
        email
        billingId
        createdAt
      }
      subscription {
        subscriptionId
        status
        plan {
          refId
          displayName
        }
        trialEndDate
      }
      entitlements {
        feature {
          refId
          displayName
        }
        isGranted
        usageLimit
      }
      subscriptionDecisionStrategy
    }
  }
  ```

  ```json Variables theme={null}
  {
    "input": {
      "customerId": "customer-123",
      "name": "Acme Corp",
      "email": "billing@acme.com",
      "subscriptionParams": {
        "planId": "plan-pro",
        "billingPeriod": "MONTHLY"
      }
    }
  }
  ```

  ```json Response theme={null}
  {
    "data": {
      "provisionCustomer": {
        "customer": {
          "customerId": "customer-123",
          "name": "Acme Corp",
          "email": "billing@acme.com",
          "billingId": "cus_ABC123",
          "createdAt": "2024-01-15T10:30:00Z"
        },
        "subscription": {
          "subscriptionId": "sub-456",
          "status": "ACTIVE",
          "plan": {
            "refId": "plan-pro",
            "displayName": "Pro Plan"
          },
          "trialEndDate": null
        },
        "entitlements": [
          {
            "feature": {
              "refId": "feature-api-calls",
              "displayName": "API Calls"
            },
            "isGranted": true,
            "usageLimit": 10000
          }
        ],
        "subscriptionDecisionStrategy": "REQUESTED_PLAN"
      }
    }
  }
  ```
</CodeGroup>

## Parameters

<ParamField body="input" type="ProvisionCustomerInput" required>
  Input for provisioning a customer

  <Expandable title="properties">
    <ParamField body="customerId" type="String" required>
      Your unique identifier for this customer
    </ParamField>

    <ParamField body="name" type="String">
      Customer display name
    </ParamField>

    <ParamField body="email" type="String">
      Customer email address
    </ParamField>

    <ParamField body="billingId" type="String">
      Existing billing provider customer ID (e.g., Stripe customer ID)
    </ParamField>

    <ParamField body="billingInformation" type="CustomerBillingInfo">
      Billing details for invoice generation
    </ParamField>

    <ParamField body="couponRefId" type="String">
      Coupon code to apply at customer level
    </ParamField>

    <ParamField body="additionalMetaData" type="JSON">
      Custom metadata for the customer
    </ParamField>

    <ParamField body="subscriptionParams" type="SubscriptionParams">
      Optional subscription to create

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

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

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

        <ParamField body="startDate" type="DateTime">
          When subscription should start
        </ParamField>

        <ParamField body="trialConfig" type="TrialConfigInput">
          Trial period configuration
        </ParamField>

        <ParamField body="couponId" type="String">
          Coupon to apply to subscription
        </ParamField>

        <ParamField body="billableFeatures" type="[BillableFeatureInput]">
          Initial quantities for usage-based features
        </ParamField>
      </Expandable>
    </ParamField>

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

## Return Type

Returns a `ProvisionedCustomer` object with:

| Field                          | Type                         | Description                             |
| ------------------------------ | ---------------------------- | --------------------------------------- |
| `customer`                     | Customer                     | The created customer                    |
| `subscription`                 | CustomerSubscription         | The created subscription (if requested) |
| `entitlements`                 | \[Entitlement]               | Resulting entitlements                  |
| `subscriptionDecisionStrategy` | SubscriptionDecisionStrategy | How subscription was determined         |

## Examples

### Basic Customer Creation

```json theme={null}
{
  "input": {
    "customerId": "customer-123",
    "name": "Acme Corp",
    "email": "billing@acme.com"
  }
}
```

### Customer with Free Plan

```json theme={null}
{
  "input": {
    "customerId": "customer-123",
    "name": "Acme Corp",
    "email": "billing@acme.com",
    "subscriptionParams": {
      "planId": "plan-free"
    }
  }
}
```

### Customer with Trial

```json theme={null}
{
  "input": {
    "customerId": "customer-123",
    "name": "Acme Corp",
    "email": "billing@acme.com",
    "subscriptionParams": {
      "planId": "plan-pro",
      "trialConfig": {
        "duration": 14,
        "units": "DAYS"
      }
    }
  }
}
```

### Customer with Addons

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

## Common Use Cases

<AccordionGroup>
  <Accordion title="User signup">
    Create customer when user signs up, optionally with a free or trial plan.
  </Accordion>

  <Accordion title="Upgrade from anonymous">
    Provision customer when anonymous user converts to registered.
  </Accordion>

  <Accordion title="B2B onboarding">
    Create organization customer with initial subscription during onboarding.
  </Accordion>
</AccordionGroup>

## Related Operations

* [Create Customer](/api-and-sdks/api-reference/mutations/create-customer) - Create customer without subscription
* [Provision Subscription](/api-and-sdks/api-reference/mutations/provision-subscription) - Add subscription to existing customer
* [Get Customer](/api-and-sdks/api-reference/queries/get-customer) - Retrieve customer