Playbooks

These five playbooks walk through complete flows for a Discord supporter tier, a Telegram-only shop, a subscription switch, a Black Friday sale, and a platform migration.

​

Discord supporter tier

This walkthrough takes you from a Discord server with no monetization to a working paid supporter tier in about 20 minutes.

​

What you will have at the end

• A Discord role that gets granted automatically when someone subscribes on your shop.
• The role is revoked when the subscription is canceled or fails, as long as “Remove role on cancel” stays on. This setting is on by default.
• A customer dashboard your buyers use to manage their subscription themselves.

​

Prerequisites

• A Discord server you own (you need Manage Server permission).
• A Shoppex shop with at least one payment gateway connected. If you do not have one, do Quickstart first.

​

Step 1 — Connect Discord and invite the bot

In your Shoppex dashboard, open Settings → Integrations → Discord.

1. Click Connect Discord. This is the OAuth step that links your Discord identity to your Shoppex account.
2. Pick the target server from the dropdown that appears.
3. Click Invite Bot. Discord opens its OAuth approval flow asking you to authorize the Shoppex bot on the server you picked.
4. The bot requests Manage Roles, View Channels, Send Messages, and Embed Links. Accept.
5. Discord redirects you back to Shoppex with the bot connected.

In your Discord server settings, you will now see the Shoppex bot listed as a member. Important: its 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. If needed, drag the Shoppex role up in Server Settings → Roles.

​

Step 2 — Create the supporter role

In Discord → Server Settings → Roles → Create Role. Give it a name like Supporter, pick a color, set any permissions for private channels you want this role to see. You can now connect this role to a Shoppex product.

​

Step 3 — Create the subscription product

Back in Shoppex → Products → New product.

• Type: Subscription (this is the product’s Type field, not the Discord role. The Discord role comes next.)
• Title: “Supporter — Monthly” (or whatever fits).
• Price: Set monthly amount and billing interval.

Then scroll to the product’s Discord section and:

• Toggle Assign Role on.
• Pick the server.
• Pick the Supporter role (loaded live from your server).
• Leave Remove role on cancel on (the default) so the role gets revoked when the subscription ends.

Save the product. It is now live on yourshop.shoppex.io.

​

Step 4 — Test the flow yourself

Open your shop in an incognito window. Buy the product with one of your own gateways (or use a Stripe test key if you connected one). You will see:

1. Checkout asks you to link your Discord account.
2. You authorize through Discord OAuth.
3. You pay.
4. Within a few seconds, the Supporter role appears on your Discord account.

If anything stalls, the order page in your dashboard tells you exactly which step is pending.

​

Step 5 — Announce it

Share the product link in your server (or anywhere). Buyers click → checkout → done.

​

What happens when someone subscribes

Each month:

• The subscription auto-renews against the gateway the buyer used at signup.
• If renewal succeeds, the role stays. Neither you nor the buyer needs to do anything.
• If renewal fails, Shoppex enters a 7-day grace period (configurable in shop settings). The role stays. The buyer is asked to update payment.
• Once the subscription has two voided invoices total (cumulative across its lifetime, not only consecutive), Shoppex auto-cancels it. The role is revoked at cancel time.

Buyers can cancel anytime from their customer dashboard. Cancellation behavior depends on the gateway: see Subscriptions for the specifics. Stripe and crypto cancel at the end of the billing period. PayPal cancels immediately.

​

Common questions

“Can I have multiple supporter tiers?” Yes. Create a separate product per tier (Bronze / Silver / Gold), bound to different roles. A buyer can hold several at once. “Can I grant roles across multiple servers?” Not from one product. Assign Role binds to one role on one server. To cover multiple servers, create multiple products and either bundle them or use addons. “What if a buyer leaves my Discord server?” Shoppex cannot grant a role to someone who is not in the server. The order pauses in pending-fulfillment until they rejoin. After they rejoin, you can re-trigger fulfillment from the order page. “What if I delete the role?” Shoppex cannot grant a role that no longer exists. Existing holders lose it implicitly, because the role is gone, and new orders fail to fulfill. See Subscriptions for trials, plan changes, retries, and pauses on any subscription product.

​

Telegram-only shop

This playbook connects a Telegram bot for sales and, if you want, hides the web storefront so Telegram is the only sales channel.

​

What you will have at the end

