Provision Customer

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

Mutation

Mutation

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

{
  "input": {
    "customerId": "customer-123",
    "name": "Acme Corp",
    "email": "[e-mail]",
    "subscriptionParams": {
      "planId": "plan-pro",
      "billingPeriod": "MONTHLY"
    }
  }
}

{
  "data": {
    "provisionCustomer": {
      "customer": {
        "customerId": "customer-123",
        "name": "Acme Corp",
        "email": "[e-mail]",
        "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"
    }
  }
}

Parameters

input · ProvisionCustomerInput · required

Input for provisioning a customer

Show properties

customerId · String · required

Your unique identifier for this customer

name · String

Customer display name

email · String

Customer email address

billingId · String

Existing billing provider customer ID (e.g., Stripe customer ID)

billingInformation · CustomerBillingInfo

Billing details for invoice generation

couponRefId · String

Coupon code to apply at customer level

additionalMetaData · JSON

Custom metadata for the customer

subscriptionParams · SubscriptionParams

Optional subscription to create

Show nested properties

planId · String · required

Plan reference ID

billingPeriod · BillingPeriod

MONTHLY, ANNUAL

addons · [SubscriptionAddonInput]

Addons to include

startDate · DateTime

When subscription should start

trialConfig · TrialConfigInput

Trial period configuration

couponId · String

Coupon to apply to subscription

billableFeatures · [BillableFeatureInput]

Initial quantities for usage-based features

environmentId · UUID

Environment ID

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

{
  "input": {
    "customerId": "customer-123",
    "name": "Acme Corp",
    "email": "[e-mail]"
  }
}

Customer with Free Plan

{
  "input": {
    "customerId": "customer-123",
    "name": "Acme Corp",
    "email": "[e-mail]",
    "subscriptionParams": {
      "planId": "plan-free"
    }
  }
}

Customer with Trial

{
  "input": {
    "customerId": "customer-123",
    "name": "Acme Corp",
    "email": "[e-mail]",
    "subscriptionParams": {
      "planId": "plan-pro",
      "trialConfig": {
        "duration": 14,
        "units": "DAYS"
      }
    }
  }
}

Customer with Addons

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

Common Use Cases

User signup

Create customer when user signs up, optionally with a free or trial plan.

Upgrade from anonymous

Provision customer when anonymous user converts to registered.

B2B onboarding

Create organization customer with initial subscription during onboarding.

Related Operations

• Create Customer - Create customer without subscription
• Provision Subscription - Add subscription to existing customer
• Get Customer - Retrieve customer