Skip to content

Cancel Subscription

The cancelSubscription mutation allows you to programmatically cancel an active subscription for a user. This enables you to revoke access to premium content or membership benefits at the end of the current billing period or immediately.

Input Parameters

Field	Type	Required	Description
`id`	`String!`	Yes	ID of the subscription to cancel
`cancelAtPeriodEnd`	`Boolean`	No	If true, cancels at period end; if false, cancels immediately or at specified time (default: true)
`customEndedAt`	`Int`	No	Specific time to end the subscription as Unix Timestamp (seconds since epoch). Overrides the default behavior

Note: Lifetime subscriptions cannot be cancelled as they represent one-time purchases with permanent access. The isCancellable field will return false for lifetime subscriptions.

Return Type

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

  # The cancelled subscription object, null if operation failed
  subscription: Subscription
}

Subscription Object

type Subscription {
  id: String!

  # Unix Timestamp. The date when the subscription was cancelled. Null if not cancelled.
  canceledAt: Int

  # Unix Timestamp. The end date of the current billing period. For active subscriptions, this represents when the next payment will be due.
  currentPeriodEnd: Int

  # Unix Timestamp. The start date of the current billing period.
  currentPeriodStart: Int

  # Unix Timestamp. The date when the subscription ends. For cancelled subscriptions, this represents the final termination date.
  endAt: Int

  # 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

  payments: [Payment!]
  plan: MembershipPlan!
  planId: String!

  # Unix Timestamp. The date when the subscription starts.
  startAt: Int

  # Possible values: active, incomplete, incomplete_expired, trialing, past_due, canceled, expired
  state: String!

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

Example

mutation CancelSubscription {
  cancelSubscription(
    id: "sub_12345"
    cancelAtPeriodEnd: true
  ) {
    errors
    subscription {
      id
      planId
      startAt
      endAt
      isCanceling
      state
      user {
        id
        name
        email
      }
    }
  }
}

Example - Immediate Cancellation

mutation CancelSubscriptionImmediately {
  cancelSubscription(
    id: "sub_12345"
    cancelAtPeriodEnd: false
  ) {
    errors
    subscription {
      id
      state
      endAt
      canceledAt
    }
  }
}

Early Cancellation (for subscriptions pending cancellation)

If a subscription is already in a canceling state (i.e., isCanceling: true - the user has already requested cancellation but it’s scheduled for a future date), you can use this mutation to immediately cancel the subscription.

Behavior

When calling cancelSubscription on a subscription that is already canceling:

Aspect	Behavior
`cancelAtPeriodEnd` parameter	Ignored - always cancels immediately
`customEndedAt` parameter	Ignored - always cancels immediately
Result	Subscription is immediately cancelled (`state: "canceled"`)
`cancelAt`	Set to `null` (scheduled cancellation is cleared)
`endAt`	Set to current time

Example - Early Cancel a Pending Cancellation

mutation EarlyCancelSubscription {
  cancelSubscription(
    id: "sub_12345"
  ) {
    errors
    subscription {
      id
      state
      isCanceling
      cancelAt
      endAt
      canceledAt
    }
  }
}

Sample Response - Early Cancellation

{
  "data": {
    "cancelSubscription": {
      "errors": [],
      "subscription": {
        "id": "1af2d4fc-1bfb-4e03-a11d-6254bf175adb",
        "state": "canceled",
        "isCanceling": false,
        "cancelAt": null,
        "endAt": 1736956800,
        "canceledAt": 1736956800
      }
    }
  }
}

Note: This is useful when a student has already initiated a cancellation request, but an administrator needs to immediately terminate the subscription (e.g., due to a refund agreement or policy violation).

Sample Response

{
  "data": {
    "cancelSubscription": {
      "errors": [],
      "subscription": {
        "id": "1af2d4fc-1bfb-4e03-a11d-6254bf175adb",
        "planId": "sub_id_12345",
        "startAt": 1745561281,
        "endAt": 1748153281,
        "isCanceling": true,
        "state": "active",
        "user": {
          "id": "abaed4c4-4d48-4118-a3e8-34d89d540335",
          "name": "Student",
          "email": "student@example.com"
        }
      }
    }
  }
}

Common Errors

Error	Description
`Subscription not found`	The specified subscription ID does not exist
`Subscription already cancelled`	The subscription is already in a cancelled state
`Subscription is not cancellable`	The subscription cannot be cancelled. This applies to lifetime subscriptions which represent one-time purchases with permanent access

Create Subscription - Create a new subscription for a user
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.