16. The e-shop

Who: admins set the shop up; editors and admins manage products and orders.

The e-shop is an add-on. It lets visitors put products in a cart and pay for them with Stripe (cards) or PayPal. You can sell physical products (you ship them) and digital ones (the buyer downloads a file). Until you switch it on, the shop does not exist: no menu items, no pages, no blocks.

What you need

• An activation code. You receive it from Mella; it may be tied to your site's address and to an end date.
• The site address filled in under Settings → General (for example https://example.com). A code that is tied to an address works only when this matches.
• A Stripe and/or PayPal business account.
• On the server, the SETTINGS_KEY setting (the same one that protects the mail password). Without it the payment keys cannot be stored. Whoever runs the server can instead put the keys in the server's environment (STRIPE_SECRET_KEY and so on, see .env.example).

Switching the shop on

1. Open Settings and the E-shop section.
2. Paste the activation code and click Activate. Below the field you see whether the code is valid and until when.
3. Tick Switch the e-shop on.
4. Choose the currency, the shipping cost for physical products and from which amount shipping is free (0 = never free). Prices always include VAT.
5. Optionally choose a terms of sale page: buyers must tick a box that links to it before they pay.
6. Optionally enter an address for new order notices (otherwise the contact address is used).
7. Click Save settings.

A Shop group (Products, Orders) now appears in the left menu, and the Shop blocks appear in the page builder.

If you remove the activation code, the shop switches itself off. Your products and orders are kept.

Setting up payments

Do this in Settings → E-shop → Payments. Keys are write-only: after saving you see only that they are stored.

Stripe

1. In the Stripe dashboard copy the secret key (sk_live_…, or sk_test_… for testing) into Stripe secret key.
2. Add a webhook in Stripe for the event checkout.session.completed. Its address is shown under the key fields, for example https://example.com/api/shop/webhook/stripe.
3. Copy the webhook's signing secret (whsec_…) into Stripe webhook signing secret.

PayPal

1. In the PayPal developer dashboard create an app and copy its Client ID and Secret.
2. Choose Sandbox (testing) while you try things out, and Live when you are ready. Sandbox and live use different keys.

A payment method appears in the checkout only when its keys are filled in. Test with the test keys first: place an order yourself and check that it arrives under Orders.

Products

Open Products and click New product.

• Title and Description for each language of the site. The default language's title is required; an empty field in another language uses the default text.
• Type: Physical (shipped) or Digital (download).
• Price including VAT.
• Stock: a number, or empty for unlimited. At 0 the product shows as Out of stock. Stock goes down when an order is paid.
• SKU, your own product code (optional).
• Pictures: the main picture and more for the gallery. Without a main picture the first gallery picture is used.
• Categories and tags: tick the ones that fit. Create them under Product categories and Product tags in the menu; they work like the categories and tags of posts (also per language) but are separate from them.
• Address: the web address of the product (/shop/…). It is made from the title.
• Status: Draft products are invisible to visitors; Published ones are in the shop.

Digital products. Save the product first, then use Download to upload the file (PDF, zip, e-book, audio, …). Set how many times the buyer may download it and for how many days the link works. The file is stored outside the public files; nobody can open it without the buyer's personal link.

What visitors see

• /shop lists the published products; each has its own page with a quantity box and Add to cart.
• The cart shows the lines, the shipping and the total, and has a Checkout button.
• At the checkout the buyer enters name, email and (for physical products) a shipping address, and chooses Stripe or PayPal. Payment happens on Stripe's or PayPal's own page, so card details never reach your site.
• After paying, the buyer lands on an order page with the result and, for digital products, the download buttons. A confirmation email goes to the buyer (if outgoing mail is set up in Settings) and a notice to you.

Each category and tag has its own page, /shop/category/<address> and /shop/tag/<address>, which shows only its products. The shop page lists the categories as small links above the products, and the product page shows the product's own.

To put products on another page, such as the home page, add the Product grid block. The Cart link block adds a button to the cart, for example in the header; it can have an icon (cart, bag or basket) or a picture of your own, and the number of items in brackets or in a small badge. The Product categories block lists the categories or tags, and Product grid can show one category only. Both are in the Shop group of the page builder.

The shop's pages use your header and footer from Design.

Designing the shop's pages

When the shop is on, Design shows five more templates next to Header, Footer and Post: Shop (the list of products), Product, Cart, Checkout and Order. Open one and change it like any other page: move, add and remove blocks, and style them in the Design tab (colours, fonts, spacing, corners).

• Shop uses Shop heading (it shows the category's name on a category page), Product categories (the links) and Product grid (how many, how many columns, with or without the add-to-cart button).
• Product is built from Product pictures, Product name, Product price, Product description, Product categories & tags and Buy box. The first two columns of the built-in layout show the pictures on the left and the rest on the right; you can rearrange them, for example to put the price above the name.
• Cart, Checkout and Order each have one main block (Cart, Checkout form, Order summary). Put headings, text, pictures or columns around it as you like, for example a note about delivery times above the checkout form.

In the builder these blocks show made-up sample products and orders, so you can design the pages before you have sold anything. Reset to the default design (in the builder) brings a template back to the built-in layout.

Orders

Orders lists paid orders, newest first. A number in the menu counts new ones you have not opened yet. Click an order to see the buyer, the products, the shipping address and the buyer's note.

Refunds. Make the refund in Stripe or PayPal itself. Then click Mark as refunded here: it records it and switches the buyer's download links off. Stock is not put back automatically.

Good to know

• Prices include VAT; the shop does not calculate VAT, invoices or shipping by country. Shipping is one fixed amount for all orders that contain a physical product.
• An order is marked paid only when Stripe or PayPal confirms the same amount that was ordered.
• If two buyers pay for the last item at the same moment, both orders are valid and the stock stays at 0. You decide how to handle it.

Troubleshooting