Internal review · 12 November 2026

Coffee Kit: subscriptions evidence and route decision

Research date: 12 November 2026. Scope: public documentation, supplied briefs, the recovered thread and local market aggregates. No app implementation, installed-provider test, merchant mutation, payment attempt or outreach was performed.

1. Decision in plain terms

Do not commit to a $99 subscription overlay before proving that its extra value survives the provider bill. Keep three routes open, with different customers and promises.

  1. Purchase-only UX over existing plans is the smallest useful route for merchants happy with their engine. Coffee Kit can connect coffee discovery, grind/size/quantity choices and enrollment. This does not deliver automated limited-lot replacement. Price the complete catalog/presentation/discovery kit on its demonstrated value; a nicer subscription selector alone is a weak $99 proposition.
  2. Deep provider orchestration is credible with affordable, documented APIs. Prioritize Seal, followed by Appstle's approved partner route, and support Recharge where an existing merchant's workflow warrants it. Loop/Skio are expensive defaults for new small roasters. Curobi deserves a direct competitive test, but its conflicting access documentation prevents an unconditional integration recommendation.
  3. A deliberately narrow owned engine is a serious option if subscriptions are the core paid product. Shopify supplies checkout, vaulting, contracts and charging APIs; its reference app supplies considerable application scaffolding. Fixed-SKU replenishment and one merchant-selected physical coffee per club cycle are a bounded product. The remaining work is concrete reliability, inventory, communications and management work, rather than building a payments platform from scratch.

Recommendation, conditional on evidence: use route 1 to test the connected selling experience with existing subscribers. For a subscription-led $99 single-app offer to new roasters, compare route 2 with Seal/Appstle against route 3 before choosing architecture. Advance the narrow engine if its distinct coffee workflow wins paid commitments and the reference-app audit plus lifecycle tests fit the team's capacity. Choose the provider route if it delivers the same promise economically with less ongoing work. Do not turn the lower initial engineering cost of an overlay into a claim of superior merchant economics.

Confidence: high on the documented platform boundary and observed price gates; medium on provider suitability; low on willingness to pay and delivery cost until a development-store test and merchant task comparison exist.

Boundary for the study website and wireframes

The concept may demonstrate coffee discovery and enrollment into existing eligible selling plans, with the current provider retaining billing and customer management. Describe provider names as research candidates, not working Coffee Kit integrations. Show automated physical-lot rotation as proposed, with two evaluated delivery routes: authorized provider API or a narrow Coffee Kit-owned engine. Neither route has passed an integration test. The website can explain this decision without presenting unfinished automation as live functionality. The three options should remain visible; do not silently commit the commercial offer to a provider overlay.

2. Evidence provenance and current market fit

Read before this work: the original user idea brief; current Coffee Kit and Krown direction briefs; existing data-discovery-evidence.md, economics-validation.md and checkpoint. The prior thread [research session] was read with includeOutputs:true. Its available response was truncated and recovered the Curobi pricing/API contradiction and Appstle partner lead, rather than a complete earlier research transcript. Current public pages were checked to close those specific gaps. The subscription agent ID in the old checkpoint resolves to this resumed work, so it is not an independent second source.

Labels below:

The user's latest v1.1 signal was independently matched to cohorts.roaster_active and cohorts.local_roaster_active in verified aggregates (local handoff artifact). The active roaster-language cohort contains 5,990 entities; the Local + roaster-language cohort contains 94. These are screening cohorts, not 5,990 qualified subscription customers or 94 confirmed customers Krown can contact.

Provider detection Active roaster-language entities, n=5,990 Local + roaster-language, n=94 Research implication
Recharge 948 16 Meaningful existing-provider compatibility candidate
Seal 914 14 Almost comparable signal with much lower advertised fixed fees
Appstle 727 13 Strong candidate if partner access is approved
Shopify Subscriptions 449 10 Essential free/native control
Loop 83 4 Lower local signal and expensive API entry
Skio 12 0 detected No justification for making this the initial default

The final market report uses the narrower strong coffee AND roaster-language cohort, coffee_roaster_active, n=5,820. Its detections are Recharge 934, Seal 892, Appstle 714, Shopify 436, Loop 81, Skio 12. The strongest changing-catalog screening intersection contains 1,073 entities with strong coffee + roaster language, positive products_created_30, and a mapped subscription provider. Product creation is a proxy; it does not prove seasonal coffee rotation. Local + strong coffee + roaster contains 88, with Recharge 15, Seal 12, Appstle 12, Shopify 10 and Loop 4. These are narrower filters, not revisions to the 5,990/94 counts above. Use 5,820/1,073 for the final market narrative. See market report and the same verified aggregates.

