Coupons 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 Coupon API allows you to retrieve information about discount coupons in your school. Coupons enable you to offer promotional discounts on your courses, events, and other products. This API provides access to coupon details, usage statistics, and filtering capabilities.

Available Queries

`coupons`

Returns a paginated list of coupons for the authenticated school.

Parameters:

Parameter	Type	Description
`filter`	AdminCouponFilter	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:

AdminCouponPage object with:
- nodes: Array of AdminCoupon objects
- currentPage: Current page number
- hasNextPage: Whether there are more pages
- hasPreviousPage: Whether there are previous pages
- nodesCount: Total number of items across all pages
- totalPages: Total number of pages

Example:

query {
  coupons(
    filter: {
      active: true,
      code: { like: "SUMMER%" }
    },
    page: 1,
    perPage: 10
  ) {
    nodes {
      id
      name
      code
      amount
      couponType
      active
      appliedCount
      expiredAt
    }
    currentPage
    hasNextPage
    hasPreviousPage
    nodesCount
    totalPages
  }
}

`couponGrants`

Returns one coupon’s member grants, paginated, newest grantedAt first. Requires the coupons:read and students:read scopes (members:read is accepted in place of students:read), since each grant carries the member’s name and email.

Parameters:

Parameter	Type	Description
`couponId`	String!	ID of the coupon. A coupon that is not in your school, or is deleted, returns an empty page
`status`	[AdminCouponGrantStatus!]	Only grants in these statuses: `granted`, `redeemed`, `revoked`, `expired`. Omit to return every status; an empty list returns none
`filter`	AdminCouponGrantFilter	`userId` or `userEmail` (StringOperator). `userEmail` is matched case-insensitively. For `userId` use `eq` or `in`; `like` and `contains` are ignored on IDs
`page`	Int	Page number for pagination
`perPage`	Int	Number of items per page (default: 20, max: 50)
`limit`	Int	Alternative to perPage

Returns: an AdminCouponGrantPage with the same pagination fields as coupons; nodes holds AdminCouponGrant objects.

Example: find a member’s grant so it can be revoked with revokeCouponGrant. Any grant whose revokedAt is null can be revoked, including a redeemed one or one whose coupon has expired:

query {
  couponGrants(
    couponId: "4f0c2a9e-7b1d-4c3e-9a52-8d6e1f3b7c20",
    filter: { userEmail: { eq: "member@example.com" } }
  ) {
    nodes {
      id
      status
      userEmail
      grantedAt
      revokedAt
    }
    nodesCount
  }
}

AdminCoupon Object

The AdminCoupon object contains the following fields based on the schema:

Field	Type	Description
`id`	String!	Unique identifier
`name`	String!	Name of the coupon
`code`	String!	Unique coupon code that users enter to apply the discount
`description`	String	Optional description of the coupon
`amount`	Float!	Discount amount (in currency units or percentage based on couponType)
`couponType`	String!	Type of discount: “fixed_amount” or “percentage”
`currency`	String!	Currency code (e.g., USD, EUR) in ISO 4217 format
`currencySymbol`	String!	Currency symbol (e.g., $, €, £, ¥)
`active`	Boolean!	Whether the coupon is currently active
`restricted`	Boolean!	Whether the coupon is grant-only: only members holding a grant for it can redeem it. Only a restricted coupon can be granted with `createCouponGrant`
`oncePerUser`	Boolean!	Whether each member may redeem the coupon only once
`singleProduct`	Boolean!	Whether coupon applies to a single product only
`appliedCount`	Int!	Number of times the coupon has been used
`redemptionLimit`	Int	Maximum number of times the coupon can be used (null for unlimited). Not enforced for restricted coupons
`startedAt`	Int	When the coupon becomes valid
`expiredAt`	Int	When the coupon expires
`state`	String!	Lifecycle state: `scheduled`, `activated` or `expired`. Coupons created through the API or the school admin stay `scheduled`, so do not use it to tell whether a coupon can be redeemed; use `active`, `startedAt` and `expiredAt`
`items`	[JSON!]	Related products the coupon can be applied to
`applicableItems`	[AdminCouponApplicableItem!]!	Labelled products the coupon applies to. A course or event lists its plans or tickets as `children`. Empty when the coupon applies to every product
`grants`	[AdminCouponGrant!]!	All grants of the coupon in one unpaginated list, revoked ones included, ordered by `grantedAt` descending. Requires `students:read` or `members:read`, as `couponGrants` does. Use `couponGrants` to page through them or find one member’s grant. See AdminCouponGrant
`createdAt`	Int!	When the coupon was created
`updatedAt`	Int!	When the coupon was last updated