• A Telegram bot connected to your Shoppex shop.
• The bot answers buyer questions and creates payment links right in the chat.
• Broadcasts and journeys to bring buyers back.
• (Optional) The web storefront at yourshop.shoppex.io disabled, so the bot is the only sales channel.

​

Prerequisites

• A Telegram bot you have created with @BotFather on Telegram. You will need its API token, the long string that BotFather sends you after /newbot.
• A Shoppex shop with at least one payment gateway connected.

​

Step 1 — Connect the bot

Open your Shoppex dashboard at Store → Telegram (/store/telegram).

1. Click Connect bot or Add bot.
2. Paste the bot token from BotFather.
3. Save.

Shoppex verifies the token, fetches the bot’s profile, and registers it against your shop. The bot is now connected and listening.

​

Step 2 — Turn on the AI sales agent

In the same Telegram page, configure the bot’s Agent. There are three modes:

• CUSTOMER_SALES — the bot talks to buyers, answers product questions, creates payment links when they want to buy.
• MERCHANT_ASSISTANT — the bot works for you only: DM it to check orders or get daily revenue. It does not talk to buyers.
• BOTH — the same bot serves buyers and you, distinguished by who is chatting.

For a sales-channel use case, pick CUSTOMER_SALES (or BOTH if you also want to use the bot yourself).

​

Step 3 — Test a purchase

DM your bot from a different Telegram account. Ask about a product, or say “I want to buy X”. The agent will:

1. Find the product in your catalog.
2. Reply with the product info and a Pay now button.
3. Tapping the button opens the Shoppex hosted checkout in Telegram’s in-app browser.
4. The buyer pays through your normal gateways.
5. Order confirmation is delivered both through email and (if the buyer linked Discord/Telegram to their customer profile) directly in the chat.

The payment itself happens on checkout.shoppex.io, not inside Telegram natively. The bot generates a Shoppex payment link and hands it over through an inline button.

​

Step 4 — Build out user management

Once buyers start interacting, the Users section of the Telegram dashboard fills up. You can:

• See who has chatted with the bot (with last-seen, total interactions).
• Toggle per-user notification settings.
• Build Segments, saved filters like “buyers in the last 30 days” or “VIPs over $500”.

​

Step 5 — Set up broadcasts and journeys

For ongoing engagement: Broadcasts are one-off announcements to a list. Draft a message, pick a segment or all users, schedule it for later, or send immediately. Statuses: DRAFT, SCHEDULED, SENDING, COMPLETED, CANCELLED, FAILED. Journeys are automated triggers. They fire when an event happens for a user. Available trigger types:

• ORDER_COMPLETED — thank-you flow after a purchase.
• ABANDONED_CART — nudge buyers who opened checkout but did not pay.
• PAYMENT_REMINDER — invoice past due reminder.
• SUBSCRIPTION_RENEWAL — renewal heads-up.
• MANUAL — fired by you or the API on demand.

Journeys can branch and wait, for example “if a buyer has not paid after 4 hours, send the discount code”.

​

Step 6 — (Optional) Disable the web storefront

If you do not want anyone visiting yourshop.shoppex.io, turn off the managed storefront from Settings → Shop. The field is managedStorefrontEnabled. Turn it off, and optionally add a redirect URL, for example to your Telegram bot’s t.me link. After that, the public storefront URL no longer serves your shop. The Telegram bot is the only entry point. Payment links and direct checkout URLs still work. They do not depend on the storefront.

​

Common questions

“Can the bot accept payment directly in Telegram (no redirect)?” Not currently. Shoppex generates a Shoppex-hosted checkout URL and the bot sends it as an inline button. The buyer taps, pays in Telegram’s in-app browser. There is no native Telegram Stars or native Telegram payments integration. “Can buyers manage their subscription from the bot?” Yes for queries through the agent (“show me my subscriptions”), but cancel and upgrade actions still go through their customer dashboard on Shoppex. “Multiple bots for the same shop?” Each shop can connect multiple bots. This is useful for testing in a separate bot before you swap the primary bot, or for running different language versions.

​

Switch to recurring

This playbook moves a product line from single-use codes, like Steam keys or activation tokens, to an auto-renewing subscription. It keeps the old product running, launches the new one, and moves customers over during the renewal cycle. This is the safest migration path.

​

Why not edit the existing product?

Technically Shoppex allows changing a product’s type (the type field is mutable on update). But changing SERIALS to SUBSCRIPTION on a live product does not carry over what you actually need. It creates no automatic Stripe plan, migrates no past buyers to the new billing terms, and handles no pending serial deliveries. The clean path is to create a new subscription product alongside the old one, then deactivate the old one once customers have moved.

