Skip to content

Enroll Student to Course

The enrollStudentToCourse mutation allows you to enroll a student to a specified course, or update existing enrollment details. For paid or pre-order courses, this mutation automatically creates payment records using the specified curriculum plan’s pricing information.

Input Parameters

Field	Type	Required	Description
`userId`	`String`	No*	ID of the student (User) to enroll
`email`	`String`	No*	Email of the student. If user doesn’t exist, a placeholder user will be created
`name`	`String`	No	Name of the student. Required when creating a new user
`courseId`	`String!`	Yes	ID of the course to enroll the student into
`planId`	`String`	No	ID of the curriculum plan to apply to this enrollment. If not provided, will use the course’s first plan (ordered by creation date). For paid/pre-order courses, the plan’s `amount` and `currency` are used to create the payment record
`endedAt`	`Int`	No	Optional expiration date for the enrollment (Unix Timestamp)

*Note: Either userId or email must be provided.

Return Type

type AdminEnrollStudentToCoursePayload {
  # The created or updated enrollment
  enrollment: StudentCourseShip
}

StudentCourseShip Object

Field	Type	Description
`id`	`String!`	ID of the enrollment
`completionRate`	`Float`	The completion rate of the enrolled course which student achieved
`course`	`AdminCourse!`	Information of the enrolled course
`user`	`AdminUser!`	User information of the enrolled course
`createdAt`	`Int!`	Created date of the enrollment (Unix Timestamp)
`updatedAt`	`Int!`	Last updated date of the enrollment (Unix Timestamp)
`endedAt`	`Int`	Expiration date for the enrollment (Unix Timestamp)

Example

Enroll a new student to the course

mutation EnrollNewStudent {
  enrollStudentToCourse(
    courseId: "ab6ee332-614d-475d-93b5-abc5ebb1fc84"
    email: "student@example.com"
    name: "John Doe"   # Required when creating a new user
  ) {
    enrollment {
      id
      completionRate
      createdAt
      updatedAt
      endedAt
      course {
        id
        name
        slug
      }
      user {
        id
        name
        email
      }
    }
  }
}

Enroll student to paid course with specific plan

mutation EnrollStudentToPaidCourse {
  enrollStudentToCourse(
    courseId: "paid-course-123"
    email: "premium.student@example.com"
    name: "Premium Student"
    planId: "premium-plan-456"
    endedAt: 1735689600
  ) {
    enrollment {
      id
      completionRate
      endedAt
      course {
        id
        name
      }
      user {
        id
        name
        email
      }
    }
  }
}

Note: For paid or pre-order courses, this mutation creates a payment record with:

amount and currency from the specified plan
status set to manual_enrolled
A lineitem linking to the curriculum plan

For free or redeem courses, no payment record is created. If the student is already enrolled in a paid/pre-order course, the mutation returns the existing enrollment without creating a new payment.

Sample Response

{
  "data": {
    "enrollStudentToCourse": {
      "enrollment": {
        "id": "619ad939-8591-40ad-9364-cf3825a9bf70",
        "completionRate": 0.0,
        "createdAt": 1672531200,
        "updatedAt": 1672531200,
        "endedAt": null,
        "course": {
          "id": "ab6ee332-614d-475d-93b5-abc5ebb1fc84",
          "name": "Introduction to GraphQL",
          "slug": "intro-graphql"
        },
        "user": {
          "id": "387b0c87-0f85-44cc-833e-7306c1b5d3e6",
          "name": "John Doe",
          "email": "student@example.com"
        }
      }
    }
  }
}

Common Errors

Error	Description
`Either user_id or email must be provided`	At least one identifier must be provided
`Name is required when creating a new user`	Required when creating a new user via email
`Course not found`	The specified course ID does not exist
`User not found`	The specified user ID does not exist
`Public access courses don't require enrollment`	Public access courses don’t require enrollment
`No valid plan found for this course`	The specified planId is invalid for this course

Remove Student from Course - Remove a student’s enrollment
Expire Student Course Access - Mark access as expired
Extend Student Course Access - Extend access duration
Course Management - Overview of course operations

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