Skip to content

Create Subscription

Important: The Teachify Admin API is currently under development and not yet available for public use. This documentation is provided for preview purposes only.

Overview

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`	`ID!`	ID of the membership plan
`expireAt`	`BigInt`	Expiration date for fixed_date plans (Unix Timestamp)
`initialChargeAt`	`BigInt`	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: ISO8601DateTime!

  # End of the current billing period
  currentPeriodEnd: BigInt

  # Start of the current billing period
  currentPeriodStart: BigInt

  # Unix timestamp when the subscription ends
  endAt: BigInt

  # 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: BigInt

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

  # The ID of the membership plan
  planId: String!

  # Unix timestamp when the subscription starts
  startAt: BigInt

  # The current state of the subscription
  state: String!

  # When the subscription was last updated
  updatedAt: ISO8601DateTime!

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

Example

mutation CreateSubscription($email: String!, $planId: ID!, $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": "john@example.com",
  "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": "john@example.com",
          "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: "existing@example.com",
    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: "student@example.com",
    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.