​

Step 1 — Create the subscription product

Open Products → New product, the same page used in Discord supporter tier above:

• Type: Subscription
• Title: the new name (for example “Pro Access — Monthly”)
• Price: monthly amount
• Billing interval: Day / Week / Month / Year (and a count, for example interval=Month, count=1 for monthly)
• Trial period: optional, up to 60 days

In the Discord section (if applicable), bind a supporter role with Assign Role so subscribers get access automatically. See Discord supporter tier above for the full Discord setup. If your old product delivered files or serials on each purchase, set the subscription product’s delivery type to match. Subscriptions can deliver SERIALS, FILE, SERVICE, or DYNAMIC content on each renewal. Save the product. It is now live on your storefront.

​

Step 2 — Announce the change to existing buyers

Email or message your existing customer list. Be explicit:

• The old product (one-time codes) is staying available through a specific date.
• The new subscription product is now live. Mention its benefits: for example a lower monthly price, better access, or automatic renewal.
• After the cutover date, only the subscription product will be sold.

Tools available to you: the built-in email marketing (Marketing → Email), Telegram broadcasts if you have a bot, and Discord announcements.

​

Step 3 — Move the old buyers

There is no automated way to convert a buyer’s past one-time purchase into a subscription. The payment method changes from one-off to recurring, and the gateway agreement is different. The buyer must subscribe again on their own. The most reliable way to nudge them: offer a discount coupon on the first month of subscription, restricted to existing customers. Create the coupon at Discounts (/coupons):

• Type: PERCENTAGE (or FIXED)
• Value: whatever feels right (20-50% on first month is typical for migration)
• validUntil: a hard cutoff
• maxUses: total count to cap exposure

Share the code in the same announcement. See Black Friday sale below for the full set of coupon fields and limits.

​

Step 4 — Wind down the old product

When the cutover date arrives, deactivate the old product instead of deleting it. From the old product’s settings, toggle it inactive. It disappears from your storefront, but the past orders, delivered codes, and customer records all stay intact.

​

What about Discord roles already granted?

If the old product granted a Discord role, those grants stay. The buyer keeps the role until you remove it manually. Most merchants either:

• Let the old grants stand as a goodwill gesture (existing customers keep access forever).
• Set a date and bulk-revoke from the Discord side, with a clear announcement.

Subscription-bound roles are auto-revoked on cancel (when Remove role on cancel is on for the subscription product), so the role lifecycle is automatic going forward.

​

Common questions

“Will the new subscription auto-charge buyers who had recurring billing somewhere else?” No. Recurring billing is per-product per-buyer per-gateway. The new subscription is a fresh authorization. The buyer goes through checkout once to set it up. “Can I keep both running indefinitely?” Yes. Some merchants keep a one-time purchase option for buyers who prefer not to subscribe, alongside the subscription as the default. Make sure the pricing makes the subscription the clearly better deal.

​

Black Friday sale

This two-week walkthrough runs a major sale on Shoppex, built around Black Friday but equally usable for Cyber Monday, end-of-quarter sales, or a launch.

​

What you will do

• Prep your catalog (which products are on sale, by how much).
• Create coupon codes, with limits and product-targeting.
• Build the buyer list to email and Telegram-blast.
• Schedule the email campaign for the moment the sale opens.
• Track conversions live and react if something underperforms.
• Run the post-mortem.

​

Two weeks before — prep

Pick the discount strategy. Coupon types Shoppex supports:

• PERCENTAGE — N% off the order.
• FIXED — fixed-amount discount.

(There is no built-in BOGO. For buy-one-get-one, use bundle products instead.) For each coupon, configurable limits:

• maxUses — total redemptions across all buyers (cap the exposure).
• minOrderAmount — minimum order subtotal to be eligible.
• maxDiscount — cap the absolute discount (useful for percent codes on big orders).
• validFrom / validUntil — time window. Coupon code returns invalid outside these times.
• Product / variant binding — restrict to specific products. Without bindings, coupon applies to anything.

Decide your codes:

• A general code (BF25 for 25% off everything, capped at $X).
• Product-line specific codes (PRO-BF for the Pro tier only).
• VIP code with bigger discount, low max-uses, shared only with your top customers.

Create them at Discounts (/coupons). Build your email lists and segments. In Marketing → Email (/marketing/email), your list of buyers is automatically maintained. Build segments based on what you want to target:

