> ## 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

<Steps>
  <Step title="Add the Shoppex bot to your 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. This is a Discord rule: bots can only manage roles below their own.
  </Step>

  <Step title="Configure the product">
    On a product, choose the product **Type** (usually `Subscription` for recurring access). In the **Discord** section, toggle **Assign Role**. Then pick the server and the role, loaded live from your server.
  </Step>

  <Step title="Buyers authorize Discord at checkout">
    Buyers are prompted to authorize Discord through OAuth, so Shoppex can grant the role to their account. If the buyer skips that authorization, the order cannot fulfill.
  </Step>
</Steps>

## 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 over about 14 hours. If the role has not landed after the last attempt, the grant is marked failed, and the order's fulfillment status reflects that. Once the issue is resolved, re-trigger the grant from the order page.

## 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 invoices trigger auto-cancel — see [Subscriptions](/selling/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 more products and either bundle them or use addons.

## Troubleshooting

If a buyer reports they did not get their role:

1. Check the order's fulfillment status. If the status is pending, the Discord OAuth authorization is still missing. The buyer needs to complete the link from their order page.
2. Check that the bot has Manage Roles permission and sits above the target role in the server hierarchy.
3. Check that the role still exists. If you deleted it, Shoppex cannot grant it.
4. If fulfillment is marked failed after all five retries, wait until Discord is back, then re-trigger the grant from the order page.