integrations

List coupons (internal)

Add MCP server to your AI tool

Allow AI tools and LLMs to interact with the API documentation portal through MCP.

MCP server URL

https://docs.usehearsay.com/mcp

Standard setup for AI tools providing an mcp.json file

mcp.json 
{
  "integrations MCP server": {
    "url": "https://docs.usehearsay.com/mcp"
  }
}
Close
GET /admin/billing/coupons
Access token

Lists coupons newest first with the total that match, filtered by status (active, expired or deleted, worked out from the expiry and deletion dates), duration, creation date range and a case-insensitive search on code and name. limit defaults to 50 (at most 200). Super admin only.

Query parameters

  • status string

    active = not deleted and not past redeemBy; expired = past redeemBy; deleted = withdrawn in Stripe

    Values are active, expired, or deleted.

  • duration string

    Values are once, repeating, or forever.

  • createdFrom string(date-time)

    Created at or after (ISO 8601)

  • createdTo string(date-time)

    Created at or before (ISO 8601)

  • limit number
  • skip number

Responses

  • 200 application/json
    Hide response attributes Show response attributes object
    • data object Required
      Hide data attributes Show data attributes object
      • coupons array[object] Required
        Hide coupons attributes Show coupons attributes object
        • couponId string Required

          Stripe coupon id — the redeemable code

        • name string | null Required
        • percentOff number | null Required
        • amountOffCents number | null Required
        • currency string | null Required
        • duration string Required

          Values are once, repeating, or forever.

        • durationInMonths number | null Required
        • maxRedemptions number | null Required
        • redeemBy string(date-time) | null Required
        • timesRedeemed number Required
        • status string Required

          Derived from deletedAt/redeemBy at read time, never stored

          Values are active, expired, or deleted.

        • reason string | null Required
        • deletedAt string(date-time) | null Required
      • total number Required

        Total matching the filter, ignoring limit/skip

    • statusCode number Required
    • timestamp string(date-time) Required
GET /admin/billing/coupons 
curl \
 --request GET 'http://api.example.com/admin/billing/coupons' \
 --header "Authorization: Bearer $ACCESS_TOKEN"
Response examples (200) 
{
  "data": {
    "coupons": [
      {
        "couponId": "SPRING20",
        "name": "Spring 20% off",
        "percentOff": 20,
        "amountOffCents": 42.0,
        "currency": "string",
        "duration": "repeating",
        "durationInMonths": 3,
        "maxRedemptions": 50,
        "redeemBy": "2026-06-30T23:59:59.000Z",
        "timesRedeemed": 4,
        "status": "active",
        "reason": "Spring promotion approved by sales",
        "deletedAt": "2026-05-04T09:42:00Z"
      }
    ],
    "total": 1
  },
  "statusCode": 200,
  "timestamp": "2026-01-15T10:15:00.000Z"
}