• All past buyers.
• Buyers in the last 90 days (recent and warm).
• High-value buyers (LTV > $X).
• Trial-only buyers (never converted to paid).

Segments are saved filters. Once you build one, it stays current as new customers come in. Draft the email. Email Marketing’s template system is MJML-based. You can either:

• Use the builder to drag-and-drop the email.
• Write MJML directly if you want pixel-precise control.

Personalize the email with variables: first name, the buyer’s most-bought category, or the discount code itself. These variables come from the campaign-recipient context. Send a test to yourself before you schedule the campaign. A broken template can render differently in each mail client. Build a parallel Telegram blast (if you use Telegram). The same idea works on the Telegram side. Store → Telegram → Broadcasts → New broadcast.

• Pick the target segment.
• Compose the message (include the coupon code or a deeplink).
• Schedule for the same moment as the email.

​

Sale day — go live

Schedule everything in advance. Do not manually click “Send” at 9am. Set the schedule the night before instead. Both campaigns (emailMarketingCampaigns.scheduleAt) and Telegram broadcasts support scheduled send. You wake up to the campaigns already going out. Make sure your coupons’ validFrom matches the announcement time. If you email at 9am with a code that says “valid from 10am”, buyers will hit “invalid code” on the first 100 tries, and you will lose them. Watch the dashboard. During the sale, watch these live indicators:

• Analytics → Revenue (/analytics) — running revenue total.
• Orders page — orders coming in, filterable.
• Email campaign status — sent / delivered / opened / clicked counts, available per campaign.
• Telegram broadcasts — same kind of stats, per broadcast.

Shoppex does not have a built-in coupon analytics dashboard. To see how many sales each code drove, filter Orders by coupon code. Every order with a redeemed coupon has the code attached, so you can read the count and revenue from there. React if something underperforms. If the email got delivered but conversions are flat, consider:

• A follow-up email 12-24 hours later with a different angle (urgency, social proof).
• Lower the coupon’s minOrderAmount if you are getting “cart abandoned because code did not apply” complaints.
• Create a deeper discount code for an off-hours segment.

If conversions are too strong on a wholesale-margin product, you can mark the coupon inactive during the sale. Buyers who already redeemed it are unaffected, but the code stops working for everyone else.

​

After the sale — post-mortem

Within a few days of close:

1. Filter Orders by each coupon code. Count: total redemptions, average order value, total revenue.
2. Compare the results against the same week last month, or last year if you have the data. This shows the real lift from the sale, not only orders from your existing buyers.
3. Check Email Marketing stats: open rate, click rate, conversion rate per campaign.
4. Note which segment converted best. That is where you focus for the next campaign.

Save the coupons, but mark them inactive. Keeping the codes intact preserves your historical record, since orders that redeemed them stay linked.

​

Common pitfalls

• Forgetting maxUses on a percent code shared publicly. If someone leaks it, you end up refunding a thousand orders. Always cap maxUses.
• Email templates that break on iOS Mail. Test before scheduling. MJML compiles to cross-client HTML but you still want to eyeball it.
• Coupon stacking. Shoppex applies one coupon per cart. If buyers complain that they cannot use both codes, that is expected. Pick which coupon wins, usually the larger discount.
• Shipping a sale on a day where one gateway is down. Test Stripe, PayPal, crypto before the announcement goes out.

​

Migrate to Shoppex

This guide migrates an existing shop from Billgang, Sell.app, SellAuth, or Komerza to Shoppex, using the same flow for every platform except the export step. The export step is the only part that differs per platform. The whole migration usually takes one to two hours of active work, plus a few hours of DNS propagation in the background.

​

What you will have at the end

• All your products live on Shoppex with the same SKUs.
• Payment gateways connected to your own accounts.
• Custom domain pointing at Shoppex (optional).
• Old shop links redirecting (manual on your side).
• No data lost.

​

Step 1 — Export your data from your current platform

You are looking for: products with prices and descriptions, license keys / serial pools, and customer order history if available. Most platforms expose this under “Data Export”, “Backup”, or “Tools” in their dashboard. Exact menu paths shift over time, so check the current vendor docs if anything has moved. The data shape you need is the same regardless of platform. The dump needs one row per product, and one row per remaining serial or license key. If you have that, in CSV or JSON, you can re-import everything. You do not need to re-upload customers. Shoppex creates new customer records as buyers come in. Save the export anyway: it is your archive.

