Coupon 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 in the current page
- 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
  }
}

AdminCoupon Object

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

Field	Type	Description
`id`	ID!	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
`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)
`startedAt`	ISO8601DateTime	When the coupon becomes valid
`expiredAt`	ISO8601DateTime	When the coupon expires
`state`	String!	Current state of the coupon
`items`	[JSON!]	Related products the coupon can be applied to
`createdAt`	ISO8601DateTime!	When the coupon was created
`updatedAt`	ISO8601DateTime!	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
`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: "coupon_123" }             # 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: "active" }              # 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 (ID!)
      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!)
      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 (ISO8601DateTime)
      expiredAt                            # When the coupon expires (ISO8601DateTime)
      state                                # Current state (String!)
      createdAt                            # Creation timestamp (ISO8601DateTime!)
      updatedAt                            # Last update timestamp (ISO8601DateTime!)

      # Related items
      items                                # Products the coupon can be applied to ([JSON!])
    }

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