Skip to content

Create Subscription

The createSubscription mutation allows you to programmatically create a new subscription for a user to a specific membership plan. This enables automatic enrollment in premium content or membership benefits.

Input Parameters

Field	Type	Description
`email`	`String!`	Email of the user to create subscription for
`name`	`String`	Name of the user (required if user doesn’t exist)
`planId`	`String!`	ID of the membership plan
`expireAt`	`Int`	Expiration date for fixed_date plans (Unix Timestamp)
`initialChargeAt`	`Int`	Initial charge date for recurring plans (Unix Timestamp)

Return Type

type CreateSubscriptionPayload {
  # Array of error messages, if any occurred during the operation
  errors: [String!]!

  # The created subscription object, null if operation failed
  subscription: AdminSubscription
}

AdminSubscription Object

type AdminSubscription {
  # Optional reason for subscription cancellation
  cancelReason: String

  # Type of cancellation, if applicable
  cancelType: String

  # When the subscription was created
  createdAt: Int!

  # End of the current billing period
  currentPeriodEnd: Int

  # Start of the current billing period
  currentPeriodStart: Int

  # Unix timestamp when the subscription ends
  endAt: Int

  # Unique identifier for the subscription
  id: String!

  # Indicates whether this subscription will be cancelled in the next billing cycle
  isCanceling: Boolean!

  # Indicates whether this subscription can be cancelled
  isCancellable: Boolean!

  # Timestamp of the next scheduled charge (null for non-recurring or inactive subscriptions)
  nextChargeDate: Int

  # The membership plan associated with this subscription
  plan: MembershipPlan!

  # The ID of the membership plan
  planId: String!

  # Unix timestamp when the subscription starts
  startAt: Int

  # The current state of the subscription
  state: String!

  # When the subscription was last updated
  updatedAt: Int!

  # The user who owns this subscription
  user: User!
}

Example

mutation CreateSubscription($email: String!, $planId: String!, $name: String) {
  createSubscription(
    email: $email
    name: $name
    planId: $planId
  ) {
    errors
    subscription {
      id
      state
      planId
      startAt
      endAt
      currentPeriodStart
      currentPeriodEnd
      nextChargeDate
      user {
        id
        email
        name
      }
      plan {
        id
        name
        interval
        intervalCount
      }
    }
  }
}

Variables

{
  "email": "[email protected]",
  "name": "John Doe",
  "planId": "plan_456"
}

Sample Response

{
  "data": {
    "createSubscription": {
      "errors": [],
      "subscription": {
        "id": "sub_12345",
        "state": "active",
        "planId": "plan_456",
        "startAt": 1687436400,
        "endAt": null,
        "currentPeriodStart": 1687436400,
        "currentPeriodEnd": 1690028799,
        "nextChargeDate": 1690028799,
        "user": {
          "id": "user_789",
          "email": "[email protected]",
          "name": "John Doe"
        },
        "plan": {
          "id": "plan_456",
          "name": "Premium Monthly",
          "interval": "month",
          "intervalCount": 1
        }
      }
    }
  }
}

Common Errors

Error	Description
`Plan not found`	The specified plan ID does not exist
`User already subscribed to this plan`	The user already has an active subscription to this plan
`Name is required for new users`	When creating a subscription for a new user, name must be provided
`Invalid plan type`	The expireAt parameter is only valid for fixed_date plan types
`Unauthorized`	The API key does not have permission to create subscriptions

Usage Scenarios

Creating a Subscription for an Existing User

mutation CreateExistingUserSubscription {
  createSubscription(
    email: "[email protected]",
    planId: "plan_monthly_123"
  ) {
    errors
    subscription {
      id
      state
      user { email }
      plan { name }
    }
  }
}

Creating a Subscription with Specific Expiration

For fixed_date plan types, you can specify when the subscription should expire:

mutation CreateFixedSubscription {
  createSubscription(
    email: "[email protected]",
    name: "New Student",
    planId: "plan_course_456",
    expireAt: 1704067199  # December 31, 2023 23:59:59 UTC
  ) {
    errors
    subscription {
      id
      endAt
    }
  }
}

Update Subscription - Update an existing subscription
Membership Plans - Available membership plans
User Management - User management APIs

For more information about the Teachify Admin API, please refer to the API Overview.