Detections overlap. A zero is absence of a detection in this cohort, not evidence of no installed users. No paid status, live subscription volume, adoption intent or provider reliability follows from these counts. See audit and limitations (local handoff artifact). Inference: prioritize Seal/Appstle/Recharge testing, rather than importing an enterprise DTC vendor ranking into this niche.

3. Coffee subscription models are different promises

Model Buyer promise Product and stock requirement Sensible first scope
Fixed-SKU refill The same blend/decaf, bag size and grind each cycle Actual variant remains available; preserve agreed price independently from catalog edits Yes, all three routes
Roaster's choice Roaster selects this cycle's coffee within a stated category Map to a real physical variant, preserve size/grind and club price; approve each cycle Yes for narrow own engine or tested provider
Taste-category club Consistently classic/adventurous/decaf, rather than the same lot Reviewed eligibility rules; explicit boundaries on replacements and price Later refinement of roaster's choice
Calendar club Everyone renews on a specified weekday/date Define cutoff, first charge and first shipment separately Native now provides a stronger control; avoid novel cutoff logic initially
Finite pay-per-delivery Stop after N orders Count successful orders consistently, including first order and skips Native control available; not equivalent to prepayment
Prepaid gift Buyer pays for several shipments for a recipient Recipient identity, claim/start date, remaining deliveries and refund policy Defer from narrow engine
Curated multi-bag box Roaster selects several physical coffees each cycle Component variants, quantities, stock and fulfillment traceability Requires separate bundle/line design
Build-a-box Customer chooses N items, potentially every cycle Choice windows, defaults for non-response, component availability, shared billing terms Defer from narrow engine
Quiz-personalized program Preferences influence subsequent coffees Persist stated preferences; explain mismatches and replacement choices Purchase quiz can ship before ongoing personalization

Real merchant examples establish that these shopping models exist, not the software beneath them. Square Mile offers whole-bean subscription choices. Trade's gift subscription uses a recipient redemption and quiz flow. Neither source proves Coffee Kit demand, a particular provider install or a sales uplift.

4. Shopify infrastructure versus app responsibility

Documented: storefronts can submit a variant plus selling plan to the cart; Shopify handles checkout pricing, consent, vaulted payment details and initial contract creation. The app maintains contracts, supplies management interfaces and automates renewals. Editing the original plan does not rewrite existing contracts. Shopify responsibility model.

Resource/action Route 1: purchase UX Route 2: provider orchestration Route 3: own engine
Published plan selection and cart Coffee Kit renders provider plan allocations and submits the supported purchase payload Same, possibly provider SDK/properties Coffee Kit renders its own plans
Selling-plan administration Existing app's setup Existing app/API if supported Coffee Kit
Subscription contract Existing app owns lifecycle Provider remains owner; Coffee Kit acts through provider API Coffee Kit is owning app
Renewal scheduling and recovery Existing app Provider, unless an explicit supported handoff exists Coffee Kit scheduler using Shopify charge APIs
Lot replacement Merchant/provider workflow Coffee Kit rules + authorized provider writes Coffee Kit rules + own contract edits
Customer portal Existing provider Prefer provider portal; add only justified actions Coffee Kit/customer-account extensions
Physical stock/order correctness Existing engine and actual sold variant Shared integration responsibility Coffee Kit mapping and Shopify order/inventory behavior

The public SubscriptionContract reference requires read_own_subscription_contracts or write_own_subscription_contracts and exposes the managing app. These own-contract scopes are not a universal cross-provider write permission. Merchant OAuth access to products/orders does not itself confer contract ownership. A provider-issued key authorizes that provider's surface; it does not transfer the contract to Coffee Kit. An exceptional/read-all scope appearing elsewhere in Shopify's schema is insufficient evidence of general third-party entitlement.

Practical boundary: route 1 needs no provider Admin API for a plain, eligible Shopify selling-plan cart flow. Provider-specific bundle metadata, purchase widgets, tracking and customer portal actions still need a compatibility audit. Route 2 needs the provider's working write endpoints and commercial permission. No documented general API for external administration of the free Shopify Subscriptions app was established here; treat its setup and existing-contract editing as a merchant workflow until proven otherwise.

Current free Shopify Subscriptions control

Shopify now documents weekly/monthly/yearly plans with specific billing weekdays/dates and automatic expiry after 2–1,000 orders. The initial order counts, skipped orders do not, and the final order expires the customer's contract while leaving the plan available to new buyers. This is stronger than an assertion that native supports only signup-relative replenishment. Fixed billing dates do not establish a custom roast cutoff, and finite orders do not establish prepaid gift redemption. Current plan setup.

