# Checkout and advertising

## Available screens and entry points

- `/provider/advertise`: all 15 existing placements in five groups; choose 7, 14 or 30 days to compare VAT-inclusive demo totals. Information buttons show placement descriptions and examples. Every Choose action carries the placement and duration into setup.
- `/provider/promotions`: retains the same advertising catalog for existing navigation links.
- `/provider/campaigns/new`: select a published listing or eligible company, adjust placement/duration, then Continue to checkout. Back to selection preserves the saved draft.
- `/provider/checkout`: one-column review, item/duration, subtotal/VAT/total and one confirmation button. Free plan, monthly/annual subscription, listing-slot pack, advertising, unavailable order and confirmation states are included. No fake connected card or card-entry form.
- `/provider/billing` and `/customer/account/billing`: Advertise entry at the bottom. Also available at the bottom of `/provider/plans` and as the last item in the shared Plans menu.
- `/design-system#cards`: reusable AdvertiseLink example; live checkout and advertising routes are listed in the route inventory and this guide.

## Source of truth

- `components/provider/ad-placements.ts`: 15 placement definitions, descriptions, net seven-day rates, duration multipliers and demo VAT. Catalog, setup and checkout share these calculations. These are existing illustrative prices, not approved live commercial rates.
- `components/provider/provider-commercial-data.ts`: subscription and slot-pack rates.
- `components/provider/checkout-order.ts`: catalog-only order resolution; no URL-supplied price is accepted. Invalid selection or a draft price that differs from the current rate cannot be confirmed. Existing confirmed campaigns return a status link without a second confirmation.
- `components/provider/provider-checkout.tsx`: review, local confirmation, error handling and a clear next action. Repeated clicks are guarded. Campaign dates start at local demo confirmation and existing records are preserved.
- `components/provider/advertising-options.tsx`, `campaign-builder.tsx`, `placement-info.tsx`: selection, setup and placement information.
- `components/kligo/advertise-link.tsx`: shared bottom-of-page entry card.
- `components/i18n/commerce-copy.ts`: new Hebrew and Arabic copy; English is the source text. Existing dictionaries translate placement descriptions, durations and names. RTL layout, mirrored back arrows and isolated currency amounts are included.

## Demo and production boundary

This remains a presentation prototype. Confirming an order updates browser-tab demo state only; no money is collected. There are no payment credentials, real invoices, server entitlements or automatic billing in this build. Subscription renewal preferences and listing-slot expiry are illustrative; production expiry must be implemented server-side. Paid ads use the existing demo schedule rules.

For production, approve prices, VAT/rounding and renewal/cancellation rules; use a payment provider's secure hosted checkout or hosted fields; compute authoritative prices on the server; verify payment events before activating entitlements; implement idempotent order/payment records, failure/retry/cancellation handling, refunds where applicable, invoicing and scheduled expiry. The browser confirmation handler must never become proof of payment.

KLIGO checkout is only for its own subscriptions, listing add-ons and advertising placements. Buyers and suppliers arrange and pay for their equipment/material/service deals directly. No buyer-deal checkout, escrow, seller payouts or commissions are added.

## Verification

- All 15 placements × 3 durations use matching net, tax and total values through checkout.
- Every subscription cycle and slot pack uses the source catalog rate.
- Invalid orders, unknown campaigns and stale draft prices fail closed; confirmed campaigns cannot be reactivated through checkout.
- New checkout copy plus all placement labels, descriptions, surfaces and group names have Hebrew and Arabic translations.
- Visually review both themes, RTL, amount readability and mobile wrapping; confirm selection survives Back to selection and successful demo orders open the relevant campaign, listings or billing screen.

Both downloadable packages include these source components, translations and this guide. The full project ZIP also includes the route and validation tests, along with the previous theme-integrated images and carousel improvements.

## Placement-specific information previews (September 2026)

`components/provider/ad-placement-preview.tsx` replaces the generic repeated card. It is shared by info dialogs and campaign setup. All 15 examples are available in `/design-system#cards` under **Advertising placement previews**. Dialogs scroll within the viewport; layouts use logical spacing and shared day/night surfaces. English, Hebrew and Arabic copy is in the normal dictionaries and `commerce-copy.ts`.

| Placement | Preview context and click destination |
| --- | --- |
| Featured listing | Yellow photo/price card with standard search/category neighbors → listing |
| Featured + priority | Separate priority position above standard results → listing |
| Search boost | Relevant search query and horizontal matching results → listing |
| Category boost | Active Earthmoving category and listing grid → listing |
| Featured map pin | Self-contained illustrative street map with the shared yellow sponsored marker control; selecting markers changes the example listing card |
| Featured company | Switch between homepage company section and company results → profile |
| Trusted provider spotlight | Approved-provider directory, with explicit separation of sponsorship and approval → profile |
| Company category spotlight | Company directory with four business-type filters → profile |
| Local company spotlight | Gush Dan location filter and local company results → profile |
| Crawler excavator sponsor | Wide company sponsor above crawler equipment results → profile |
| Wheel loader sponsor | Wide company sponsor above wheel-loader results → profile |
| Earthworks sponsor | Wide company sponsor above earthworks companies → profile |
| Homepage card + category hero | Two selectable steps: homepage listing card → wide category hero → listing |
| Homepage featured card | Sponsored listing among regular Popular near you cards → listing directly |
| Homepage banner | Wide logo/message banner between equipment and local company sections → profile |

The examples use actual catalog photos, official KLIGO artwork, company marks and the marketplace card surface system, with compact layouts for the dialog. They illustrate placement contexts, not guaranteed impression counts, exclusivity or exact pixel positions on every device. Shared ad formats intentionally stay consistent across surfaces; directory filters, page context and destinations explain the different reach. The map example is explicitly illustrative and uses the same KButton price-marker treatment as equipment browsing. It requires no external tile connection, so the placement remains visible offline. Buttons drawn inside sample cards are explanatory; the map and the two multi-surface preview controls are interactive. No campaign is created or changed by exploring these examples.

The pricing catalog and checkout logic are unchanged. Both generated source downloads include the preview component, translations, this guide and existing assets. Rebuild exports before publishing so downloadable ZIPs match the deployed source.