Rankly Docs

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

Choose a target

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

Choose a tier

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

Confirm the credit balance

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

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 type	Meaning
Weekly	Renew or expire on a 7-day cycle.
Monthly	Renew or expire on a 30-day cycle.
Lifetime	Stays active until it is manually revoked.

Event types you can receive

Event	Meaning	Common reason
`premium_purchase`	A premium order was created successfully.	New checkout completed
`subscription.renewed`	A recurring plan was renewed.	Auto-renew succeeded
`subscription.expired`	A recurring plan was ended.	Past due, invalid buyer, tier unavailable
`subscription.revoked`	A 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.

Integrations

Premium Plans

What premium covers

How a purchase works

Premium webhooks

Headers

Signature verification (Node.js)

Plan types

Event types you can receive

Webhook payload examples

`premium_purchase`

`subscription.renewed`

`subscription.expired`

`subscription.revoked`

What could happen in production

What to expect in your app

Handler checklist

Helpful implementation notes

Credits

Bot API Integration

​What premium covers

​How a purchase works

​Premium webhooks

​Headers

​Signature verification (Node.js)

​Plan types

​Event types you can receive

​Webhook payload examples

​premium_purchase

​subscription.renewed

​subscription.expired

​subscription.revoked

​What could happen in production

​What to expect in your app

​Handler checklist

​Helpful implementation notes

​Related docs

Credits

Bot API Integration

What premium covers

How a purchase works

Premium webhooks

Headers

Signature verification (Node.js)

Plan types

Event types you can receive

Webhook payload examples

`premium_purchase`

`subscription.renewed`

`subscription.expired`

`subscription.revoked`

What could happen in production

What to expect in your app

Handler checklist

Helpful implementation notes

Related docs