The free app also documents configurable payment/inventory retries and skip/pause/cancel outcomes, plus customer self-management. Those are real baseline features, not automatic Coffee Kit differentiation. Native settings.

October 2026 contract-editing correction

The SubscriptionContractCalculation flow is available in 2026-10, now stable as of this research date. It replaces stateful draft editing with calculate → asynchronous result/poll or webhook → commit, using the unified checkout engine. Legacy draft APIs coexist but are deprecated for this direction. Status-only actions remain separate. An early-access announcement written before October should not be read as saying the API is still an RC in November. Dated Shopify announcement.

The current migration guide describes four calculate operations plus commit, rather than freezing the early announcement's count at three. More significant: omitted top-level update fields can be preserved, but a supplied lines array replaces the entire stored list and each retained line must be fully restated. A rotation job must re-read/reconcile current state rather than send one changed line and accidentally remove the others. Cart transforms and delivery customizations are supported; the guide does not promise every Function type. Migration rules.

Bundles: surface-specific evidence conflict

The new API explicitly supports bundle contract edits from 2026-10, including grouped parent/component lines. Rebuilding from current merchandise definitions and preserving a stored bundle are different modes; deleted components/parents have specific consequences. Bundle contract-edit guide.

However, current merchant documentation still says bundles are incompatible with purchase options and the Shopify Subscriptions app; Shopify Bundles also lacks mix-and-match. Merchant bundle restrictions. The general developer bundle overview also retains a selling-plan limitation.

Conclusion: neither “Shopify can never do subscription bundles” nor “all bundle apps now work with subscriptions” is defensible. Contract-edit capability is verified; initial checkout, bundle representation, relevant enablement, provider adoption and renewal fulfillment must be proven for the exact combination. A box represented as several subscription lines, a permanent box SKU, and a native bundle parent/components product are separate designs.

5. Providers, prices and explicit API gates

USD advertised recurring prices observed 12 November. Provider percentage charges are additional to applicable payment processing/Shopify charges. Contractual, legacy and negotiated plans may differ. “API documented” is not a successful credential test.

Provider Observed price and coffee-relevant scope Exact public API/access evidence Unknowns and recommendation
Shopify Subscriptions Free app; fixed replenishment, specific billing dates, finite order count, retries and management Shopify platform contract API uses owning-app scopes; no generic external admin API for the free app established Best route-1 control. Do not promise Coffee Kit automated rotation over its contracts
Seal Free up to 50 total subscriptions; $5.95/100; $9.95/250; $24.95/500; $89.95/2,000; $199/50,000; $399/150,000; 0% transaction fee Detailed pricing matrix explicitly checks API & webhooks on every tier including Free. Merchant API includes line edits, status, schedule and rule updates; shop token uses X-Seal-Token First affordable deep-integration candidate. Confirm total-count semantics, automation behavior, webhook delivery guarantees and safe edits before billing. A $199 marketing card mentioning API is not an exclusive entitlement gate
Appstle Free to $500 subscription revenue/month; Starter $10 to $5,000; Business $30 to $15,000; Premium $100 to $100,000; 0% transaction fee. Business advertises build-a-box; Premium advertises product swaps Direct merchant API requires an active paid API plan, price not published in developer guide. Approved partner tokens bypass the paid API plan; onboarding assigns read-only/read-write Strong second candidate conditional on partner approval. Do not assume ordinary $10/$30/$100 tiers include direct API or that partner tokens unlock every plan-gated product feature. Partner fees/eligibility, webhooks and exact write permissions need confirmation
Recharge Starter $99 + 1.49% + $0.19/transaction; Plus $499 + 1.34% + $0.19; Custom negotiated. Workflow rotation documented; customizable bundles advertised on Plus Admin/Storefront APIs and SDK documented; store owner accepts API-specific terms and creates scoped tokens. No explicit Plus-only basic API gate found in the examined API guide Relevant existing base. Exact effective Starter API entitlement and rotation/bundle workflow access remain unconfirmed; public token instructions alone are weaker than explicit plan entitlement. Do not migrate a tiny roaster here just for the overlay
Loop Starter $99 + 1%; Pro $399 + 0.75%; optional loyalty-order charges shown separately Current pricing explicitly puts API/webhooks and Bundle SDK/API on Pro Expensive default. Existing Pro users may be suitable. Confirm any partner exception rather than assuming one
Skio Scale $599 monthly or $499/month annually + 1% + $0.20 on orders involving a subscription Scale pricing explicitly includes APIs/webhooks. Shop-specific GraphQL token; Authorization: API <token>. Help page says no API sandbox Existing merchants only as an initial direction; fee and testing constraints weaken a small-roaster default
Curobi Current pricing: Free/Starter $9.99/Growth $19.99/Business $29.99/Pro $69.99, every 30 days; 0% transaction fee. Boxes and fixed-calendar schedules on Pro Conflict: current pricing says developer API on every plan, webhooks Business+, API/webhooks off on development stores and require paid Shopify. Older API/pricing docs say API+webhooks Pro and all features free on dev stores Direct competitor and conditional candidate. Effective access is unresolved, even though both claims are verified as published. Do not select it on a presumed free dev API
Kitenzo Current commercial page: $0 fixed + 1.5% bundle sales, capped at $10,000/30 days; Enterprise negotiated Developer SDK/headless API exists but enabled per shop by request, with keys/origins provisioned by vendor Bundle commerce layer, not verified independent renewal engine. Exact API commercial entitlement and subscription compatibility need confirmation; another subscription app is required by its integration guide

