integrations

Create a coupon (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
POST /admin/billing/coupons
Access token

Creates the coupon in Stripe, keeps a local copy for search and returns it. Send exactly one of percentOff or amountOffCents (with currency); durationInMonths is required with duration: repeating and not allowed otherwise. Breaking either rule returns 400. Super admin only.

application/json

Body Required

  • couponId string

    Stripe coupon id — THIS IS THE REDEEMABLE CODE customers type. Stripe generates a random one when omitted.

  • name string

    Human-readable name shown on the invoice

  • percentOff number

    Percent discount, 1-100. Mutually exclusive with amountOffCents.

  • amountOffCents number

    Fixed discount in cents. Requires currency.

  • currency string

    ISO currency, required with amountOffCents

  • duration string Required

    Values are once, repeating, or forever.

  • durationInMonths number

    Months to repeat for — required when duration is "repeating"

  • maxRedemptions number

    Total redemptions allowed across all customers

  • redeemBy string(date-time)

    Cannot be applied after this instant (ISO 8601)

  • appliesToProducts array[string]

    Restrict the discount to these Stripe product ids

  • metadata object
  • reason string

    Audit note — why this coupon was issued

Responses

  • 201 application/json
    Hide response attributes Show response attributes object
    • data object Required
      Hide data attributes Show data 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
    • statusCode number Required
    • timestamp string(date-time) Required
POST /admin/billing/coupons 
curl \
 --request POST 'http://api.example.com/admin/billing/coupons' \
 --header "Authorization: Bearer $ACCESS_TOKEN" \
 --header "Content-Type: application/json" \
 --data '{
  "couponId": "string",
  "name": "string",
  "percentOff": 42.0,
  "amountOffCents": 42.0,
  "currency": "usd",
  "duration": "once",
  "durationInMonths": 42.0,
  "maxRedemptions": 42.0,
  "redeemBy": "2026-05-04T09:42:00Z",
  "appliesToProducts": [
    "string"
  ],
  "metadata": {},
  "reason": "string"
}'
Request examples 
{
  "couponId": "string",
  "name": "string",
  "percentOff": 42.0,
  "amountOffCents": 42.0,
  "currency": "usd",
  "duration": "once",
  "durationInMonths": 42.0,
  "maxRedemptions": 42.0,
  "redeemBy": "2026-05-04T09:42:00Z",
  "appliesToProducts": [
    "string"
  ],
  "metadata": {},
  "reason": "string"
}
Response examples (201) 
{
  "data": {
    "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"
  },
  "statusCode": 201,
  "timestamp": "2026-01-15T10:15:00.000Z"
}