> ## Documentation Index
> Fetch the complete documentation index at: https://docs.shoppex.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Discord roles

> Grant a server role automatically when a buyer's payment clears.

Sell access to private channels, supporter tiers, or paid communities by binding a product to
a Discord role. When the buyer pays, Shoppex grants them the role on your server through the
Discord API.

## Setup

1. Add the Shoppex bot to your Discord server. The invite link is on **Settings → Integrations
   → Discord** (`/settings/integrations/discord`). The bot requests **Manage Roles**,
   **View Channels**, **Send Messages**, and **Embed Links**. Its own role in the server
   hierarchy must sit *above* any role you intend to sell (Discord rule — bots can only manage
   roles below their own).
2. On a product, choose your product **Type** (usually `Subscription` for recurring access),
   then in the **Discord** section toggle **Assign Role** and pick the server and the role
   (loaded live from your server).
3. At checkout, buyers are prompted to authorize Discord through OAuth so Shoppex can grant
   the role to their account. Without that authorization the order can't fulfill.

## When the role is granted

The grant runs asynchronously after payment, through an outbox queue so transient Discord API
failures retry automatically. Most grants land within a few seconds.

If Discord is down or rate-limiting, Shoppex retries on a fixed schedule: **1 minute, 5
minutes, 30 minutes, 2 hours, 12 hours** — five attempts spanning roughly 14 hours. If the
role still hasn't landed after the last attempt, the grant is marked failed and the order's
fulfillment status reflects that. Re-trigger from the order page once the issue is resolved.

## Revoking

For one-time purchases, the role stays granted indefinitely. The buyer keeps it until you
remove it manually or they leave the server.

For **subscription products**, revoke behavior is per-product. By default new products have
**Remove role on cancel** enabled — the role is revoked when:

* The subscription is canceled.
* The subscription moves to a canceled state because the buyer stopped paying (two voided
  renewals trigger auto-cancel — see [Subscriptions](/merchants/products/subscriptions)).

If you turn off **Remove role on cancel**, the role stays granted regardless of subscription
status. If the same buyer holds another active subscription tied to the same role, the role
is kept either way.

## Multiple servers

Bind a product to a role on one server. If you want to grant roles across multiple servers
in the same purchase, set up additional products and either bundle them or use addons.

## Troubleshooting

If a buyer reports they didn't get their role:

1. Check the order's fulfillment status. If pending, the Discord OAuth is still missing —
   the buyer needs to complete the link from their order page.
2. Check the bot has Manage Roles permission and is above the target role in the server
   hierarchy.
3. Check the role still exists. If you deleted it, Shoppex can't grant it.
4. If fulfillment is marked failed (after the 5-attempt retry chain), re-trigger from the
   order page once Discord is back.