Purchase Flow

Purchase Flow

This page explains what happens from the moment a user interacts with a store panel to when they receive their reward.

1. User Selects a Product

A panel is deployed to a channel via /store panel. The user selects a product from the dropdown or clicks a button.

2. Eligibility Check

Before a checkout session is created, the plugin checks whether the user is eligible to purchase:

• If the product has a role reward and the user already has that role → purchase is blocked.
• If max_purchases is set and the user has already reached that limit → purchase is blocked.

3. Payment Method Selection (Multi-Provider)

• If the product has multiple providers defined in providers: ["stripe", "paypal", "crypto"], an interactive private card is sent to the user to choose their payment method:

  [ Stripe ] [ PayPal ] [ Crypto ]

• If the product only has a single provider defined in provider: "stripe", it skips this step and opens checkout directly.

4. Checkout Session

Based on the selected provider, the plugin creates a hosted checkout session and sends a private (ephemeral) card to the user with a link to complete payment.

5. Payment Confirmation

Once the user completes payment, the provider fires a webhook to the Store plugin. The bot then:

• Updates the user's checkout card to show Paid.
• Delivers all configured rewards (roles, webhooks).
• Sends a DM receipt to the buyer.
• Posts a purchase log in the configured store-logs channel.
• Records the transaction in the database.

Webhook Endpoints

Each provider has its own dedicated webhook route:

Reward Errors

If a reward fails to deliver (e.g. an unknown role ID), the purchase is still recorded as completed with errors and a 200 OK is returned to the payment provider. The error detail is included in the store-logs message so you can investigate without the payment being retried.

Commands

The /store command is restricted to admins (permissions.store_command = "admin").

/store panel <panel> <channel>

Deploys a store panel to the specified channel. Only visible to the command executor.

/store lookup [user] [transactionid] [email] [date]

Queries completed purchase transactions in the database.