Skip to main content
Premium is the part of Rankly that lets users pay for bot or server upgrades with the platform’s credit system.

​
What premium covers

  • Bot premium tiers
  • Server premium tiers
  • Weekly, monthly, and lifetime durations
  • Gifted purchases
  • Order history and transaction tracking
  • Premium lifecycle webhooks for purchases, renewals, expirations, and revocations

​
How a purchase works

1

Choose a target

Premium can be attached to a bot or a server, depending on what the product offers.
2

Choose a tier

Tiers define the price, duration, and plan type that will be charged.
3

Confirm the credit balance

Rankly checks the purchaser’s available credits before the order is created.
4

Store the resulting state

Keep your own internal record of the plan, the expiry, and whether the purchase was gifted.

​
Premium webhooks

For bot premium plans, Rankly sends signed webhook events to your configured premium webhook URL.

​
Headers

  • X-Webhook-Signature: HMAC SHA-256 signature of the exact JSON body
  • Content-Type: application/json

​
Signature verification (Node.js)

import crypto from 'crypto';

function verifyRanklySignature(rawBody, signatureHeader, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(rawBody)
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(expected, 'utf8'),
    Buffer.from(signatureHeader || '', 'utf8')
  );
}
Use the raw request body for verification before parsing or mutating payload fields.

​
Plan types

Plan typeMeaning
WeeklyRenew or expire on a 7-day cycle.
MonthlyRenew or expire on a 30-day cycle.
LifetimeStays active until it is manually revoked.

​
Event types you can receive

EventMeaningCommon reason
premium_purchaseA premium order was created successfully.New checkout completed
subscription.renewedA recurring plan was renewed.Auto-renew succeeded
subscription.expiredA recurring plan was ended.Past due, invalid buyer, tier unavailable
subscription.revokedA plan was revoked and should be disabled immediately.Chargeback/dispute

​
Webhook payload examples

​
premium_purchase

{
  "event": "premium_purchase",
  "purchaseId": "682f4d8e8c4a93b75ad69f90",
  "orderId": "682f4d8e8c4a93b75ad69f90",
  "timestamp": "2026-05-24T12:00:00.000Z",
  "buyer": {
    "userId": "123456789012345678",
    "username": "Skyline"
  },
  "recipient": null,
  "isGift": false,
  "giftedBy": null,
  "tier": {
    "id": "pro-monthly",
    "name": "Pro Monthly",
    "duration": "monthly",
    "planType": "user"
  },
  "serverId": null
}

​
subscription.renewed

{
  "event": "subscription.renewed",
  "orderId": "682f4d8e8c4a93b75ad69f90",
  "purchaseId": "682f4d8e8c4a93b75ad69f90",
  "timestamp": "2026-05-24T13:00:00.000Z",
  "buyer": {
    "userId": "123456789012345678",
    "username": "Skyline"
  },
  "recipient": null,
  "isGift": false,
  "vendor": {
    "type": "bot",
    "id": "987654321098765432"
  },
  "tier": {
    "id": "pro-monthly",
    "name": "Pro Monthly",
    "duration": "monthly",
    "planType": "user"
  },
  "autoRenew": true,
  "status": "active",
  "currentPeriodEnd": "2026-06-24T13:00:00.000Z"
}

​
subscription.expired

{
  "event": "subscription.expired",
  "orderId": "682f4d8e8c4a93b75ad69f90",
  "purchaseId": "682f4d8e8c4a93b75ad69f90",
  "timestamp": "2026-05-24T14:00:00.000Z",
  "buyer": {
    "userId": "123456789012345678",
    "username": "Skyline"
  },
  "recipient": null,
  "isGift": false,
  "vendor": {
    "type": "bot",
    "id": "987654321098765432"
  },
  "tier": {
    "id": "pro-monthly",
    "name": "Pro Monthly",
    "duration": "monthly",
    "planType": "user"
  },
  "autoRenew": true,
  "status": "past_due",
  "currentPeriodEnd": "2026-05-24T14:00:00.000Z",
  "reason": "past_due"
}

​
subscription.revoked

{
  "event": "subscription.revoked",
  "orderId": "682f4d8e8c4a93b75ad69f90",
  "purchaseId": "682f4d8e8c4a93b75ad69f90",
  "timestamp": "2026-05-24T15:00:00.000Z",
  "buyer": {
    "userId": "123456789012345678",
    "username": "Skyline"
  },
  "recipient": null,
  "isGift": false,
  "vendor": {
    "type": "bot",
    "id": "987654321098765432"
  },
  "tier": {
    "id": "pro-monthly",
    "name": "Pro Monthly",
    "duration": "monthly",
    "planType": "user"
  },
  "autoRenew": true,
  "status": "revoked",
  "currentPeriodEnd": "2026-06-24T13:00:00.000Z",
  "reason": "chargeback_dispute"
}

​
What could happen in production

  • A user buys premium now: you get premium_purchase, then grant features immediately.
  • The subscription renews a month later: you get subscription.renewed, and just extend access.
  • Auto-renew fails: you get subscription.expired, and you should remove paid features.
  • A chargeback happens after purchase: you get subscription.revoked, and you should disable access right away.
  • A gift purchase is made: isGift is true and recipient is populated, so entitlement should be applied to the recipient.

​
What to expect in your app

  • A premium purchase becomes an order in Rankly’s billing flow.
  • The purchaser and recipient can be different users when the plan is gifted.
  • The dashboard should always show the current status, not just the original purchase date.
  • If you need to reflect the current plan in your bot, refresh your own cached state after checkout.

​
Handler checklist

  • Verify X-Webhook-Signature before processing.
  • Deduplicate by orderId plus event.
  • Make state transitions idempotent.
  • Treat subscription.revoked as highest priority for entitlement removal.
  • Return 2xx quickly, then do heavy work async.

​
Helpful implementation notes

  • Keep tier IDs stable once users rely on them.
  • Show the user what they are paying for before they confirm the purchase.
  • Make expired plans obvious in the UI.
  • Treat a billing failure as a recoverable state, not a fatal error.

Credits

See how premium purchases interact with balances.

Bot API Integration

Pull plan state into your bot commands or dashboard.