​

Step 2 — Sign up for Shoppex and pick your shop URL

At dashboard.shoppex.io, create an account. Pick a slug for your default URL (for example yourshop.shoppex.io). If you plan to use a custom domain, the slug does not matter long-term. Buyers will reach the custom domain instead.

​

Step 3 — Connect payment gateways

This is the biggest difference from your old platform: you connect your own gateway accounts, not Shoppex’s. Open Settings → Payment gateways. Set up each one you want:

• Stripe — paste publishable and secret key from your Stripe dashboard.
• PayPal SDK — paste client ID and secret from PayPal Developer Console.
• PayPal F&F — your PayPal Business email.
• Cash App — your $cashtag and Gmail forwarding.
• Crypto — your wallet addresses, or Cryptomus / Oxapay API keys.

See Payment gateways for the full per-provider walkthrough. Important: if you were using merchant-of-record on the old platform (some platforms operate as MoR by default), you will need to switch to your own gateways now. Shoppex does not operate as MoR. Funds settle directly to your own Stripe, PayPal, or wallet accounts.

​

Step 4 — Recreate your products

For each product on your old shop:

1. Products → New product in Shoppex.
2. Set the same title, description, price.
3. Pick the fulfillment mode that matches:
   • Files → File.
   • License keys / activation codes / Steam keys → Serials or Licenses (Licenses if you need HWID-locking).
   • Discord access → Subscription, and assign a Discord role from the product’s Discord section, the same role-binding steps as Discord supporter tier above.
   • Monthly billing → Subscription.
   • Custom service / boost / design → Service.
4. If it is a serials product, paste your old key pool into the Serials tab.

If you have many products, doing this by hand is tedious. The Developer API lets you script it. Write a small migration tool that reads your old export and sends one product at a time to /dev/v1/products. There is no bulk-create endpoint. Do not run too many requests at once, and respect the rate limit. The contracts are documented in API Reference → Products.

​

Step 5 — Move your custom domain

You can choose between two strategies, depending on how much downtime you can tolerate. Cleanest: dual-domain transition. Keep your old shop running on its current domain. Set up Shoppex on a new domain (for example new.yourbrand.com or yourbrand.shop). Test thoroughly. When ready, swap DNS so the main domain points at Shoppex. This means you have two shops live at the same time for a few days while you confirm Shoppex works for your buyers. You have no revenue gap during the switch. Fastest: direct swap. Update DNS on the day you are ready. Old shop goes dark when DNS propagates. For the actual DNS setup, see Custom domain.

​

Step 6 — Redirect your old product links

Shoppex URLs look different from your old platform’s. Old buyers, old social posts, and search-engine results will hit dead URLs unless you redirect. If you control the old platform’s domain, set up a redirect rule. For Cloudflare:

1. Add the old domain to Cloudflare.
2. Rules → Redirect Rules → “If URL contains /product/, then 301 to https://yourbrand.shoppex.io/product/{path}”.

For domains you cannot redirect, for example third-party platforms hosting old links, there is nothing to do. You lose those click-throughs.

​

Step 7 — Notify your customers

Send an email or Discord announcement explaining the move. Include:

• The new shop URL.
• Tell buyers that existing subscriptions on the old platform do not carry over. Stripe and PayPal do not transfer subscriptions between merchants, so buyers must re-authorize the recurring charge on Shoppex.
• A link to your support channel for questions.

The subscription point is the most painful part of any migration. Communicate this clearly.

​

Step 8 — Shut down the old shop

Monitor the new shop for a week or two. Check that there are no support tickets about missing items, that search results are updated, and that social posts point at the new shop. Then close the old account. Keep the export file permanently. It is your historical record.

​

Common pitfalls

• Subscriptions do not migrate. This is the biggest surprise for most merchants. Buyers must re-subscribe on Shoppex with their own payment method. Plan a transition window of a month where you message them, ideally with a discount code to make it easier.
• License keys you sold but never delivered, for example ones still in the old shop’s pool, go into the Shoppex Serials pool. Once sold and delivered, they stay with the buyer forever.
• Customer wallet balances on the old shop cannot transfer. If buyers had store credit on your old platform, you can manually re-credit their Shoppex wallet from the Customers page as a goodwill gesture.
• Disputes filed on old gateway accounts stay with those gateways. Watch your old Stripe / PayPal dashboards for a few months after the cut-over.