# ADR 0002 — The Combined Order is the unit of the customer's order pages; URLs stay per Child Order

- Status: accepted
- Date: 2026-10-20

## Context

`/purchase_history` paginated `orders` rows, so a checkout split over several sellers
showed up as several unrelated "orders", each with its own details page, while the
shipping, coupon, invoice number, Paymera payment and rating all belong to the checkout
(`combined_orders`). Every order belongs to a Combined Order, and 82% of checkouts have a
single Child Order.

## Decision

- The customer's order list and details page are built per **Combined Order**. A
  Single Order is just the one-child case, not a second code path.
- The list paginates and sorts Combined Orders (newest checkout first, 10 per page).
- The details page shows the shared data once and one section per Child Order.
- **URLs do not change.** The page is still reached through
  `/purchase_history/details/{encrypt(child order id)}`. Any Child Order's URL renders
  the whole Combined Order and scrolls to that Child Order. No new route, no redirect;
  every notification, Paymera return, e-mail and bookmark already sent keeps working.
  The list links to the first Child Order (lowest id).
- Opening the page marks every Child Order shown as viewed (`delivery_viewed`,
  `payment_status_viewed`), not only the one in the URL.

## Consequences

- One Combined Order has several valid URLs (one per Child Order). Anything that needs
  "the" URL of a Combined Order uses its first Child Order.
- Code that builds links to the details page (`NotificationController`, the nav bell,
  the notifications page, `PaymeraController`, `CheckoutController` re-payment) needs no
  change.
- The app API (`Api/V2/PurchaseHistoryController`) still lists Child Orders, unchanged. The
  grouping lives in shared classes (`app/Services/CustomerOrders`), and the app got new,
  additive endpoints on them (`Api/V2/CustomerOrderController`, `docs/api/combined-orders.md`):
  same numbers and rules as the website.