Primary price/access sources: Seal matrix, Seal Merchant API; Appstle listing, direct API guide, partner framework; Recharge pricing, Recharge API/token access; Loop pricing; Skio pricing, Skio API use/testing, technical partner guide; Curobi current pricing, older pricing docs, older API entitlement; Kitenzo current pricing, developer access.

Specific evidence that changes the shortlist

Seal: its documented REST editing accepts a replacement variant ID, quantity and price for a subscription item. This is the essential primitive for a controlled coffee swap. Its rate limit is 10 concurrent requests per key, returning 503 when exceeded, not an assumed 10 requests/second. Public docs do not establish transaction locks against its renewal scheduler. A working endpoint is necessary but insufficient to guarantee an atomic pre-renewal swap. API reference.

Appstle: partner onboarding documents scoped per-merchant tokens, revocation on disconnect/uninstall, approved read-write access to status, skip/reschedule, discounts and line editing. It explicitly says merchants are not billed for partner API usage. This is stronger evidence than an anecdotal API surcharge, but Coffee Kit has no approved partner access yet. Direct API pricing and any developer-side commercial contract remain unknown. Partner integration. The API overview distinguishes customer-session Storefront APIs from API-key server access; they are not interchangeable.

Recharge: automatic monthly swaps already serve curated monthly programs, with monthly-frequency constraints; one-off and sequential workflows differ. Coffee-specific rotation alone is therefore not a unique Coffee Kit feature. Documented swap workflows. Compare preparing the next lot in Recharge against preparing it in Coffee Kit, including stock and merchant time, rather than merely comparing storefront screenshots.

Curobi: its coffee page claims rotating curated programs and build-a-box. API docs also state that contract line/status writes exist while plan/bundle definition write scopes are vocabulary without working endpoints. Even if all-tier access is effective, Coffee Kit cannot assume it can configure the whole provider backend through API. Documented API surface. This is competitive evidence, not established reliability or traction.

Kitenzo: older support pricing says $299/month + 1%, conflicting with the current 1.5%-only offer; use the current commercial page for scenarios and verify the installed contract. Dated older price. Its May subscription guide modifies the add-to-cart payload to include a selling plan from a separate app and recommends Single-SKU bundles while describing limitations. That is a purchase integration, not proof of component-aware recurring fulfillment after October's API changes. Subscription template guide.

6. Merchant economics across the three routes

Scenario, not forecast: $99 Coffee Kit fee, $30 subscription order value, one successful monthly order per subscription, no one-time items in those orders. Three cases: 100 orders/$3,000 revenue; 500/$15,000; 2,000/$60,000. Ignore tax, payment processing, Shopify plan fees, email/loyalty extras, discounts and implementation services here because they require merchant-specific inputs. Use actual invoices and fee bases in a pilot. Amounts are a normalized billing-period comparison; 30-day provider billing is not exactly a calendar month.

Route/provider, including proposed $99 Coffee Kit 100 orders / $3k 500 / $15k 2,000 / $60k
Purchase UX + native free app $99.00 $99.00 $99.00
Deep Seal API, tier sized to total count $104.95 $123.95 $188.95
Deep Appstle partner + Premium budget* $199.00 $199.00 $199.00
Curobi Pro + overlay, access unresolved $168.99 $168.99 $168.99
Recharge Starter + overlay** $261.70 $516.50 $1,472.00
Loop Pro API + overlay $520.50 $610.50 $948.00
Skio monthly Scale + overlay $748.00 $948.00 $1,698.00
Coffee Kit narrow owned engine*** $99.00 $99.00 $99.00

*Conservative feature budget because native product swaps appear on Premium; an approved API implementation may need a lower tier, but the evidence does not establish permission to bypass plan-gated features. Partner usage fee bypass is documented; partner acceptance and other commercial terms are unverified.

