Skip to content

Update 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 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`	`ID!`	The ID of the subscription to update
`currentPeriodEnd`	`ISO8601DateTime!`	New end date for the current subscription period, in ISO 8601 format (e.g., “2023-12-31T23:59:59Z”)

Return Type

type UpdateSubscriptionPayload {
  # 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: BigInt

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

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

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

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

  # 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: "2023-12-31T23:59:59Z"
  ) {
    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"
        }
      }
    }
  }
}

Common Errors

Error	Description
`Subscription not found`	The specified subscription ID does not exist
`Invalid date format`	The provided date is not in valid ISO 8601 format
`Date is in the past`	The new end date cannot be earlier than the current date
`Unauthorized`	The API key does not have permission to update this subscription

Usage Scenarios

Extending a Subscription

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

mutation ExtendSubscription {
  updateSubscription(
    id: "sub_12345",
    currentPeriodEnd: "2024-01-31T23:59:59Z"
  ) {
    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: "2023-07-15T23:59:59Z"
  ) {
    subscription {
      id
      currentPeriodEnd
      state
    }
    errors
  }
}

Create Subscription - Create a new subscription
Membership Plans - Available membership plans
Payments - Payment processing

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