Coupons

Overview

Coupons let you gift credits or subscription plans to other users. Create coupons from your balance and share the codes with recipients.

Credits for coupons are deducted from your balance credits (not plan credits).

Create a Credits Coupon

Endpoint

POST /v1/coupons/create

Request

Parameter	Type	Required	Description
`credits`	number	✅	Credits to gift (100 - 100,000)
`message`	string	❌	Optional gift message
`expirationDays`	number	❌	Days until expiration (default: 30)

Example

curl -X POST https://api.ender.black/v1/coupons/create \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "credits": 1000,
    "message": "Enjoy!",
    "expirationDays": 30
  }'

Response

{
  "success": true,
  "data": {
    "code": "GIFT-A1B2C3D4",
    "credits": 1000,
    "message": "Enjoy!",
    "expiresAt": "2026-01-31T00:00:00.000Z",
    "createdAt": "2026-01-01T00:00:00.000Z"
  }
}

Redeem a Coupon

Endpoint

POST /v1/coupons/redeem

Request

{
  "code": "GIFT-A1B2C3D4"
}

Response (Credits Coupon)

{
  "success": true,
  "data": {
    "type": "CREDITS",
    "credits": 1000,
    "message": "Enjoy!",
    "from": "@sender_username"
  }
}

Response (Plan Coupon)

{
  "success": true,
  "data": {
    "type": "PLAN",
    "planTier": "PREMIUM",
    "credits": 15000,
    "duration": 20,
    "expiresAt": "2026-01-21T00:00:00.000Z",
    "message": "Enjoy your premium plan!",
    "from": "@sender_username"
  }
}

List Your Coupons

Endpoint

GET /v1/coupons/list

Query Parameters

Parameter	Type	Description
`status`	string	Filter: ACTIVE, REDEEMED, EXPIRED, CANCELLED
`type`	string	Filter: CREDITS, PLAN

Response

{
  "success": true,
  "data": [
    {
      "code": "GIFT-A1B2C3D4",
      "type": "CREDITS",
      "credits": 1000,
      "status": "ACTIVE",
      "message": "Enjoy!",
      "expiresAt": "2026-01-31T00:00:00.000Z",
      "redeemedAt": null,
      "redeemedBy": null,
      "createdAt": "2026-01-01T00:00:00.000Z"
    }
  ]
}

Validate a Coupon

Check if a coupon is valid before redeeming:

GET /v1/coupons/validate/:code

This is a public endpoint (no API key required).

Cancel a Coupon

Cancel an unredeemed coupon and get your credits back:

DELETE /v1/coupons/:code

{
  "success": true,
  "data": {
    "code": "GIFT-A1B2C3D4",
    "refundedCredits": 1000
  }
}

List Redeemed Coupons

GET /v1/coupons/redeemed

Get Coupon Details

GET /v1/coupons/details/:code

Gift a Plan

Create a crypto payment to gift a subscription plan. A PLAN-XXXXXXXX coupon code is reserved immediately and becomes active after payment is confirmed.

POST /v1/coupons/gift-plan

Check Gift Plan Status

GET /v1/coupons/gift-status/:trackId

Coupon Statuses

Status	Description
ACTIVE	Available for redemption
REDEEMED	Already claimed
EXPIRED	Past expiration date
CANCELLED	Cancelled by creator

Coupons

On this page