Essentials Shop
Essentials Shop lets you sell game servers from your own Pelican panel. Customers pick a package, pay an invoice, and the panel builds the server for them. After that the shop renews, reminds, suspends unpaid services and handles refunds, credit, coupons and gift cards. It is meant for hosting providers and communities that charge for servers.
At a glance
| Plugin ID | essentials-shop |
| Current version | 1.5.3 |
| Pelican Panel | 1.0 (tested on 1.0.0-rc.2) |
| Needs | The scheduler, the queue worker, the panel's frontend build (Node.js and Yarn), working panel mail for invoice emails, and an account with Stripe, PayPal or Mollie (or manual payment instructions) |
| Works with (optional) | Essentials Core, Essentials Support, Essentials Monitoring, Essentials API, Essentials Arranger |
| Adds | Admin area, sidebar group Essentials Shop: Overview, Packages, Orders, Invoices, Extras, Payments, Coupons, Gift cards, Customers, Shop settings. Client area: Shop, the basket, checkout and pay pages, My services, a page per service, Billing. Account menu: My services, Billing and the customer's credit. A Your details section on the profile page. A public page at /shop |
| Permissions | Admin -> Roles, section Essentials Shop: View, Update, and a pair per part (see below) |
The role editor shows View (look at everything), Update (change everything, including the Parts switches) and then one pair per part: Shop / View Shop, Packages / View Packages, Orders / View Orders, Invoices / View Invoices, Payments / View Payments, Coupons / View Coupons, Customers / View Customers, Credit / View Credit, Upgrades / View Upgrades, Addons / View Addons, Takings / View Takings (the Overview page), Terminate / View Terminate and Gift Cards / View Gift Cards. The plain permission lets someone manage that part; the View one only lets them look.
A few combinations are worth knowing:
- The payment provider keys on Shop settings need Payments to see and edit, and Shop (or Update) to save the page.
- Refunds and giving credit need Credit.
- Terminate (deleting a customer's server now) is separate from Orders on purpose. Suspending, cancelling and moving a due date only need Orders.
Before you install
Shop-specific:
- The legacy all-in-one "Essentials" plugin (
essentials) is not running on this panel, or you have decided to move from it to the modules (see "Things to watch out for"). - Your panel can be reached from the internet at its normal address. Payment providers report payments to it.
- You have, or will create, an account with Stripe, PayPal or Mollie. Start with their test or sandbox mode.
- Pelican can send email. Check it under Admin -> Settings -> Mail and send the test mail there.
- You have at least one egg and one node with free allocations (ports) for the servers you want to sell.
- You have a recent backup of the panel database.
General:
-
Pelican Panel 1.0 (the plugin declares
^1.0.0-beta35and is tested on 1.0.0-rc.2). Pelican 1.0.0-rc.2 itself needs PHP 8.4 or 8.5. -
Node.js and Yarn are installed on the panel server. The shop ships a stylesheet that Pelican compiles into the panel's frontend build when the plugin is installed.
-
The scheduler (a cron job that runs Pelican's timed tasks every minute) is set up for the web user. Add it with
sudo crontab -e -u www-data:* * * * * php /var/www/pelican/artisan schedule:run >> /dev/null 2>&1The commands in this document assume Pelican lives in
/var/www/pelicanand the web server user iswww-data(Debian/Ubuntu). On another setup, adapt the path and the user (for examplenginxon some systems). -
The queue worker (Pelican's background worker, usually the systemd service
pelican-queuerunningphp artisan queue:work) is running. Check it withsystemctl status pelican-queue. SetRestart=alwayson the service, and add a drop-in withStartLimitIntervalSec=0under[Unit]so systemd never gives up restarting it after repeated crashes. If it does give up,systemctl reset-failed pelican-queue && systemctl start pelican-queuebrings it back. -
Essentials Core is optional. With Core installed the shop appears in Core's module list on the Essentials page, with its health notes and its Parts window. Without Core the shop works on its own and every part stays switched on.
Installing
Download the plugin from the Essentials website, https://essentialsplugins.nl: sign in, open the catalogue, pick Essentials Shop and a version, and download the zip. x.y.z is stable, x.y.z-beta is a test release and x.y.z-dev is a development build. Use stable on a live panel.
Pick one of these routes:
-
From the admin area (recommended). Go to Admin -> Plugins -> Import from File and choose the zip. The plugin appears in the list; press Install. Pelican says "Plugin install started in the background". Refresh after a minute until the plugin shows Enabled. (Pelican also has Import from URL.)
-
From the Essentials website. Connect your panel on the website with a Pelican application key. Make the key on the panel under Admin -> API keys, with read and write on Plugins; it starts with
papp_. Then press Install on the plugin's page on the website. -
With Essentials Auto Updater. Its Plugin updates page offers Essentials modules that are not installed yet.
-
Command line (advanced). Unzip so the folder is exactly
/var/www/pelican/plugins/essentials-shop, then:sudo chown -R www-data:www-data /var/www/pelican/plugins/essentials-shop cd /var/www/pelican sudo -u www-data php artisan p:plugin:install essentials-shop sudo -u www-data php artisan p:plugin:listThe list must say enabled. Unzipping over an existing plugin folder resets it to "not installed", so always run the install command again after unzipping.
What the install does:
- It creates the shop's 13 database tables if they are missing and adds any missing columns to existing ones. It does not use migrations, and a table that already exists is left as it is. A panel coming from the all-in-one plugin keeps all its orders, invoices and payments.
- It encrypts payment keys that an older version saved in plain text.
- It clears Pelican's route and view caches and asks the queue worker to restart.
After installing, every time:
- If a new page answers 404 or an old version still shows, reload PHP-FPM (
sudo systemctl reload php8.4-fpm, use your PHP version) and restart the worker (sudo systemctl restart pelican-queue). - If styling or buttons are missing, rebuild the frontend:
cd /var/www/pelican && sudo -u www-data yarn build. With Essentials Core, the Panel health section on the Essentials page reports missing built assets. - Run artisan, yarn and file commands as the web user (
sudo -u www-data ...), never as root. Files created by root cause errors and failed updates later. - Give your admin roles the shop's permissions under Admin -> Roles, section Essentials Shop. Root Admins have everything already.
Moving from the all-in-one plugin: until you press Save on Shop settings, the shop reads the values the all-in-one plugin wrote to .env (the LEGEND_THEME_SHOP_* lines), including the payment keys. A panel that was taking payments keeps taking them. After the first save, the shop's own settings file is used. A secret key field you leave empty on that save keeps coming from .env until you type the key in, so do not remove those lines before every key has been entered on Shop settings. Role permissions granted under the all-in-one plugin are copied over once.
First-time setup
Work through these steps before you let customers in.
- Close the shop while you set it up. Open Admin -> Essentials Shop -> Shop settings. In Maintenance, switch on Shop closed for maintenance and save. Customers see a notice instead of the store. You, anyone else who may manage the shop and the roles you pick under Testers still see it as normal.
- Money. Pick the Currency (EUR, USD, GBP, CHF, SEK, DKK, NOK, PLN, CZK, AUD, CAD or NZD). Set Tax as a percentage (zero for none) and Invoice numbers start with (the default
INV-givesINV-000001). - Who is selling. Fill in Trading name, Billing email, Address, VAT number, Chamber of Commerce number and Country code (two letters, such as NL). These are printed on every invoice. The country code also decides whether EU business customers are reverse-charged. Payment term, in days is how long a new invoice has to be paid; zero means due on the day it is written.
- Renewals. Invoice this many days before the period ends (default 7) sets when the next invoice is written. Suspend this many days after an invoice is due (default 7) is the grace period before an unpaid server is suspended. Every new invoice reaches the customer as a panel notification and an email, and an unpaid renewal invoice gets one reminder (notification and email) once it is past its due date, before the server is suspended.
- Tax display. Under Where the shop sits, decide on Prices already include tax (off by default: tax is added at checkout) and Check VAT numbers against the EU register (on by default).
- Payment providers. Set up at least one in test mode, then press Test the payment keys at the top of the page. See "Payment providers" below.
- Payment without a provider. If you take bank transfers, write your instructions in How to pay under Paying without a provider. They are shown on unpaid invoices while no provider is switched on. You then mark invoices paid by hand on Invoices with Mark paid.
- Save. The Save button is below the form.
- Packages. Open Packages and press New package. Fill in:
- The package: Name, Description, Order and For sale.
- The server it becomes: Egg, Docker image, Startup command, Variables, Nodes (tried in order until one has a free address; nothing ticked means any node), optionally Ports from / to and Address shown to customers. Can be changed to lists the packages a customer may move to later.
- Limits: memory, disk, CPU, swap and the rest, the same as Pelican's own server form.
- Price and stock: Price, Setup fee, Billed (one-off, monthly, every three months or yearly), Stock (empty is unlimited), Minimum term.
- Optionally Picture (PNG, JPEG, WebP or GIF; SVG is refused because the file is served from the panel's own address), Ask the customer (egg variables to ask at checkout, or a zip file to upload) and an offer. A package without an egg is never shown in the shop.
- Optional extras. Extras (add-ons sold with a package), Coupons, Gift cards, and the customer switches under Where the shop sits: Open the shop first, Let customers end their own service, Let customers join the waiting list and Let customers buy several things at once. With the Credit and refunds part on (the default) and a payment provider switched on, customers can also top up their balance with Add credit on their Billing page; credit comes off their next invoices by itself.
- Test a whole purchase. Use a test account that has a role listed under Testers. Buy a package, pay with a test card or sandbox account, and check that the invoice turns Paid, the server is built, the customer gets the "Your server is ready" notification and the invoice email arrives. An order placed during maintenance is a real order, so clean up test orders and servers afterwards.
- Go live. Replace the test keys with live keys (or switch PayPal's Sandbox off and use live credentials), press Test the payment keys again, and make one small real payment. You can refund it from Invoices with Refund -> Back to how they paid.
- Open the shop. Switch Shop closed for maintenance off and save, or press Open the shop on the Packages page.
Do not take real money before you have tested with sandbox or test keys, and make sure you have working database backups first.
Payment providers
All three are set on Shop settings. Each section shows the exact webhook address for your panel. The secret fields (Mollie's API key, Stripe's Secret key and Signing secret, PayPal's Secret) are stored encrypted and never shown again after saving; leave one empty to keep the saved value, or type a new one to replace it. A provider that is switched on but missing keys is left out of checkout.
Stripe (cards on a page Stripe hosts; card numbers never reach the panel)
- In the Stripe dashboard, go to Developers -> API keys and copy the secret key (it starts with
sk_). Paste it into Secret key. - Under Developers -> Webhooks, add the address shown on the page (
https://<your panel>/essentials/pay/stripe/webhook) as an endpoint for the eventcheckout.session.completed. - Copy the signing secret Stripe shows for that endpoint (it starts with
whsec_) into Signing secret. Without it, Stripe's messages cannot be verified and are ignored. - Switch on Offer Stripe and save.
Test or live is decided by the key itself; there is no separate switch.
PayPal
- On developer.paypal.com, open Apps & Credentials. Use the Sandbox tab for testing and the live tab for real payments, and set the Sandbox switch on Shop settings to match.
- Create or open an app. Copy the Client ID with the copy button (the dashboard shortens the text it shows) and the Secret (behind Show).
- On that app, add a webhook for the address shown on the page (
https://<your panel>/essentials/pay/paypal/webhook) and the eventPAYMENT.CAPTURE.COMPLETED. Paste the ID PayPal gives the webhook (not the address) into Webhook ID. - Switch on Offer PayPal and save.
With PayPal the money is taken when the customer comes back to the panel after approving. A customer who closes the tab leaves an unpaid invoice, not a lost payment.
Mollie (iDEAL, Bancontact, cards and more)
- In the Mollie dashboard, open the Developers section and copy an API key. A test key and a live key belong to different modes; the key says which.
- Paste it into API key, switch on Offer Mollie and save.
There is no webhook to add in Mollie's dashboard: each payment tells Mollie where to report (https://<your panel>/essentials/pay/mollie/webhook). Your panel must be reachable from the internet at that address.
Test the payment keys asks each switched-on provider whether it accepts the keys. It creates nothing and can be pressed as often as needed. For PayPal it also points out a shortened client ID, a client ID that equals the secret, or a sandbox/live mix-up.
Things to watch out for
Shop-specific:
- Never run the shop next to the legacy all-in-one plugin. "Essentials" (plugin id
essentials) contains the older shop and uses the same tables. Installing a module switches the all-in-one off; installing the all-in-one on a panel with modules can switch modules off. Uninstalling the all-in-one deletes database tables the modules share (shop, tickets, API keys), so all orders, invoices, payments and credit are lost. Pick one: the all-in-one, or the modules. Back up the database before touching either. - Some actions delete servers. A cancelled service runs until the end of the period the customer has paid for, and then the daily pass deletes the server with its files, databases and backups. For a monthly package with a Minimum term that is the end of the current month, not the end of the term (from 1.5.3 on): the shop does not bill the rest of a term after a cancellation, so enforce a term in your terms of service if you need one. (A service with no end date to run to, such as a one-off, stops billing at once and keeps its server until you delete it in Pelican.) Stop and delete on Orders deletes it at once. Neither can be undone. Customers can only do this themselves if Let customers end their own service is on (off by default). Give the Terminate permission only to people who should be able to delete customer servers.
- Suspension deletes nothing. An unpaid renewal invoice past the grace period suspends the server with Pelican's own suspension. Paying the invoice, or Mark paid, lifts it again. The shop never deletes a suspended server by itself.
- A shared invoice is one debt. With Let customers buy several things at once on, services bought together are billed together, and one unpaid bill suspends every service on it.
- Price changes do not reach existing customers. An order keeps the price it was bought at. Changing a package's price only affects new orders. Changing the currency does not convert any prices; the numbers stay the same in the new currency.
- Switching the Shop part off is not the same as maintenance. Turning the Shop part off (in Core's Parts window) closes buying and paying for customers, stops the daily renewals pass, takes the payment provider addresses away and removes the Shop settings page. To pause sales and keep billing running, use maintenance mode instead.
- Orders placed during maintenance are real. Testers create real invoices and, once paid, real servers.
- Payment keys are encrypted with the panel's app key (
APP_KEYin.env). If that key changes, or you copy the settings file to a panel with a different key, the stored payment keys can no longer be read and checkout stops offering those providers. Enter the keys again. Back up.envtogether with the settings file. - Switching a provider or the shop off. From 1.5.1 on, a payment that was already in progress is still recorded when the provider confirms it, even if you switched that provider or the whole shop off in the meantime (1.5.0 answered such confirmations with 404). Customers cannot start new payments through a provider that is off, and Re-check answers "That provider is switched off" until you switch it back on.
- Payments need your panel to be reachable. Stripe, PayPal and Mollie report payments to the webhook addresses. If they cannot reach the panel, a payment is still confirmed when the customer returns to the panel, but a customer who closes the tab leaves an invoice that stays unpaid until you press Re-check on Payments.
- Short payments are not accepted. If a provider reports less than the invoice asks, or another currency, the invoice stays unpaid and staff get a notification. Refund the payment or settle the rest by hand.
- Ports can run out. A package with a port range only uses ports in that range. When the range is full, a paid order cannot be built. Saving a range creates the missing allocations on the chosen nodes (ports 1024 to 65535, at most 1000 at a time) and never removes any.
- VAT. EU business customers with a valid VAT number from another EU country are reverse-charged only when your Country code is filled in. With Check VAT numbers against the EU register on, the number is checked with the EU's VIES service; when VIES cannot be reached, tax is charged. Check your tax settings with your accountant.
- Deleting a Pelican user keeps their orders and invoices (shown as "Account deleted") but removes their credit balance and their billing details.
- Exports hold personal data. The Export CSV files on Orders, Invoices and Customers contain customer details. Store them where only staff can read them.
- Invoices are web pages, not PDF files. An invoice opens in the browser (the email links to it), and Print or save as PDF opens the browser's print dialog. The shop does not create or attach PDF files itself.
- Read-only gift card access shows part of a code. Somebody with only View Gift Cards sees the last four characters of a code that has not been used, and cannot copy or search codes (from 1.5.3 on). Only Gift Cards shows whole codes.
- Wrong coupon codes are limited. After 30 wrong codes in ten minutes, every code is refused for a while, the right one included (from 1.5.3 on).
- Gift cards need Credit. The Gift cards part only works while Credit and refunds is switched on. You can make codes while it is off (the Gift cards page warns about it), but customers get nowhere to redeem them until it is on.
- Where customers redeem a gift card. While at least one code can be redeemed, customers see Redeem a gift card in their account menu; it opens the window on their Billing page, where the button is as well. A gift card code typed into the coupon box at the basket or checkout says it is a gift card and links there (from 1.5.2 on).
- Refunds to the provider can fail (old payments, methods that cannot be reversed). Refunding to the customer's account as credit cannot fail.
- The Payments part is only the admin side. Switching it off hides the Payments page, the provider sections on Shop settings and Test the payment keys; it does not stop customers paying.
General:
- Run every artisan, yarn and file command as the web user, never as root.
- The
storagefolder must be writable by the web user. If saving fails with "Could not save the shop settings. Check that storage/app belongs to the user the panel runs as.", fix the ownership. - Without the scheduler, nothing on the timetable happens: no renewal invoices, reminders, suspensions or service endings, and no worker check.
Things to keep an eye on
- Core's module list. On the Essentials page, Essentials Shop shows notes when something needs you: tables missing, the shop closed for maintenance, a provider switched on without keys, no way to pay at all, tax charged without a shop country, or no package on sale.
- Overview. The top line says when paid orders have no server yet and when invoices are past due. The lists show what is due soon and which packages are running out.
- Staff notifications. People with View, Orders or View Orders in Essentials Shop get panel notifications when an order could not be built, a payment did not cover an invoice, money arrived for a withdrawn invoice, an extra or a package change could not be applied, a customer's upload could not be put into its server, or a server could not be deleted.
- Orders. Look for Not built yet and use the Behind on a bill filter. Build again retries a failed build.
- Invoices. Not emailed means the mail could not be sent; fix Pelican's mail settings. Use the Past due filter.
- Payments. Attempts stuck on Waiting can be asked again with Re-check.
- Ports. The Ports each package lands on section on Shop settings marks a range nearly out at five free ports or fewer. With Essentials Monitoring installed, its watchdog can warn about this too.
- Scheduler and worker. The renewals pass runs once a day; the worker check and the waiting list run every five minutes. Check
systemctl status pelican-queuenow and then. When the shop notices that no worker answers, it builds servers and runs renewals itself. That check only runs every few minutes, so work queued just after a worker stops waits until it is back. Keep the worker running. - Provider dashboards. Watch for failed webhook deliveries in Stripe and PayPal, and update the keys on Shop settings whenever you rotate them.
- Customer uploads. Zip files customers upload at checkout wait in
storage/app/private/essentials/uploadsuntil they are put into the server. Files that could not be delivered stay there. - Logs. Errors go to
storage/logs/laravel-YYYY-MM-DD.log(orlaravel.log). Pelican's log viewer reads the whole file, so very large logs (around 100 MB) make it fail; Essentials Core warns above 50 MB.
Updating
- Make a database backup. The shop keeps orders, invoices and payments in tables.
- Download the new version and import it the same way you installed it (Pelican shows Update on the plugin when an update is known), or let Essentials Auto Updater do it.
- The shop switches itself back on after an update through the admin area. Settings and data are kept. New tables and columns are added on install and again on the first request after the version changes; orders, invoices and payments are never touched.
- If a page still shows the old version or answers 404, reload PHP-FPM and restart the queue worker (see "Installing").
Removing it
Before you remove the shop, decide what happens to the servers it sold. Uninstalling stops all billing: no more invoices, reminders, suspensions or automatic endings.
Uninstalling under Admin -> Plugins:
- Removes the shop's pages, the public page, the payment addresses and its timed tasks.
- Does not delete any table. The shop has no migrations to roll back, so all 13 tables and their data stay in the database.
- Does not touch servers. Servers the shop built stay as normal Pelican servers, including any it suspended. Lift those suspensions in Pelican's own server admin if needed.
- Leaves the files listed below.
Afterwards, remove the webhook endpoints in your Stripe and PayPal dashboards; they will only get errors from now on.
To remove the data by hand (this cannot be undone; back up first and be sure the legacy all-in-one plugin is not using these tables):
-
Tables, in an order the database accepts (tables that point at others first):
DROP TABLE IF EXISTS essentials_invoice_orders; DROP TABLE IF EXISTS essentials_customers; DROP TABLE IF EXISTS essentials_credit; DROP TABLE IF EXISTS essentials_upgrades; DROP TABLE IF EXISTS essentials_order_addons; DROP TABLE IF EXISTS essentials_addons; DROP TABLE IF EXISTS essentials_gift_cards; DROP TABLE IF EXISTS essentials_waitlist; DROP TABLE IF EXISTS essentials_payments; DROP TABLE IF EXISTS essentials_invoices; DROP TABLE IF EXISTS essentials_orders; DROP TABLE IF EXISTS essentials_coupons; DROP TABLE IF EXISTS essentials_packages;If Essentials Support is installed, its
essentials_ticketstable refers toessentials_orders, and the database refuses to dropessentials_orderswhile that link exists. -
Files:
storage/app/private/essentials/shop/(settings, including the encrypted payment keys, and two small marker files)storage/app/private/essentials/uploads/(customer uploads not yet delivered)- Package pictures you uploaded, under
storage/app/public/theme/(Essentials Appearance keeps its uploads in the same folder, so delete only the package pictures if you use it) - The plugin folder
/var/www/pelican/plugins/essentials-shop, if Pelican left it
For backups while the shop runs, include the database, storage/app/private/essentials, storage/app/public/theme and the panel's .env (for the app key).
Troubleshooting
| Problem | What to do |
|---|---|
| The plugin shows an error: "Update legacy Essentials to a version supporting standalone Shop, or disable legacy Essentials before enabling this plugin." | The legacy all-in-one plugin is active and too old. Update it or disable it. Do not uninstall it without a backup: that deletes the shared tables. |
| Core says "The shop is switched on, but its tables are missing." | Install the plugin again (Install in Admin -> Plugins, or sudo -u www-data php artisan p:plugin:install essentials-shop) and check storage/logs for the database error. |
| A new shop page answers 404, or an old version still shows. | Reload PHP-FPM and restart the queue worker. |
| Store cards and invoices look unstyled. | Run cd /var/www/pelican && sudo -u www-data yarn build. |
| Customers get "The payment could not be opened". | Press Test the payment keys on Shop settings and fix what it reports. |
| PayPal refuses the keys. | Make sure the Sandbox switch matches the dashboard tab the keys came from, copy the client ID with the copy button, and reveal the real secret behind Show. |
| A customer paid but the invoice stays Unpaid. | Open Payments and press Re-check. Then check the webhook: Stripe needs the Signing secret, PayPal the Webhook ID, and all three need the panel to be reachable from the internet. If the provider reported less than the invoice asks, refund or settle by hand. |
| A paid order has no server ("Not built yet"). | Read the order's Details for the reason. "No node in this package has a free allocation" means you must add allocations or widen the port range. Then press Build again. Check that the queue worker runs. |
| Renewal invoices are not written and unpaid servers are not suspended. | The scheduler is missing or not running as the web user. Fix the cron entry. Run renewals now on Orders queues one pass by hand (the queue worker must be running). |
| Invoices show Not emailed. | Fix the mail settings under Admin -> Settings -> Mail and send the test mail there. Customers can still read invoices on their Billing page. |
| Payment keys suddenly read as missing, or Core says a provider is "switched on, but its keys are missing". | The keys were never saved, or the panel's app key changed. Enter the keys again and save. |
| Customers see "The shop is closed for maintenance". | Maintenance is on, or Open again at has not passed yet. Switch it off on Shop settings or press Open the shop on Packages. |
| A customer's upload did not reach the server. | The file is still in storage/app/private/essentials/uploads; the reason is in storage/logs. Put it into the server by hand. |
| Saving Shop settings fails. | Make sure storage belongs to the web user: sudo chown -R www-data:www-data /var/www/pelican/storage. |
| Customers say there is nowhere to use a gift card | Check that Shop, Gift cards and Credit and refunds are all switched on, and that the code is not used up or past its end date. Customers redeem it under Redeem a gift card in the account menu, or on Billing (from 1.5.2 on the account menu row exists; before, only the button on Billing). |
Essentials is a community project by Legend Development. Not affiliated with or endorsed by the Pelican team.