Subscription Studio: complete functionality specification

12 November 2026. Proposed full product, independent of release order. Read the reference atlas for the six different observed shopping patterns, and the architecture evidence for current provider/API constraints. This document defines what the proposed product must do; it does not claim those backends are implemented.

1. The merchant creates an offer, not just a widget

An Offer owns a customer promise, merchandise eligibility, selection policy, pricing, billing/delivery schedule and operational owner. An Experience presents that offer as a PDP control, club comparison, box builder, quiz, gift page or office planner. A layout change must not create a different subscription agreement.

The merchant begins with one of six templates. The editor then reveals relevant settings and a matching customer preview. Avoid a universal empty form with dozens of unrelated toggles. Each template can have merchant-authored names and visual presets without losing its semantic identity.

Refill and office supply can share a recurring merchandise mechanism while having very different entry and configuration experiences. A curated club and a personalized club differ in who chooses and what the customer has authorized. A gift requires an entitlement model beyond finite recurring billing.

2. Builder steps and rule consequences

Offer → Coffees → Options and price → Schedule and choices → Stock and replacements → Experience and review. Keep a persistent shopper summary and a way to inspect the next delivery as well as the first order.

The readiness panel explains specific missing requirements. Examples: “Two selected coffees have no filter-ground variant”; “A no-response fallback has not been chosen”; “This gift has six deliveries but only five funded shipments”; “The replacement raises the agreed amount.” A saved draft is useful even when not ready. Publishing requires actual capability and configuration verification.

3. Customer-built boxes in detail

The customer can inspect a coffee without losing their box, filter by approved coffee attributes, add or remove quantities, select valid grinds and see total bags/weight. A visible tray says what remains to complete the offer. Keyboard and mobile users need an equally clear selection count; the tray must not obscure the last coffee card.

Distinguish three commercial designs:

• Sum of selections: each component has a real price; a configured discount may apply. Price changes when selected coffees change.
• Fixed box allowance: a stated number of eligible components costs a stated amount. Premium coffees require an explicit surcharge or exclusion, not a silently reduced merchant margin.
• Tiered quantity offer: the quantity band changes the configured price/discount. Show the actual threshold and outcome; do not invent false urgency.

A two-coffee box is not necessarily two bags: two coffees at 1kg each total 2kg; four 250g bags can contain two origins twice. The data model and UI must state both identities and quantities. An unavailable grind should disable that variant, not remove the customer's whole box without explanation.

For recurring boxes, the merchant chooses whether the initial selection repeats, the customer may reselect before each cycle, or the merchant selects later contents. If the customer does nothing, the disclosed rule might repeat the last valid selection, use an authorized roaster selection, or skip. The selected engine must be able to enforce the exact rule. A storefront builder alone cannot promise this.

When one component sells out, show which line is affected and the price/weight/eligibility effects of each alternative. Specify whether the entire box waits or partial fulfillment is permitted. Shipping a partial box at the original full price is not a neutral fallback. Several independent recurring cart lines also do not establish one atomic renewal or shipment; the implementation must prove the box-level promise.

4. Curated and personalized programs

A curated club has a stable identity and versioned cycle contents. Its current landing page can show the first shipment and past selections while allowing future lots to change within the offer. Different tiers can have different components and weights; rare coffee is not necessarily another standard 250g bag.

The merchant's cycle workspace shows due members, required physical variants/quantities, excluded or unmatched options, projected totals and readiness. Approval applies to an identified cycle/selection version. Later stock or customer changes can invalidate it. Preserve past selection records and historical orders.

A personalized program adds explicit preferences and recommendation history. Hard requirements such as decaf are applied before soft taste ranking. Brew method and whole-bean/grind are different questions. The explanation should reference actual facts and stated choices; it should not fabricate an assessment score or imply a medical suitability judgment.

The customer can edit preferences and understand when they take effect. An initial quiz recommendation does not establish ongoing adaptive selection. If promising variety, store selection history and define how repeats, favorites, missing eligible coffees and conflicting preferences are handled. When no coffee qualifies, ask for a choice or use an agreed safe policy; do not silently cross a hard exclusion.

5. Gifts and office supply

Gift: distinguish payer, recipient, gift-message delivery date, activation, coffee dispatch and remaining funded deliveries. The purchaser can preview the message and choose the permitted notification/activation route. The recipient activates once, selects eligible preferences/address and sees what remains. No undisclosed automatic renewal follows the final gift delivery.

A gift ledger must reconcile paid entitlement, successful shipments, pauses, replacements, failed fulfillment and partial refunds. An activation token needs single-use protection and a controlled recovery process. Define unclaimed gifts and changing addresses. Finite pay-per-delivery subscriptions and ordinary store gift cards are not automatically equivalent to prepaid fulfillment.

Office: allow direct kilograms entry and an optional calculator. Show the assumptions—people, cups per working day, grams per cup and working days—then round to actual pack quantities with an editable result. An estimate is not a promise of exact consumption. Support changing amount/cadence and a disclosed closure skip. A payer, delivery contact and account administrator may be different people.

Multiple locations, invoices/NET terms, purchase orders, role permissions and wholesale catalogs are additional office/B2B scope. The first office concept can use ordinary supported checkout and one address without implying those capabilities exist.

6. Shared domain and interfaces

The proposed engine interface has distinct operations to resolve capabilities, validate a selection, quote prices, prepare supported cart lines, read current contract/cycle state, preview a change, commit it, reconcile an unknown outcome and read the resulting order. These are conceptual contracts, not claims of a delivered public API.

The browser can give immediate feedback, but the server validates authoritative merchandise, price and permissions. Money uses currency and minor units with deterministic rounding. A quote identifies its configuration/catalog version and expires or revalidates when relevant facts change. Provider credentials and contract-write authority remain server-side. The agency interface uses the same validation and quotation as the visual builder.

7. Implementation proof by model

Apply the existing twelve-case lifecycle matrix to each released model; do not infer that a passing refill proves a passing box or gift.

The 2026-10 contract calculation API provides new bundle-edit capabilities, while other initial-checkout and merchant bundle surfaces retain restrictions. Use the evidence reconciliation for the exact platform boundary. Neither a general incompatibility statement nor a successful contract edit settles all six products.

8. Design review and commercial testing

The prototype must let the team actually build a multi-coffee box, compare club tiers, complete a guided match, compose a gift and estimate office supply. Each route needs its own substantive controls and review. Source references should show the different original patterns alongside their Coffee Kit interpretation, not merely reuse the existing Figma subscription image.

In merchant sessions, compare the full offer they need with their current tools and total bill. Ask which model creates their strongest switching reason and which controls they use in the next real cycle. Record a concrete tradeoff: the first operational release can deliver fewer models, but its scoped offer must remain worth the actual price. The broader product vision should remain visible and costed as additional work rather than disappearing from the pitch.

Operational discovery and demand planning

The configurations above are hypotheses until observed with a real club/box merchant. Follow the design-partner discovery plan before implementing advanced allocation. The demand and inventory specification separates upcoming cycles, physical reward exposure, forecasts, stock protection and confirmed engine actions. A studio stock check does not reserve inventory or stop a charge.

Source: subscription-product-specification.md The complete Markdown handoff and private datasets remain in the local project. This web edition includes selected supporting visuals and scenario downloads.