Subscriptions Query

Note: 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 Subscriptions API allows you to retrieve information about user subscriptions in your school. Each subscription represents a user’s access to a membership plan, including billing period details and cancellation status.

Available Queries

subscriptions

Returns a paginated list of subscriptions for the authenticated school.

Parameters:

Parameter	Type	Description
filter	AdminSubscriptionFilter	Filter criteria (see Filtering)
page	Int	Page number for pagination
perPage	Int	Number of items per page (default: 20, max: 50)
limit	Int	Alternative to perPage

Returns:

• AdminSubscriptionPage object with:
  • nodes: Array of AdminSubscription objects
  • currentPage: Current page number
  • hasNextPage: Whether there are more pages
  • hasPreviousPage: Whether there are previous pages
  • nodesCount: Total number of items matching the query
  • totalPages: Total number of pages

Example:

query {
  subscriptions(
    page: 1,
    perPage: 10
  ) {
    nodes {
      id
      state
      startAt
      endAt
      currentPeriodStart
      currentPeriodEnd
      planId
      isCanceling
      isCancellable
      nextChargeDate
      createdAt
      updatedAt
      plan {
        id
        name
      }
      user {
        id
        name
        email
      }
    }
    currentPage
    hasNextPage
    hasPreviousPage
    nodesCount
    totalPages
  }
}

Subscription Object

The AdminSubscription object contains the following fields:

Field	Type	Description
id	String!	Unique identifier
state	String!	Current state of the subscription (e.g., active, canceled, past_due)
startAt	Int	Unix Timestamp. When the subscription starts
endAt	Int	Unix Timestamp. When the subscription ends. For cancelled subscriptions, this represents the final termination date
currentPeriodStart	Int	Unix Timestamp. Start of the current billing period
currentPeriodEnd	Int	Unix Timestamp. End of the current billing period. For active subscriptions, this represents when the next payment will be due
planId	String!	The unique identifier of the associated membership plan
plan	MembershipPlan!	The membership plan associated with this subscription
isCanceling	Boolean!	Whether the subscription is scheduled for cancellation in the next billing cycle
isCancellable	Boolean!	Whether the subscription can be cancelled
nextChargeDate	Int	Timestamp of the next scheduled charge. Null for non-recurring or inactive subscriptions
user	User!	The user who owns this subscription
createdAt	Int!	Unix Timestamp. When the subscription was created
updatedAt	Int!	Unix Timestamp. When the subscription was last updated
cancelReason	String	The reason for cancellation if the subscription has been cancelled
cancelType	String	The type of cancellation (e.g., immediate, at_period_end)

Filtering

The subscriptions query accepts a filter parameter of type AdminSubscriptionFilter. This allows you to narrow down results based on various criteria.

Available Filters

Filter Field	Type	Description
id	StringOperator	Filter by subscription ID
state	StringOperator	Filter by subscription state (e.g., active, canceled, past_due)
planId	StringOperator	Filter by membership plan ID
userEmail	StringOperator	Filter by user email address

StringOperator

The StringOperator used in filters has these operations:

Operation	Description
eq	Equal to
neq	Not equal to
in	In a list of values
nin	Not in a list of values
like	Match text values against a pattern using wildcards (case-sensitive)
contains	Contains substring (case-insensitive)

Filter Examples

Find active subscriptions:

query {
  subscriptions(
    filter: {
      state: { eq: "active" }
    }
  ) {
    nodes {
      id
      state
      startAt
      endAt
      user {
        id
        name
        email
      }
    }
    nodesCount
  }
}

Find canceled subscriptions:

query {
  subscriptions(
    filter: {
      state: { eq: "canceled" }
    }
  ) {
    nodes {
      id
      state
      cancelReason
      cancelType
      endAt
      user {
        id
        email
      }
    }
    nodesCount
  }
}

Find subscriptions by plan:

query {
  subscriptions(
    filter: {
      planId: { eq: "plan-123" }
    }
  ) {
    nodes {
      id
      state
      startAt
      endAt
      plan {
        id
        name
      }
    }
    nodesCount
  }
}

Find subscriptions by user email:

query {
  subscriptions(
    filter: {
      userEmail: { contains: "alice" }
    }
  ) {
    nodes {
      id
      state
      user {
        id
        name
        email
      }
    }
    nodesCount
  }
}

Find active subscriptions for a specific plan:

query {
  subscriptions(
    filter: {
      state: { eq: "active" },
      planId: { eq: "plan-123" }
    }
  ) {
    nodes {
      id
      state
      currentPeriodStart
      currentPeriodEnd
      nextChargeDate
    }
    nodesCount
  }
}

Find subscriptions with multiple states:

query {
  subscriptions(
    filter: {
      state: { in: ["active", "past_due"] }
    }
  ) {
    nodes {
      id
      state
      user {
        id
        email
      }
    }
    nodesCount
  }
}