**Illustrative Starter pricing, not confirmation that the intended workflow is entitled there. Plus bundles at $15,000/500 orders would cost $499 + $201 + $95 = $795 provider-only, or $894 with Coffee Kit, before other charges.

***Merchant price hypothesis. Coffee Kit bears development, infrastructure and support cost; there is no free internal engine operation implied.

Seal scenarios assume total subscription count equals the shown count, with no additional cancelled/paused records consuming the cap. All routes have different feature coverage; the $99 native row cannot be sold as an automated rotating club. Scenario generator (local handoff artifact) and 24 computed cases preserve formulas and qualifications.

What these numbers support

At $3,000 recurring revenue, the proposed $99 alone is 3.3% of recurring revenue. Seal + Coffee Kit is about 3.5%; Loop Pro + Coffee Kit is 17.35%; Skio + Coffee Kit is about 24.93%. Revenue percentages do not equal profit percentages. A $99 overlay that requires a small roaster to buy Loop Pro or Skio is a weak default offer. It needs substantial, observed value beyond subscription selection and ordinary swaps. At $15,000, adding Kitenzo's 1.5% for another builder would add $225 to the relevant stack if all that revenue is billable bundle sales; its fee basis for renewals needs confirmation.

For an existing provider merchant, distinguish total stack cost from incremental adoption cost. If they already pay for an entitled API plan, the incremental fee may be $99. If the integration requires upgrading Loop Starter to Pro, the fixed uplift is $300 plus Coffee Kit, partly offset by the lower percentage: $399 − 0.25% × eligible subscription revenue, before other differences. At $15,000, that is $361.50 incremental; it cannot be described as a $99 upgrade.

Using the companion economics note's illustrative $18 contribution per genuinely incremental order: $99 requires six additional orders; a $361.50 incremental upgrade requires 21. Alternatively, at an assumed $30/hour, those amounts require 3.3 and 12.05 hours of useful saved work per billing period. These are thresholds for merchant evidence, not promised conversion uplift. Do not charge the overlay's value case for provider spend the merchant would already incur; also do not hide provider upgrades caused by Coffee Kit.

The strongest contradiction to an engine-first cost argument is Seal, not Skio. Replacing a $5.95–$24.95 engine creates little fee-saving justification for our own engine. Owning one must improve the single-app workflow, coffee-specific controls or supported outcome enough to pay for its maintenance. Conversely, a new roaster that would otherwise need a $399 API tier has a credible single-vendor cost reason to consider a narrow Coffee Kit engine.

Coffee Kit's internal owned-engine sensitivity

Budget scenario only, not an estimate from a completed build: 240 incremental engineering hours at $60/hour = $14,400; amortize over 24 months = $600/month. Ongoing maintenance 16 hours/month at $60 = $960/month. Add per store $3 incremental infrastructure/email and 10 minutes incremental support at $30/hour = $5. Incremental engine burden = $1,560 / engine stores + $8 per store/month.

Engine stores sharing those fixed costs Incremental engine burden/store/month
20 $86.00
50 $39.20
100 $23.60

This excludes the existing catalog/showcase app's costs and acquisition; cash salary and allocated labor must not be counted twice. Maintenance of 32 rather than 16 hours adds $19.20/store at 50 stores. The table shows why cheap merchant pricing and lean-team operability are different questions. Replace 240/16 with measured spike/on-call/support results before an investment commitment.

7. A deliberately narrow owned engine: bounded specification

What Shopify's reference app actually removes

Shopify publishes a subscriptions reference app including basic merchant and customer functionality; it is explicitly a starting point, and an App Store submission must add substantive merchant value. Public core component documentation describes hourly billing jobs, bulk charging, failed-payment recovery, persistence and inventory-error handling. It would be inaccurate to budget all of these as inventions Coffee Kit must design from zero.

A read-only source inspection pinned to 575a825f9f38aca9b0a1880e0fac10121b572a1c found:

Source evidence Implication for a narrow engine
Recurring billing job and charge job call Shopify bulk billing for eligible unbilled cycles Reuse/audit a working architectural pattern; add the coffee rotation barrier before eligibility to charge
Job runner guide distinguishes local inline execution and production Cloud Tasks Production queue setup is real remaining work; an always-running development process is not a production scheduler
Customer email service and merchant email service return success without sending Supply transactional email transport, templates and delivery monitoring; a marketing automation platform is unnecessary for this minimum
Draft edit and draft commit remain in the inspected source Reuse UI/domain patterns while budgeting a 2026-10 calculation-flow adaptation
Template config uses unstable webhooks and broad scopes Pin versions and justify minimal scopes rather than copying deployment defaults
License grants use/modification subject to Shopify integration/distribution conditions Available for the proposed Shopify app; not a general unrestricted cross-platform license. Preserve notices

