Owner's manual

This manual is for you, the shop owner. (CLAUDE.md is the technical map for your AI assistant.) It explains what the shop does on its own, what you do in the admin, and how to change the things that have no admin page.

1. The three parts of the shop

Rule of thumb: anything that changes often is in the admin (orders, products, prices, stock, announcements). Anything that rarely changes is a file (pages, menu, your address, shipping prices).

2. What happens automatically

When someone buys:

1. The buyer pays in the PayPal window (with a PayPal account or by card).
2. The order gets the next number (1001, 1002 …) and the stock goes down.
3. The buyer gets a confirmation email in their language, with the PDF invoice.
4. You get a "New order" email (always in English) with the address, and the postal documents attached: a CN22 label for goods under €300, or CN23 + address label + invoice from €300.
5. A book or other download: the buyer gets a personal download link (7 days, 5 downloads).

Every hour (the cron job you set up):

• Orders whose buyer paid but closed the browser too early are finished (PayPal tells the shop).
• Checkouts nobody paid are cleaned up after 3 days.
• After every new order, a backup is made (database, invoices, settings) into the folder shop.backup next to your site; the newest 10 are kept.

Every day: the exchange rate is fetched (if you chose "automatic" in Settings).

3. Your daily work in the admin

The black bar at the top of every admin page:

Orders – the list of all orders, like in WooCommerce. Click a number to open an order.

• Processing = paid, to be shipped. On hold = PayPal holds the money (check PayPal). Completed = shipped. Cancelled / Refunded = as it says.

• Shipping an order: open it, choose Completed under "Change to", enter the tracking number, click Update status. The buyer gets the "shipped" email with the tracking number. (Letters, e.g. stickers, need no tracking number.)

• Printing the papers again: the buttons "CN22 label", "CN23", "Address label", "Invoice PDF".

• Refunds: make them in PayPal. PayPal tells the shop, and the order turns "Refunded" by itself. A refund you arranged differently: set the status "Refunded (manually)".

• + Create test order: makes an order without payment (number T-1, T-2 …), with all emails and papers, no stock change. Use it after changing a template or a product.

Products – all products with price, stock and visibility.

• Click a product to change name, prices, sale price, texts, photos, weight, HS code, "visible in shop".
• + Add product for a new one. Photos: pick them from your PC or phone; they are resized for you.
• Test product (kind "Test product"): no shipping, not in the shop lists – for a real €1 test payment.
• Letter (under "Ships as"): small items like stickers ship for a flat price worldwide.
• Changing the English text does not change the translations – see section 5.

Stock – one page with all products and their numbers. Change, then Save stock once. An empty box means "not counted, always available". Below zero = sold, still to be made (backorder).

Customers – the customer accounts. Customers log in under "My account" to see orders and invoices.

Announcements – a coloured bar at the top or bottom of every page ("Summer sale", "Holiday until …"), with a text per language (empty = the English text is shown), start and end date.

History – orders, turnover and visitors per month and year.

Export – a CSV file of the orders for your accountant (opens in Excel).

Backup – the backups on the server, and a button to download a complete backup now.

Log – what happened recently (payments, emails, PayPal messages). "Ask PayPal" checks a checkout that has no result yet.

Server check – after every upload or change of hosting: every line should be green.

Settings – exchange rate (automatic or fixed), the US import duty in percent, maintenance mode (visitors see "We will be back soon", you still see the shop), and your admin password.

4. Changing things that have no admin page

There is no online editor for pages and settings files. You edit the file on your computer and upload it.

What you need

• A text editor made for code – it shows the structure in colours and never adds hidden formatting (Word or WordPad would break the files). Free and good: Visual Studio Code, Notepad++ (Windows) or Atom (no longer updated, but still works).

• An FTP program: WinSCP or FileZilla, with the login from your hosting.

How

1. Keep a copy of the whole shop folder on your PC – that is your master copy.
2. Open the file in your editor, change it, save.
3. Upload that one file to the same folder on the server (overwrite). Reload the page in the browser (Ctrl+F5).

Where is what

Pages are HTML fragments: no <html>, <head> or <body> – just paragraphs (<p>), headings (<h2>), lists, links. The shop wraps them in its design. .json files are strict: every comma and quote counts – if the shop shows an error after an upload, put back the previous version and check the file (your AI assistant spots a missing comma in seconds).

5. Languages

The shop has English, German, French, Spanish and Portuguese. Buyers switch with the globe menu at the top; emails and invoices follow the language the buyer used.

What is not translated is shown in English (and hidden from Google in that language). That happens when you add a product or change an English text. To translate: give the English text to your AI assistant or a translator, and put the result into the files in section 4. Admin → Products → "Download all products" gives you all product texts in one file.

6. Shipping and customs, explained

• Every country is in a price group (1–4). Each group has a price for heavy parcels (from a set weight, e.g. a kit) and for light parcels. Light items travel free in a heavy parcel.

• Letters (e.g. stickers) cost one flat price worldwide, and nothing extra with a parcel.

• Blocked countries cannot be chosen at checkout.

• USA: the import duty is charged at checkout and paid by you at the post office (percentage in Settings), so US buyers pay nothing on delivery. Other countries: the buyer pays duties on delivery.

• The demo uses India Post prices in rupees, converted with the exchange rate. Replace them with your own carrier's prices in data/zones.json.

7. PayPal

• Sandbox = test money (for the test site), live = real money. The keys are in private/config.php.

• Payments "pending" in PayPal (e.g. a currency you have not accepted yet) put the order On hold until you accept the payment in PayPal; the shop then continues by itself.

• Disputes and refunds are handled in PayPal; the shop records what PayPal reports.

8. When something goes wrong

1. Admin → Server check – a red line usually names the problem (missing file, wrong setting).
2. Admin → Log – what happened with a payment or an email.
3. Maintenance mode (Settings) – close the shop while you fix something.
4. Backups – shop.backup on the server holds the last 10; the README.txt there explains the restore.
5. Ask your AI assistant – describe what you see and paste the error message, never passwords or private/config.php.