Filtering

The coupons query supports filtering through the filter parameter. The following filter fields are available:

Filter Field	Type	Description
`id`	StringOperator	Filter by coupon ID
`code`	StringOperator	Filter by coupon code
`name`	StringOperator	Filter by coupon name
`couponType`	StringOperator	Filter by coupon type (fixed_amount, percentage)
`state`	StringOperator	Filter by coupon state (scheduled, activated, expired). See the `state` field above
`active`	Boolean	Filter for active/inactive coupons
`singleProduct`	Boolean	Filter for single product coupons

StringOperator Filters

String fields can be filtered using the following operators:

Operator	Description	Example
`eq`	Equal to	`{ code: { eq: "SUMMER2023" } }`
`neq`	Not equal to	`{ code: { neq: "SUMMER2023" } }`
`in`	In a list of values	`{ code: { in: ["SUMMER2023", "FALL2023"] } }`
`nin`	Not in a list of values	`{ code: { nin: ["EXPIRED2022"] } }`
`like`	Pattern matching (case-sensitive)	`{ code: { like: "SUMMER%" } }`

Filter Examples

Find active percentage-based coupons:

query {
  coupons(
    filter: {
      active: true,
      couponType: { eq: "percentage" }
    }
  ) {
    nodes {
      id
      name
      code
      amount
      appliedCount
    }
  }
}

Find coupons by name pattern:

query {
  coupons(
    filter: {
      name: { like: "Summer%" }
    }
  ) {
    nodes {
      id
      name
      code
      amount
      couponType
    }
  }
}

Relationships

The Coupon API indirectly relates to:

Products: Coupons can be applied to one or more products (courses, events, etc.)
Payments: Payments track the application of coupons as adjustments
Users: Users apply coupons during checkout

Detailed Query Structure

Below is a comprehensive view of fields available in the coupons query based on the schema:

query {
  coupons(
    filter: {
      id: { eq: "4f0c2a9e-7b1d-4c3e-9a52-8d6e1f3b7c20" } # Filter by ID (StringOperator)
      code: { like: "WELCOME%" }           # Filter by code pattern (StringOperator)
      name: { like: "Welcome%" }           # Filter by name pattern (StringOperator)
      couponType: { eq: "percentage" }     # Filter by coupon type (StringOperator)
      state: { eq: "scheduled" }           # Filter by state (StringOperator)
      active: true                         # Filter for active coupons (Boolean)
      singleProduct: false                 # Filter for multi-product coupons (Boolean)
    },
    page: 1,                               # Page number (Int)
    perPage: 20                            # Items per page (Int)
  ) {
    nodes {
      id                                   # Unique identifier (String!)
      name                                 # Coupon name (String!)
      code                                 # Coupon code (String!)
      description                          # Optional description (String)

      # Discount information
      amount                               # Discount amount (Float!)
      couponType                           # Type of discount: fixed_amount or percentage (String!)
      currency                             # Currency code (String!)
      currencySymbol                       # Currency symbol (String!)

      # Status fields
      active                               # Whether the coupon is active (Boolean!)
      restricted                           # Grant-only coupon (Boolean!)
      oncePerUser                          # Each member may redeem it only once (Boolean!)
      singleProduct                        # Whether coupon applies to single product only (Boolean!)

      # Usage statistics
      appliedCount                         # Number of times used (Int!)
      redemptionLimit                      # Maximum usage limit (Int)

      # Time-related fields
      startedAt                            # When the coupon becomes valid (Int)
      expiredAt                            # When the coupon expires (Int)
      state                                # Lifecycle state (String!)
      createdAt                            # Creation timestamp (Int!)
      updatedAt                            # Last update timestamp (Int!)

      # Related items
      items                                # Products the coupon can be applied to ([JSON!])
      applicableItems {                    # Labelled products, empty when it applies to everything
        id
        label
        type
        amount
        children { id label type amount }  # Plans of a course, tickets of an event
      }

      # Grants (restricted coupons)
      grants {                             # Every grant, revoked ones included
        id
        status
        userEmail
        grantedAt
        redeemedAt
        revokedAt
      }
    }

    # Pagination information
    currentPage                            # Current page number (Int!)
    hasNextPage                            # Whether there are more pages (Boolean!)
    hasPreviousPage                        # Whether there are previous pages (Boolean!)
    nodesCount                             # Total number of items across all pages (Int!)
    totalPages                             # Total number of pages (Int!)
  }
}

Coupon Mutations — create and update coupons, and grant or revoke grant-only (restricted) coupons for members