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

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

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": "[email protected]"
        }
      }
    }
  }
}

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 due to business rules

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.