Skip to content

Update Subscription

The updateSubscription mutation allows you to update an existing subscription’s end period. This mutation is particularly useful for extending or shortening subscription periods based on business rules or customer service needs.

Input Parameters

Field	Type	Description
`id`	`String!`	The ID of the subscription to update
`currentPeriodEnd`	`Int!`	New end date for the current subscription period (Unix Timestamp)

Note: Lifetime subscriptions cannot have their period updated. Attempting to update a lifetime subscription will return an error, as lifetime plans grant permanent access and do not have billing periods.

Return Type

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

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

Subscription Object

type Subscription {
  # The unique identifier for the subscription
  id: String!

  # The timestamp when the current billing period ends
  currentPeriodEnd: Int

  # The timestamp when the current billing period started
  currentPeriodStart: Int

  # The timestamp when the subscription will end (for non-recurring subscriptions)
  endAt: Int

  # Indicates whether this subscription will be cancelled at the end of the current period
  isCanceling: Boolean!

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

  # The timestamp of the next scheduled charge (null for non-recurring subscriptions)
  nextChargeDate: Int

  # List of payments associated with this subscription
  payments: [Payment!]

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

  # The ID of the membership plan
  planId: String!

  # The timestamp when the subscription started
  startAt: Int

  # The current state of the subscription
  # Possible values: active, incomplete, incomplete_expired, trialing, past_due, canceled, expired
  state: String!

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

Example

mutation UpdateSubscription {
  updateSubscription(
    id: "sub_12345",
    currentPeriodEnd: 1704067199
  ) {
    errors
    subscription {
      id
      currentPeriodEnd
      currentPeriodStart
      state
      isCanceling
      user {
        id
        name
        email
      }
      plan {
        id
        name
      }
    }
  }
}

Sample Response

{
  "data": {
    "updateSubscription": {
      "errors": [],
      "subscription": {
        "id": "sub_12345",
        "currentPeriodEnd": "1704067199",
        "currentPeriodStart": "1701388800",
        "state": "active",
        "isCanceling": false,
        "user": {
          "id": "user_789",
          "name": "John Doe",
          "email": "john@example.com"
        },
        "plan": {
          "id": "plan_456",
          "name": "Premium Annual"
        }
      }
    }
  }
}

Restrictions for Canceling Subscriptions

If a subscription is in a canceling state (i.e., isCanceling: true - the user has already requested cancellation but it’s scheduled for a future date), all update operations are blocked. This is consistent with the UI behavior.

Operation	Allowed?	Error Message
Extend period	No	”Cannot update a subscription that is pending cancellation. Use cancelSubscription mutation instead.”
Shorten period	No	”Cannot update a subscription that is pending cancellation. Use cancelSubscription mutation instead.”
Set past timestamp	No	”Cannot update a subscription that is pending cancellation. Use cancelSubscription mutation instead.”

Note: To immediately cancel a subscription that is pending cancellation, use the cancelSubscription mutation instead. The cancelSubscription mutation will immediately terminate the subscription regardless of the originally scheduled cancellation date.

Common Errors

Error	Description
`Subscription not found`	The specified subscription ID does not exist
`Cannot update period for lifetime subscriptions`	Lifetime plans grant permanent access and do not have billing periods that can be updated
`Cannot update an already cancelled subscription`	The subscription has already been fully cancelled (`state: canceled`)
`Cannot update a subscription that is pending cancellation. Use cancelSubscription mutation instead.`	The subscription is in `canceling` state; all operations are blocked. Use CancelSubscription for early cancellation.
`Timestamp cannot be more than 10 years in the future`	The provided timestamp exceeds the maximum allowed value
`Timestamp cannot be more than 1 year in the past`	The provided timestamp is too far in the past
`Cannot set end date earlier than current period start`	The new end date cannot be before the subscription’s current period start date

Usage Scenarios

Extending a Subscription

Extend a subscription that’s about to expire for a loyal customer:

mutation ExtendSubscription {
  updateSubscription(
    id: "sub_12345",
    currentPeriodEnd: 1706745599  # Example: January 31, 2024 23:59:59 UTC
  ) {
    subscription {
      id
      currentPeriodEnd
      user { name }
    }
    errors
  }
}

Shortening a Trial Period

Adjust the end date of a trial subscription:

mutation ShortenTrial {
  updateSubscription(
    id: "sub_trial_789",
    currentPeriodEnd: 1689465599  # Example: July 15, 2023 23:59:59 UTC
  ) {
    subscription {
      id
      currentPeriodEnd
      state
    }
    errors
  }
}

Create Subscription - Create a new subscription
Cancel Subscription - Cancel an existing subscription (including early cancellation for pending cancellations)
Membership Plans - Available membership plans
Payments - Payment processing

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