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

# Discord Roles

> Grant Discord server roles automatically when customers buy, using the Komerza bot or your own Discord application

Connect a Discord server to your store and Komerza grants roles automatically when an order is delivered. Customers link their Discord account at checkout, get added to your server, and receive the role attached to the variant they bought. Refunds and chargebacks can take the role back.

You can use the **Komerza bot** (one click, nothing to configure) or your **own Discord application** (your branding, your bot, full control). This guide covers both, with the custom app in full.

Discord is managed in the dashboard under **Discord**.

## Komerza bot vs custom application

|                                | Komerza bot                   | Custom application                                      |
| ------------------------------ | ----------------------------- | ------------------------------------------------------- |
| Setup                          | One click, authorize and done | Create a Discord app, invite the bot, paste four values |
| Bot identity in your server    | Komerza's bot                 | Yours: your name, avatar, branding                      |
| What customers see at checkout | Authorizing "Komerza"         | Authorizing your application                            |
| Redirect URL registration      | Handled for you               | **You must add it yourself - see below**                |

Use a custom app if you want the bot in your server to carry your own branding, or you already run a bot and want one application for everything.

## Setting up a custom Discord application

<Steps>
  <Step title="Create the application">
    1. Go to the [Discord Developer Portal](https://discord.com/developers/applications) and click **New Application**
    2. Give it a name - this is what customers see on the authorization screen - and create it
    3. Open the **OAuth2** tab and copy the **Client ID** and **Client Secret**
  </Step>

  <Step title="Add the redirect URL to your application">
    Still on the **OAuth2** tab, under **Redirects**, add this URL exactly, with no trailing slash:

    ```
    https://checkout.komerza.com/callback/discord
    ```

    <Warning>
      This is the step people miss. Customer account linking runs through
      Komerza's checkout using **your** application's client ID, so Discord
      rejects the login with an invalid redirect URI error unless this exact URL
      is registered on your app. Nothing in the setup form will warn you - it
      fails later, at checkout, for your customers.
    </Warning>
  </Step>

  <Step title="Create the bot and copy its token">
    1. Open the **Bot** tab and add a bot to the application
    2. Click **Reset Token**, then copy the **Bot Token**

    Keep the token secret. Anyone holding it controls the bot.
  </Step>

  <Step title="Invite the bot to your server">
    Build an invite URL with your client ID and the two permissions Komerza needs:

    ```
    https://discord.com/oauth2/authorize?client_id=YOUR_CLIENT_ID&scope=bot&permissions=268435457
    ```

    | Permission                | Why it's needed                                      |
    | ------------------------- | ---------------------------------------------------- |
    | **Manage Roles**          | Granting and removing the roles customers buy        |
    | **Create Instant Invite** | Discord requires it to add a customer to your server |

    Open the URL, pick your server, and authorize.

    <Warning>
      **Drag the bot's role above every role it will hand out.** Discord only
      lets a bot manage roles below its own highest role, so a bot sitting at
      the bottom of the list silently fails to grant anything.
    </Warning>
  </Step>

  <Step title="Copy your server ID">
    In Discord, enable **Settings → Advanced → Developer Mode**, then right-click
    your server and choose **Copy Server ID**.
  </Step>

  <Step title="Connect it in Komerza">
    In the dashboard go to **Discord**, click **Use Custom Bot**, and fill in:

    * **Server (Guild) ID**
    * **Client ID**
    * **Client Secret**
    * **Bot Token**

    Komerza checks the token can reach your server before saving. If it can't,
    you'll see "Could not access the guild. Ensure the bot is added to the
    server and has the correct permissions." - that means the bot isn't in the
    server, or the token is wrong.
  </Step>
</Steps>

## Using the Komerza bot instead

On the **Discord** page, click the connect button and authorize the Komerza bot into your server. There is nothing to register and no credentials to paste. You can switch to a custom app later by disconnecting first.

## Settings

Three store-wide settings on the Discord page, each overridable per product.

<AccordionGroup>
  <Accordion title="Join Mode - when the customer joins and gets the role">
    * **Add and grant after payment** (default) - the customer is added to your server and given the role only once payment completes.
    * **Add on link, grant after payment** - the customer joins your server as soon as they link Discord at checkout, but the role waits for payment.

    The second is useful if you want buyers in your server early, in a
    welcome or support channel, before they have paid.
  </Accordion>

  <Accordion title="Discord Requirement - whether linking is mandatory">
    * **Required** - the customer cannot check out without linking Discord.
    * **Optional** (default) - offered, not enforced.
    * **Disabled** - not shown at checkout.

    Set **Required** only for products that are worthless without the role.
    Every extra step at checkout costs you conversions.
  </Accordion>

  <Accordion title="Revocation Behavior - what happens on refund or chargeback">
    * **Revoke and remove** (default) - the role is removed and the customer is kicked from the server.
    * **Revoke role only** - the role is removed, the customer stays in the server.
    * **Do nothing** - the customer keeps the role.
  </Accordion>
</AccordionGroup>

## Assigning roles to what you sell

Roles attach to **variants**, not products, so different tiers can grant different roles. Komerza reads the role list straight from your server, so create the roles in Discord first.

Per-product overrides let one product require Discord while the rest of your catalogue doesn't, or change the join mode for a single product. Anything left unset falls back to the store default.

## Grants

The **Grants** tab lists every role Komerza has handed out, with the customer, the role and the order behind it. You can **Revoke** a grant manually - useful when someone breaks your rules but hasn't refunded.

## Troubleshooting

| Problem                                                  | Fix                                                                                                                                    |
| -------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| Customers get an invalid redirect URI error when linking | `https://checkout.komerza.com/callback/discord` is missing from your application's **Redirects** list, or has a typo or trailing slash |
| "Could not access the guild" when connecting             | The bot isn't in the server, the bot token is wrong, or the Server ID belongs to a different server                                    |
| Roles are never granted                                  | The bot's role is below the role it's granting - move it up - or the bot is missing **Manage Roles**                                   |
| Customers aren't added to the server                     | The bot is missing **Create Instant Invite**, which Discord requires for adding members                                                |
| No roles appear in the picker                            | The roles don't exist in the server yet, or the bot cannot see them                                                                    |
| Nothing happens after a refund                           | Check **Revocation Behavior** - it may be set to Do nothing                                                                            |

## Next steps

<CardGroup cols={2}>
  <Card title="Products & Variants" icon={<span className="kicon kicon-box" />} href="/guides/products-and-variants">
    Roles are assigned per variant.
  </Card>

  <Card title="Managing Orders" icon={<span className="kicon kicon-receipt" />} href="/guides/orders">
    Refunds drive role revocation.
  </Card>

  <Card title="Notifications" icon={<span className="kicon kicon-bell" />} href="/guides/notifications">
    Discord alerts for store events are configured separately.
  </Card>

  <Card title="Selling Subscriptions" icon={<span className="kicon kicon-repeat" />} href="/guides/subscriptions">
    Expiring subscriptions can revoke access too.
  </Card>
</CardGroup>