Official docs additionally identify an unauthenticated-by-default internal job endpoint and tell developers to secure it. This is a specific production task. The source was inspected, not installed or exercised; no statement above proves renewal reliability. Production responsibilities in core guide.

Minimum useful owned scope — proposal

Support one domestic shipping market/currency, an explicitly verified payment gateway, pay-per-delivery plans, a small fixed set of weekly/monthly cadences, fixed-SKU replenishment, and a roaster's-choice club with one physical coffee variant and quantity per renewal. Preserve customer-selected bag size/grind, charge the disclosed club price, and require the merchant to publish each cycle's selection before billing. Offer pause, skip, cancel, address/card update and basic merchant exception handling. New clubs/customers first; no automatic migration of existing provider contracts.

Defer prepaid gifting, multi-coffee build-a-box, customer-editable monthly selections, variable-price substitutions, wholesale terms, custom roast cutoffs, POS enrollment, pickup scheduling and international billing. These are explicit product boundaries rather than claims Shopify cannot support them. Product/bag information and cancellation remain understandable without the founder operating the interface.

Owning subscriptions requires requested access and protected-data handling. Shopify documents the reference app's scope approval path; existing Krown app access does not prove approval for Coffee Kit. Reference app setup requirements. Scope approval is an external gate, not a reason to call the engineering intrinsically impossible.

8. Physical coffee rotation and inventory correctness

Design invariant: the coffee promised for a specific renewal must correspond to the physical Shopify variant(s) on its resulting order. A permanent “Roaster's Choice” SKU plus a text property naming this month's Ethiopia does not by itself decrement Ethiopia's physical stock. Renaming one SKU every month also destroys useful lot identity and does not explain old orders.

Two honest representations:

Shopify checks variant availability during billing and can fail for insufficient stock/location issues. Billing APIs also support an inventory policy override; use an explicit policy rather than assuming the merchant's “continue selling” switch always prevents overselling. Billing/stock behavior, inventory policy argument. The native app's “create order” override can oversell; exception handling should not silently select that behavior. Native inventory exception UI.

Proposed rotation sequence: merchant approves lot → validate each required size/grind mapping and price → identify affected unbilled cycles → reconcile concurrent customer edits → calculate and commit the chosen physical line(s) → verify persisted variant/quantity/price → permit that cycle's billing → link resulting order and stock outcome to the approved rotation record. Missing mapping/stock becomes a visible hold/skip decision, not an invented replacement. Freeze the selection for a retry of the same cycle unless an explicit reviewed change occurs.

In a provider overlay, the provider owns charging timing. “Swap an hour before midnight” is not a proven synchronization mechanism. The required evidence is a supported hold/cutoff/pre-charge flow, or another documented schedule that can guarantee the edit completes before billing, plus read-back and exception reconciliation. This is a key provider acceptance gate. In an owned engine, control of the charge queue makes this barrier easier to express, while Coffee Kit also owns recovery if the queue stops.

9. Twelve lifecycle edge cases and acceptance evidence

These are proposed development-store acceptance cases, not passed tests. Route 1 delegates provider lifecycle behavior and must explain that boundary; routes 2/3 must prove the promised orchestration.

# Trigger Required behavior/evidence Owner or route consequence
1 Seasonal lot sold out before renewal Approved replacement matches size/grind/category; verify actual variant, agreed price, stock/location policy and resulting order; otherwise hold/skip with notice Deep provider write or own engine; route 1 alone cannot promise this
2 Product deleted/archived or a grind/size removed Stop enrollment into invalid choices; show affected contracts and a reviewed mapping; preserve historic coffee/order facts Both integrations and engine need catalog reconciliation
3 Card decline versus authentication/action required Classify error; bounded retry for recoverable failures; secure payment-update/action link; no repeated blind retries for incompatible/revoked methods Provider for routes 1/2; Coffee Kit for 3
4 Billing request times out; webhook duplicated or late Reuse billing idempotency identity/reconcile attempt state; at most one successful charge/order for the cycle; deduplicate side effects Provider does its billing; Coffee Kit must also deduplicate rotation/notifications
5 Cancel/pause/skip coincides with queued rotation or charge Re-read current status/cycle immediately before work; honour cancellation cutoff; record already-created order separately from future cancellation A shared authoritative status and race policy are required
6 Catalog or subscription price/discount changes Existing contract honors agreed price until explicit approved change; preview shipping/tax/discount consequences and notify where required by the offer Plan edits and contract edits cannot be treated as the same operation
7 Address change, unsupported country or pickup request Validate delivery method and cost before next charge; surface unsupported requests; narrow engine initially supports domestic shipping only Avoid taking a renewal that cannot be fulfilled as promised
8 DST/month-end/leap-date, customer reschedule or signup near club date Verify first charge, first shipment, next dates and timezone; use provider-native schedule semantics; no double charge near cutoff Fixed-date native capability still needs first-cycle verification
9 Finite plan, prepaid/gift, or skipped installment Native finite control must expire after correct successful order count; prepaid fulfillment balance differs from recurring charges; gift buyer/recipient differ Narrow engine defers prepaid/gift and rejects unsupported enrollment
10 Mixed basket, several subscriptions, multiple bags or discounts One-time items stay one-time; every recurring line has valid plan/quantity; separate cadences/contracts explained; stock covers physical components Do not market arbitrary multi-line cart submission as one atomic club
11 Provider key revoked, app downgraded, Coffee Kit uninstalled or provider migrated Stop unauthorized jobs, identify continued provider renewals, preserve export/audit; own engine presents clear loss of service and migration/cancellation path Uninstalling an overlay does not mean provider contracts were cancelled
12 Paid order refunded, fraudulent first order, partial fulfillment or return Separate order refunds/fulfillment from future contract status and finite-order counts; prevent unintended continuation/re-shipment; retain support trail A refund is not inherently subscription cancellation

