Assist_Design/docs/how-it-works/services-and-checkout.md

# Services & Checkout

Where product data comes from, what we validate, and how we keep it fresh.

## Product Source

- Products and pricing come from the Salesforce portal pricebook (`PORTAL_PRICEBOOK_ID`), not WHMCS.
- Categories covered: Internet, VPN, SIM/mobile. Each SKU is a Salesforce Product2 + PricebookEntry record.
- The portal pulls only products marked for the portal category; Salesforce is the source of truth for names, SKUs, and prices.

### SIM family plans

- If a user already has an active SIM service in WHMCS, we also show SIM family/discount plans.
- If they do not have a SIM yet, we hide family plans and show regular plans only.

## Eligibility & Validation

- Internet orders check account-specific eligibility stored in Salesforce; the eligibility result is cached per account and invalidated when Salesforce signals a change.
- During checkout we confirm:
  - The user has a WHMCS client mapping and at least one payment method on file in WHMCS.
  - SKUs selected exist in the Salesforce pricebook.
  - For Internet orders, we block duplicates when WHMCS already shows an active Internet service (in production).

For the intended Salesforce-driven workflow model (Cases + Account fields + portal UX), see `docs/how-it-works/eligibility-and-verification.md`.

## Checkout Data Captured

- Address snapshot: we copy the customer's address (or the one they update during checkout) into the Salesforce Order billing fields so the order shows the exact data used.
- Activation preferences: stored on the Salesforce Order (activation type/schedule, SIM specifics, MNP details when applicable).
- No card data is stored in the portal; we only verify that WHMCS already has a payment method.

## Caching for Product Catalog

- Product catalog data uses Salesforce Change Data Capture (CDC) events; there is no time-based expiry. When Salesforce signals a product change, the cache is cleared.
- Volatile catalog bits (e.g., fast-changing reference data) use a 60s TTL.
- Eligibility per account is cached with no TTL and cleared when Salesforce changes.
- Request coalescing is used so multiple users hitting the same services endpoint do not spam Salesforce.

## If something goes wrong

- Missing payment method: checkout is blocked with a clear "add a payment method" message.
- Ineligible address or duplicate Internet: we stop the order and explain why (eligibility failed or active Internet already exists).
- Salesforce pricebook issues: we return a friendly "services unavailable, please try again later."
- Cache failures: we fall back to live Salesforce reads to avoid empty screens.