Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 6 additions & 0 deletions docs/adr/BILLING-WEB-0031-static-spa-boundary.md
Original file line number Diff line number Diff line change
Expand Up @@ -37,6 +37,12 @@ The build output is a static SPA:
item; transactional Subscribe, Resubscribe, and embedded-checkout actions
remain in the core frontend until the hosted app reaches parity.

> **Amended 2026-09-27 by
> [ADR-BILLING-WEB-0038](BILLING-WEB-0038-checkout-only-hosts-own-plan-selection.md):**
> the flag no longer redirects Plans & pricing. Plan selection stays in
> the host app, which opens billing-web `/v1/checkout` with a `plan`;
> billing-web hosts checkout, not a plan grid.

The first scaffold deliberately does not guess the future SDK interfaces or
credential lifecycle. Integration code must follow
[ADR-AUTH-CREDENTIALS-0011](AUTH-CREDENTIALS-0011-cloud-credential-lifecycle-invariants.md)
Expand Down
Original file line number Diff line number Diff line change
@@ -0,0 +1,94 @@
# ADR-BILLING-WEB-0038: Billing Web Hosts Checkout Only; Host Apps Own Plan Selection

Date: 2026-09-27

## Status

Accepted

## Context

`apps/billing-web` grew two things for choosing a plan: a plan grid on
`/v1/subscription` and `/v1/pricing` (`SubscriptionPanel` plan cards and
`PlanCard`), and a plan-change quote (`SubscriptionQuote`). Neither had a
design source. They were built in #17798 and #17937 as scaffolding while
the hosted app worked toward parity with the cloud app, which already has
its own pricing table, Monthly/Yearly switch, plan-change flow, and team
credit-stop selection.

The Milestone 2 live run on 2026-09-27 put the two side by side and found
the hosted copy had drifted from the in-app experience for the same
journey: yearly credits were labelled "monthly credits", and the
plan-change quote showed credits as a dollar amount. Each of these is a
small fix. The finding is that a second plan-selection UI with no design
source drifts by default, and every host that sends customers to
billing-web would carry that drift into the payment step.

The embedded checkout is the opposite case. ADR-PACKAGES-ACCOUNT-UI-0034
already puts payment presentation in `@comfyorg/account-ui` so that one
implementation serves every host.

## Decision

1. **billing-web hosts the embedded-checkout experience only**: the
payment step, the 3DS challenge, and the result. It renders the same
checkout UI as the cloud app's in-app embedded checkout, through the
shared components in `packages/account-ui`, not a restyled fork.

2. **Plan selection belongs to each host app.** The pricing table,
Monthly/Yearly, plan changes, and the team credit stop are chosen in
the host, which then opens billing-web `/v1/checkout` with `plan`, and
with `workspace` and `team_credit_stop_id` where they apply. The team
credit stop behaves in billing-web exactly as in the in-app embedded
checkout.

3. **`/v1/checkout` requires `plan`.** A plan-less `/v1/checkout`, and
`/v1/pricing`, redirect to the host app through `return_to` rather
than rendering a picker. The billing-web plan grid (`SubscriptionPanel`
plan cards, `PlanCard`, `SubscriptionQuote`) is removed.

4. **The remaining routes stay.** `/v1/subscription` keeps cancel and
resubscribe, without the plan grid; the host app keeps its own cancel
and resubscribe too. `/v1/payment-methods`, `/v1/invoices`,
`/v1/result`, and `/sign-in` are unchanged.

### Alternatives considered

- **Polish the billing-web plan grid to match the app.** Rejected: it
keeps two implementations of one UX, and the drift found in the live
run is what that arrangement produces between releases.
- **Ask design for a separate billing-web plan-selection spec.** Rejected:
it gives one purchase journey two designed UXs, which is the divergence
this decision removes, now with a design source behind each side.

## Consequences

### Positive

- A customer sees one plan-selection UI and one checkout UI whichever host
they start from.
- billing-web no longer needs plan catalogue, interval, or quote logic of
its own, so it has no copy of those to keep in step with the app.

### Negative

- A host without its own plan selection cannot send customers to
billing-web to pick a plan; it must build that UI or deep-link into a
host that has one.
- Rendering identically in both hosts means the shared components use
design-system token classes. That relaxes ADR-PACKAGES-ACCOUNT-UI-0034
rule 4 ("the package stays unstyled"), amended there.
- Cancel and resubscribe exist in both billing-web and the host app, so
those two actions still have two surfaces to keep aligned.

## Notes

- [ADR-BILLING-WEB-0031](BILLING-WEB-0031-static-spa-boundary.md): its line
that the flag redirects Plans & pricing to billing-web is superseded by
rule 2 and carries an amendment note.
- [ADR-PACKAGES-ACCOUNT-UI-0034](PACKAGES-ACCOUNT-UI-0034-payment-ui-belongs-to-the-shared-account-ui-package.md):
rule 4 is amended to allow design-system token classes.
- [ADR-AUTH-BILLING-0032](AUTH-BILLING-0032-billing-stays-outside-the-account-package-in-v1.md):
rule 4 (no site-local billing surfaces) is the same principle applied to
`apps/website`; billing-web's checkout follows it through the shared
package.
Original file line number Diff line number Diff line change
Expand Up @@ -81,6 +81,13 @@ does not live in the package.
framework-free above Vue; a promotion that drags the design system in has
not finished.

> **Amended 2026-09-27 by
> [ADR-BILLING-WEB-0038](BILLING-WEB-0038-checkout-only-hosts-own-plan-selection.md):**
> promoted components may use `@comfyorg/design-system` token classes so
> the cloud app and `apps/billing-web` render the same checkout
> identically. Host couplings (`Button`, telemetry, journey events) still
> arrive as inputs.

5. **Transport, commands and readers stay in `@comfyorg/account-core`.**
This decision moves presentation only. It also does not make a surface
shareable merely by moving it: state the frontend assembles from several
Expand Down
1 change: 1 addition & 0 deletions docs/adr/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -22,6 +22,7 @@ An Architecture Decision Record captures an important architectural decision mad
| [AUTH-WORKSPACE-0036](AUTH-WORKSPACE-0036-workspace-deep-link-contract.md) | Workspace Deep-Link Contract | Proposed | 2026-09-21 |
| [BILLING-CHECKOUT-0031](BILLING-CHECKOUT-0031-checkout-journey-instrumentation-contract.md) | Checkout Journey Instrumentation Contract | Proposed | 2026-09-09 |
| [BILLING-WEB-0031](BILLING-WEB-0031-static-spa-boundary.md) | Static SPA Boundary for Hosted Billing | Proposed | 2026-09-10 |
| [BILLING-WEB-0038](BILLING-WEB-0038-checkout-only-hosts-own-plan-selection.md) | Billing Web Hosts Checkout Only; Host Apps Own Plan Selection | Accepted | 2026-09-27 |
| [CANVAS-GESTURE-0029](CANVAS-GESTURE-0029-pointer-gesture-state-machine.md) | Pointer Gesture State Machine | Proposed | 2026-09-06 |
| [CANVAS-INTERACTION-0035](CANVAS-INTERACTION-0035-agent-node-picking-policy.md) | Agent Node Picking Policy | Proposed | 2026-09-19 |
| [CANVAS-SELECTION-0028](CANVAS-SELECTION-0028-single-selection-store.md) | Single Selection Store | Proposed | 2026-09-04 |
Expand Down
Loading