Shopify supplies billing attempt states and idempotency primitives, so case 4 is not an unsolved payments invention. Billing attempt object. Its documented error taxonomy includes inventory, payment-method and buyer-action failures; those should drive distinct actions. Error codes. Provider credentials or payment-token migrations are a separate coordinated process, not a CSV-copy guarantee. Shopify payment-method migration.

10. Reviewable next decision, without implementation or outreach

Candidate route Evidence needed to advance Result that would reverse the recommendation
Purchase-only, Shopify/Seal/Appstle/Recharge existing plans Real coffee enrollment task with correct allocations, price and checkout; merchant values whole kit at actual price A selector is the only improvement and the merchant won't pay for the connected experience
Deep Seal Exercise documented API on the actual intended tier; verify total-count billing, line swap/read-back, webhook behavior and synchronization with next charge Unsafe pre-charge coordination, hidden commercial restriction, or no time/value improvement over native Seal swaps
Deep Appstle partner Approved read-write partner entitlement and commercial terms; compatible product tier, events and safe rotation flow Rejected onboarding, unaffordable terms or required features outside approved access
Existing Recharge users Confirm exact installed plan/API/workflow entitlement; measure current rotation task against Coffee Kit Upgrade/bundle cost exceeds observed workflow value, or Recharge already solves the task well
Narrow owned engine Read-only audit converted into a bounded spike estimate; approval path; production queue/email plan; fixed-SKU renewal + one approved physical-lot rotation + failure/restart evidence Maintenance/support cost exceeds margin, promised scope expands into complex boxes, or no merchant prefers the single-app outcome

Proposed evaluation uses the same merchant coffee, price, stock constraint and second-cycle task across routes. Measure merchant configuration minutes, correct physical order/stock outcome, exception recovery, support minutes and combined recurring spend. Use a stable blend as the control and a real expiring lot as the differentiating task. No conversion lift should be claimed from a small qualitative study.

Commercial gate: show qualified merchants the actual combined bill and supported scope. A $99 Coffee Kit + $24.95 Seal workflow is a different offer from $99 Coffee Kit + $399 Loop API, and a new $99 Coffee Kit engine competes with a free native app and inexpensive Seal. Require observed saved work or credible incremental contribution over that specific baseline. If the full kit cannot justify the extra fee, lower/repackage the offer or keep purchase components with the theme; do not hide a weak value case behind an integration strategy.

This report completes the public-evidence comparison. Effective provider credentials, production reliability, payment-gateway/market behavior, merchant willingness to pay and actual engineering cost remain unverified. No merchant access or outreach was needed to establish the documented gates and prepare the next test.

11. Migration addendum: a replacement-worthy coffee selling solution

Added 12 November 2026 following the founder's clarification. “The #1 solution for selling coffee on Shopify” is an ambition, not a verified ranking. Existing providers are potential displacement targets, not permanent dependencies. The defensible proposition is one better coffee-selling workflow: reviewed catalog → discovery → enrollment → physical-lot renewal → customer management, with assisted switching. Purchase-only UX can validate entry, but an owned engine earns replacement status through that complete outcome. Neither inexpensive billing nor migration alone is a durable moat.

Ownership, portability and customer authorization

Documented: the subscription agreement is between merchant and customer; Shopify stores the contract and identifies its owning app, whose scopes govern administration. A provider API key grants provider access; it does not transfer Shopify ownership. Selling-plan changes do not rewrite existing contracts. No universal third-party reassignment mechanism was established here: budget supported recreation/import into destination-owned contracts, preserving source-to-destination IDs. Contract model, responsibility model.

