Required Pages
Not every page in a theme carries the same weight. Some are hard requirements — without them the theme is broken. Others are strongly recommended. The rest are optional.
Hard requirements
These pages must exist and work correctly. A theme is not shippable without them.
| Page | Route | Why |
|---|---|---|
| Coming soon | /coming-soon | Shown when health check fails. Must render with zero API calls. |
| Newsletter verify | /newsletter/verify | The API emails this link. If the page doesn't exist, email confirmation breaks. |
| Newsletter unsubscribe | /newsletter/unsubscribe | The API emails this link. Legally required — customers must be able to unsubscribe. |
| Pesapal callback | /checkout/success | Pesapal redirects here after payment. Must show order confirmation. |
| DN Wallet return | /shop (or handle the route) | Dukanext Wallet redirects here with no query params after payment. |
| 404 | catch-all | Catch all unmatched routes. |
Coming soon
This is the most important page in your theme. When the health check fails, every visitor lands here.
It must render with no API calls whatsoever — not even /settings. If the shop is unhealthy, no endpoint will respond. Keep it completely static: a branded message, optional hardcoded contact info, nothing fetched.
Newsletter pages
The API sends emails on behalf of the merchant with links to these two routes. The link format is:
Verify:
/newsletter/verify?subscription=<id>&integrity=<integrityId>&email=<email>
Unsubscribe:
/newsletter/unsubscribe?subscription=<id>&email=<email>
Each page extracts the query params and calls the corresponding API endpoint. See Newsletter for the API details.
Payment callbacks
After payment, the provider redirects back to your theme. The pages must handle these redirects and show an appropriate confirmation or error state.
See Payment Callbacks for the full details on what each provider sends.
Strongly recommended
These pages are not enforced by the API, but a theme without them will feel incomplete to both merchants and customers.
| Page | Notes |
|---|---|
Home (/) | Entry point for most visitors |
Shop / product listing (/shop) | Browse all products |
Product detail (/shop/:id) | Full product info, variants, add to cart |
Category (/categories/:id) | Products filtered by category |
Search results (/search?term=) | Search is in the nav on most themes |
| Cart | Client-side state; can be a page or a slide-out drawer |
| Checkout | Order placement flow |
Customer login (/login) | Required if you support customer accounts |
Optional
These depend on the features your theme supports.
| Page | Notes |
|---|---|
Customer dashboard (/account) | Customer JWT required |
Order history (/account/orders) | Customer JWT required |
Order detail (/account/orders/:id) | Customer JWT required |
| Notifications | Customer JWT required |
Policy pages (/support/privacy etc.) | Pull content from GET /settings/policy/:type |
Contact (/contact-us) | Submits to POST /contact-form |
| Wishlist | If you implement wishlist functionality |
Redirect unauthenticated users from protected routes to /login with a ?redirect= param so you can send them back after they log in.