Skip to content
Recipes

Monetization

With Seyfert you can now control the latest Discord monetization features.

Use entitlements to decide who can access a premium offering, and subscriptions for billing state. This guide covers SKUs, subscriptions, premium buttons, events and commands.

Activate Monetization

First you need to activate the monetization in your bot for all this to work, learn how to do it here

SKUs and subscriptions

From Seyfert 5.2.0, client.monetization returns SKU and Subscription structures. The examples below assume an already started client.

const userId = '1003825077969764414';
const skus = await client.monetization.listSKUs();
const offering = skus.find(sku => sku.isSubscription && sku.isUserSubscription);

if (offering) {
    const subscriptions = await offering.subscriptions({ user_id: userId, limit: 50 });
    const hasAccess = await offering.hasUser(userId);
    console.log(hasAccess, subscriptions.map(subscription => subscription.currentPeriodEndAt));
}

Discord returns both the subscription offering and a subscription-group row. Use isSubscription to select the offering. Other SKU helpers include isDurable, isConsumable, isAvailable, isGuildSubscription and isUserSubscription.

fetchSKU(skuId) selects from the application's SKU list and throws UNKNOWN_SKU if no row matches. subscriptions(skuId, query) accepts pagination and a user_id; list limits must be integers from 1 to 100. Discord requires user_id for bot-authenticated subscription lists. fetchSubscription(skuId, subscriptionId) fetches one subscription, and subscription.fetch() uses its first SKU ID unless one is supplied explicitly.

Subscriptions expose isActive, isInactive, isEnding, currentPeriodStartAt, currentPeriodEndAt and canceledAtDate. Do not grant access from subscription status: payment retries and other billing transitions can leave a subscription active while access must be determined from entitlements.

sku.hasUser(userId) queries user entitlements for that SKU with exclude_ended: true. For guild-granted access, query client.applications.listEntitlements() with guild_id and the relevant sku_ids instead.

Subscription events

subscriptionCreate, subscriptionUpdate and subscriptionDelete receive Subscription structures:

events/subscriptionUpdate.ts
import { createEvent } from 'seyfert';

export default createEvent({
    data: { name: 'subscriptionUpdate' },
    run(subscription) {
        console.log(subscription.id, subscription.currentPeriodEndAt);
    },
});

Entitlements

Entitlements in Discord represent that a user or guild has access to a premium offering in your application, with this you can know if a user is subscribed to your application and give him the benefits you want.

In 5.2, entitlements provide startsAtDate, endsAtDate, isTestEntitlement, isEnded and isConsumed. client.applications.fetchEntitlement(id) and entitlement.fetch() retrieve one entitlement. Use entitlement.consume() or client.applications.consumeEntitlement(id) for a consumable one-time SKU after fulfilling its benefit.

Receiving Events

Currently there are 3 events for entitlements:

entitlementCreate(entitlement: Entitlement)

Emitted whenever an entitlement is created.

entitlementDelete(entitlement: Entitlement)

Emitted whenever an entitlement is deleted. Entitlements are not deleted when they expire. This is only triggered when Discord issues a refund or deletes the entitlement manually.

entitlementUpdate(entitlement: Entitlement)

Emitted whenever an entitlement is updated - i.e. when a user's subscription renews.

events/entitlementCreate.ts
export default createEvent({
    data: { name: 'entitlementCreate' },
    async run(entitlement, client) {
        if (!entitlement.userId) return;
        const subscribedUser = await client.users.fetch(entitlement.userId);
        client.messages.write('LOG_CHANNEL_ID', {
            content: `${subscribedUser.globalName} (${subscribedUser.id}) has been subscribed to ${entitlement.skuId}`,
        });
    },
});
events/entitlementDelete.ts
export default createEvent({
    data: { name: 'entitlementDelete' },
    run(entitlement, client) {
        client.messages.write('LOG_CHANNEL_ID', {
            content: `Refund or subscription deleted (${entitlement.skuId}) [${entitlement.type}]`,
        });
    },
});
events/entitlementUpdate.ts
export default createEvent({
    data: { name: 'entitlementUpdate' },
    run: async (entitlement, client) => {
        if (!entitlement.userId) return;
        const subscribedUser = await client.users.fetch(entitlement.userId);
        client.messages.write('LOG_CHANNEL_ID', {
            content: `Subscription (${entitlement.skuId}) renewed by ${subscribedUser.globalName}`,
        });
    },
});

Premium Button

Now you can create a Button that redirects to any item in your store, such as a subscription, consumable, etc.

This type of button does not need a CustomID or Label, but it does need a SkuID, which you can get from your store menu at https://discord.com/developers/applications/{APP_ID}/skus

import { Button } from 'seyfert';
import { ButtonStyle } from 'seyfert';

new Button()
.setSKUId('STORE_ITEM_SKU_ID')
.setStyle(ButtonStyle.Premium)

Learn more

For more information about the premium buttons visit the discord documentation here

Commands / Interactions

In each Interaction you can also get all the active entitlements, with them you can detect if the user has any subscriptions, consumables, etc.

Example:

commands/premium.ts
import { Declare, Command, type CommandContext, ActionRow, Button } from 'seyfert';
import { ButtonStyle } from 'seyfert';

@Declare({
  name: 'premium',
  description: 'Premium command',
})
export class PremiumCommand extends Command  {
  run(ctx: CommandContext) {
    const isPremium = ctx.interaction.entitlements.length;

    const row = new ActionRow()
    .setComponents([
        new Button()
        .setSKUId('STORE_ITEM_SKU_ID')
        .setStyle(ButtonStyle.Premium)
    ]);

    if (!isPremium) return ctx.editOrReply({ 
        content: 'Click to subscribe and get access to the command!',
        components: [row] 
    });

    // Premium code
  }
}