Payment methods are a separate layer: Shopify-vaulted customer payment-method IDs versus legacy processor-held tokens. Neither is a portable plaintext card export; provider API credentials are also separate secrets. Same-store migrations may reuse valid Shopify payment methods, but retain the exact method associated with each contract: Recharge warns that omitting its ID can select another saved method. Recharge migration requirements.

Shopify documents token migration on all plans with subscription-developer support; raw card-number migration uses paid Professional Services and requires Plus/Enterprise. Legacy secondary-gateway removal and cross-store moves need separate assessment. Changed PayPal accounts can require customer reauthorization because billing agreements belong to the originating account. Do not promise universal “no reconsent.” Where a valid authorization can be preserved, migration need not mean fresh enrollment; otherwise provide the supported payment-update/reauthorization flow, or fresh checkout where necessary. Preserve agreed terms; any proposed price, cadence or substitution change needs a separate customer-authorization assessment. Shopify payment migration and limitations.

Supported migration versus a file export

Official paths exist: Shopify Subscriptions offers contract CSV import/export; Appstle documents validation and paused destination imports; Seal documents CSV/manual recreation and conditional Recharge/Bold API migration in its manual. These establish feasibility, not a supported migration into Coffee Kit, whose importer and payment-access path remain unbuilt. Export/import does not automatically preserve payment authorization, schedules, prepaid liabilities, portal links, loyalty or analytics history. Recharge explicitly excludes historical/analytics data from its migration process. Recharge coverage.

Proposed rehearsal, cutover and rollback

  1. Scope: one source app/store/gateway/currency; classify vaulted versus legacy methods, supported products, paused/cancelled states, discounts, next dates and outstanding paid shipments. Agree exceptions and retain exports, source IDs and an audit ledger.
  2. Rehearse: validate mappings and totals with synthetic/redacted data; destination remains unable to charge. Separately verify authorized payment-method access. Reconcile every contract's merchandise, grind/size, price, shipping, status and next billing date. A CSV passing syntax validation is insufficient.
  3. Cut over: take a final delta; freeze source edits; stop source billing/retries and reconcile in-flight attempts before activating each destination cohort. Switch storefront plans and portal links. Assign exactly one billing authority per contract/cycle; maintain idempotency and success/order reconciliation. Appstle's paused-import sequence supplies a documented precedent, not a tested Coffee Kit guarantee.
  4. Observe: monitor the first renewal cycle and exceptions; retain the old app, securely restricted and unable to bill, while rollback remains necessary. Shopify cancels surviving app-owned contracts 48 hours after uninstall; uninstall is not a reversible pause. Recharge separately warns processing continues until cancellation. Verify the actual source stopping mechanism. Shopify lifecycle, Recharge exit procedure.
  5. Rollback/refunds: stop destination billing, reconcile completed charges/orders, then resume only unpaid cycles in the source if its contracts/credentials remain usable. After cancellation/uninstall, restoration may require recreation and provider help. Refund duplicate charges through the original order/payment route; separately resolve duplicate fulfillment. Handle refunds and future-contract cancellation as separate actions. Migration rollback cannot erase completed payment events.

Sales, AI and technical responsibility

Sales can qualify workflow fit, compare actual invoices, collect scoped access approvals, demonstrate the replacement, coordinate timing and explain changed customer links. AI can draft field mappings, flag anomalies, compare redacted snapshots and prepare merchant/customer instructions. Deterministic validation and technical review decide correctness. Keep payment credentials/card data out of ordinary AI prompts.

Engineers/providers retain payment-access verification, gateway coordination, importer correctness, status/billing synchronization, exception handling and rollback execution. The merchant authorizes the switch and communications; customers complete any required reauthorization. AI assistance reduces preparation work; it does not establish authorization or guarantee payment portability.

Fixed-scope service economics — assumptions

Test $750 one-time, separately from $99/month, for up to 500 simple pay-per-delivery contracts, one supported source/store/gateway/currency, one rehearsal and cutover, and first-cycle monitoring. Exclude prepaid/gifts, processor changes, bespoke bundles, historical analytics reconstruction and provider fees.

Illustrative cost: sales coordination 2h × $30 = $60; technical work 3h × $60 = $180; support/monitoring 2h × $30 = $60; tooling $20; contingency $100: $420, leaving $330/44% contribution before acquisition and fixed overhead. Five extra technical hours consume $300. Waiving the fee subsidizes $420 of delivery, or $70/month over six months before recurring costs. Measure actual hours and quote exceptions separately. Replacement should win on the ongoing coffee workflow; assisted migration makes that choice attainable. No migration or outreach was performed.

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