Skip to main content
Creates a new customer and optionally provisions an initial subscription in a single operation.

​
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": "billing@acme.com",
    "subscriptionParams": {
      "planId": "plan-pro",
      "billingPeriod": "MONTHLY"
    }
  }
}

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

​
Parameters

​
input
ProvisionCustomerInput
required
Input for provisioning a customer

​
Return Type

Returns a ProvisionedCustomer object with:
FieldTypeDescription
customerCustomerThe created customer
subscriptionCustomerSubscriptionThe created subscription (if requested)
entitlements[Entitlement]Resulting entitlements
subscriptionDecisionStrategySubscriptionDecisionStrategyHow subscription was determined

​
Examples

​
Basic Customer Creation

{
  "input": {
    "customerId": "customer-123",
    "name": "Acme Corp",
    "email": "billing@acme.com"
  }
}

​
Customer with Free Plan

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

​
Customer with Trial

{
  "input": {
    "customerId": "customer-123",
    "name": "Acme Corp",
    "email": "billing@acme.com",
    "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

Create customer when user signs up, optionally with a free or trial plan.
Provision customer when anonymous user converts to registered.
Create organization customer with initial subscription during onboarding.