Skip to main content
Episode 16 of 24Back office50 min

Manage orders, shipping, refunds and stock from the admin

Add an order desk to the admin panel: status changes, tracking-number emails, refunds through your payment gateway, stock levels with low-stock alerts, and a customer list.

You will have: An admin area where you can find any order, mark it shipped with a tracking number, refund it, adjust stock with a written reason, and see which products are running low.

Before you start

  • Episodes 12 to 15 are done: checkout creates orders, payments and emails work in test mode, and the admin panel can edit products
  • Place two or three test orders first so the new screens have something to show
  • Have your Resend sending address ready; the agent will reuse the email templates from Episode 14
  • Decide who should get low-stock alerts (usually your own email) and how low is "low" for a typical product

Make it yours

Change the example (a fashion store) to your own. Your answers are saved in this browser and used in every episode.

Other series keywords (4)

Your prompt

Paste into: Your AI agent (Claude Code or Codex) opened in your project folder (the folder you created in Episode 4). Start a fresh session so it reads your project notes first.
You are a careful senior full-stack engineer working inside my project folder. The store is "Thread & Needle", a fashion e-commerce store selling women's and men's clothing, shoes and accessories in United States, charging in USD. Payments run through Stripe. The admin panel already manages products. Now build the order and stock desk. I am not a programmer, so explain any technical word in a few words.

Plan first: read the existing orders, products, payments and email code, then show me your plan (tables to add, pages, order status rules) and wait for my OK before changing anything.

Tasks, in this order:
1. Orders list at /admin/orders: newest first, 25 per page, filter by status and date, search by order number or customer email. Show number, date, customer, total in USD, payment status and fulfilment status.
2. Order detail page: items, quantities, prices paid, shipping address, payment reference, and a timeline of every change. Never show or store card data.
3. Status changes: allow only sensible moves (paid to processing to shipped to delivered; cancelled and refunded as end states). Enforce the rules on the server, not only in the buttons. Record every change in an order_events table with the admin who did it and the time.
4. Fulfilment: a "Mark as shipped" form with carrier and tracking number (validate length and characters). Send the customer a shipped email through Resend using the Episode 14 template style, with the tracking number and a link to their order. If the email fails, keep the status change, record the failure and show a "Resend email" button.
5. Refunds: full or partial, with a reason and a confirmation step. Call the Stripe refund API from the server only, with an idempotency key so a double click cannot refund twice. The refunded amount must never exceed what was paid minus earlier refunds. The final refund state must be confirmed by the gateway's signed webhook, using the same pattern as the payment webhook. Offer a "return items to stock" tickbox.
6. Stock: add a stock_movements table (sale, restock, manual adjustment, return) so stock is always explained. Paid orders reduce stock inside one database transaction and stock can never go below zero. Add a manual adjustment form that requires a reason. Add a low-stock threshold per product and a "Low stock" panel on the admin dashboard. Email me a low-stock alert when a product crosses its threshold, at most once per product per day.
7. Customers: a list with name, email, number of orders, total spent and join date, search, and a detail page showing that customer's orders. Never select password hashes, and never show them anywhere.

Security rules:
- Every admin page, server action and route checks the admin role on the server.
- Validate all input with Zod. Use database transactions for anything that changes money or stock.
- Never print, log or commit secrets. Use .env.local and keep .env.example names only.
- Do not put customer emails or addresses into logs.

Verify: run type-check, lint and a production build. Then walk through test mode: ship one order, partly refund one, fully refund one, adjust stock, and trigger one low-stock alert. Show me the results, plus any step that needs me to click in the Stripe dashboard.

Commit on a feature branch with a clear message and open a pull request if GitHub is connected.

Report back in this format: 1) What was done. 2) What I should check myself. 3) Anything that needs my decision.

Review the prompt, then copy it. Never paste real passwords or API keys into a chat.

How to check it worked

  • /admin/orders lists your test orders and the status filter and search both change the list
  • Marking an order shipped with a tracking number sends an email you can open, with that number inside
  • A partial refund shows the right amount in the order timeline and in your payment gateway's test dashboard
  • Trying to refund more than was paid is refused with a clear message
  • A product set below its threshold appears in the Low stock panel and triggers one alert email
  • The customer list shows order counts and totals but no passwords or card details

Sample result

Fashion store example

Example result for the fashion store: the order desk and the low-stock panel. Names and amounts are test data.

If something goes wrong

The refund works in the gateway but the order in your admin still says Paid.
The final state comes from the signed webhook. Check that the webhook now listens for refund events (in Stripe, charge.refunded) and that your test webhook secret in .env.local matches the dashboard. Ask the agent: "Show me the last webhook delivery and why the order did not change."
The shipped email never arrives.
Open the order timeline for a recorded failure. Common causes are an unverified sending domain or a wrong API key name. Ask the agent to run the Resend check from Episode 14 and read you the error without printing the key.
Stock goes negative or two orders buy the last item.
Ask: "Show me the transaction that reduces stock and add a database rule that stops stock going below zero, with a test that places two orders at once."
The customer list is slow or shows too much.
Ask for pagination and a search box, and confirm that only name, email, order count, total and join date are selected from the database.

Free to build. Refunds may not return the payment gateway's fee on the original sale, so check your gateway's refund terms before you promise customers anything.

More in Back office

This is part of the series Build a secure, no-cost e-commerce website with AI agents. See all 24 episodes, the tools used and answers to common questions on the series page.

We use optional cookies for analytics and referral tracking. Learn more about our privacy policy