Demand, inventory and operational alerts

12 November 2026. Proposed product and developer specification. No merchant workflow, allocation mechanism, forecast accuracy or live provider control has been validated. Read with merchant discovery, subscription rules and loyalty rules.

Product decision

Add Demand & stock as a first-class merchant workspace. Subscriptions and physical coffee rewards create overlapping demand. A merchant needs to know what is due, what may be claimed, which coffees are short, and what action is possible before the next cutoff. This is part of the coffee-selling product, not an optional analytics chart.

Coffee Kit plans sellable coffee and customer promises. It does not schedule roasting, purchase green beans, estimate roasting yield or run a warehouse. Shopify and the merchant's existing systems remain the sources of physical stock. The merchant supplies any future replenishment assumption; it must not masquerade as currently available stock.

Demand classes must stay visible

The board must filter by horizon, fulfillment location, offer, coffee and physical variant. Display source timestamps and missing provider data. A stale or inaccessible feed produces unknown, not a reassuring zero.

Example calculation

Start with 100 available bags. Subtract 60 due, unbilled subscription bags and a 10-bag planning buffer: 30 bags of planning headroom before reward scenarios. Shopify available excludes committed and unavailable inventory; do not subtract either again. A buffer already withheld in Shopify must not be deducted a second time. Shopify inventory states.

Suppose eight physical rewards are already issued and twelve customers are one purchase away. A merchant-selected scenario of 50% redemption for issued rewards and 25% combined earn-and-redeem for the near-threshold group implies 4 + 3 = 7 additional bags, leaving 23. These percentages are illustrations, not trained predictions. Show the full twenty-bag potential as a stress scenario too, leaving ten. Rounding and units must be explicit; use conservative whole-unit rounding when translating a fractional scenario into a planning allowance.

Do not present a confidence interval without a calibrated model. Start with counts and editable scenarios. With sufficient merchant history, a later model can estimate time to next eligible purchase and redemption by cohort, season and promotion. Compare predicted and actual demand on held-out periods; show calibration, forecast error, data age and a manual fallback. AI-generated certainty is not a substitute for those measurements.

Neither 23 nor 30 is a stock reservation. A new-enrollment limit based on expected redemption may be too permissive; any hard cap needs a merchant-approved protection policy and enforceable concurrency handling. Fifteen two-bag first deliveries is a planning upper bound before rewards in this example, not a capacity guarantee for ongoing subscriptions.

Merchant interface

The overview shows: due deliveries, unallocated bags, issued free-bag rewards, customers near a reward, projected shortages, unresolved actions and the oldest source update. Counts link to their component rows. No ambiguous “demand” total mixing people, bags, orders and money.

The coffee table shows available stock, scheduled unbilled demand, physical reward exposure, forecast assumptions, buffer and remaining headroom. A detail drawer explains every subtraction and links the affected offer/cycles. A timeline aligns choice deadlines, billing times and fulfillment dates; these are separate dates, in the merchant's timezone.

Provide scenario controls for a stock drop, a stronger reward response, a delayed replenishment and a missing provider response. Offer actions with their exact effects:

• Review new enrollment: proposed stop or later-start rule for the identified offer. Existing contracts remain separately managed.
• Review upcoming deliveries: affected cycles and provider-supported delay/skip/change options.
• Choose eligible replacements: category, size, grind, price and consent checks before a physical mapping changes.
• Review reward availability: protect existing entitlements, identify alternatives or defer redemption under disclosed terms; do not erase earned rewards when stock reaches zero.
• Preview alert: audience, deadline, shortage, data age and deep link to the actionable review.

A dry-run forecast is “Planning”; a requested provider action is “Pending”; only verified read-back becomes “Confirmed.” An unavailable control must explain which integration capability is missing.

Backend flow

1. Ingest authoritative changes. Shopify inventory/order/refund/cancellation events, provider cycle/selection/payment changes and loyalty earn/redeem/reversal events enter a deduplicated inbox. Verify signatures and tenant identity. Store source IDs, revisions and observed time.
2. Normalize without losing ownership. Resolve product variants, locations, physical units, contract cycles, reward program versions and stable customer identities. Keep unmapped demand visible as an exception. Never infer a shared grind/size stock pool from a title.
3. Reconcile a snapshot. Read back relevant sources when events arrive out of order or a reconciliation interval expires. Link order creation to its originating cycle or reward so it moves between demand classes once. Retain the event history.
4. Calculate by horizon. Produce deterministic scheduled demand, known reward exposure and separately named scenarios. Preserve category-level obligations for clubs whose physical coffee is not assigned. Exclude confirmed skipped/cancelled cycles, handle unpaid retries according to the validated policy, and expose ambiguous cases.
5. Raise actionable exceptions. Compare the forecast with merchant thresholds, cutoffs and freshness rules. Create one incident per shop/stock pool/horizon/rule; update it when the risk materially changes rather than flooding notifications.
6. Approve an operation. Recheck inventory, current contract revision, customer permission and provider capability. Record intended changes and a stable operation ID before writing. Forecast jobs must never directly charge a customer.
7. Apply and verify. Use the chosen engine's supported operation. Timeout means unknown until reconciliation, not permission to blindly repeat. Confirm scheduler/skip state separately from contract line editing. Update the board and incident only after read-back.
8. Observe the outcome. Match the actual order, stock effect, customer notification and reward event. Alert on divergence and keep a human-owned exception queue.

Shopify's inventory-management model exposes multiple inventory states; changing stock is a separate integration responsibility from forecasting it. No reservation API or provider scheduler behavior has been selected or proven for Coffee Kit. Scope and test any stock-holding mechanism as its own feature. Shopify inventory app model.

Proposed records

Cross-shop isolation, least-privilege credentials, audit history and deterministic arithmetic are mandatory. Prediction data and customer balances are private, distinct from public coffee metafields. Exportable merchant coffee facts do not imply publishing customer-level demand.

Alerts and messages

Separate internal operational alerts from customer communications and marketing. A merchant may need an urgent stock exception even when a customer has not consented to marketing. A promotional “one coffee away” nudge must use the marketing provider's consent, suppression and eligibility rules. A genuine delivery change follows the selected transactional communication route.

Internal shortage example: “Brazil Serra 250 g: 12 bags available; 18 due before Friday; 6-bag gap before reward claims. Four deliveries affected. Inventory checked 09:42; provider schedule checked 09:41. Review selection by Thursday 12:00.” The counts must be derived, not AI-written guesses. The demo only previews this message.

Reward exposure example: “Eight free-bag rewards remain unredeemed; twelve customers are one purchase away. Review reward stock before the next promotion.” Include the time window and assumptions. An alert about potential rewards must not claim that all twenty customers will redeem tomorrow.

Start with an in-app queue and a configurable internal email digest, plus urgent threshold transitions. Slack or another team webhook is an optional integration, not part of assumed base pricing. Use an outbox, deduplication, retry policy, delivery status and escalation owner. Acknowledgment stops repeated reminders, not the underlying stock check. Resolved then re-opened incidents need a clear history.

Acceptance cases

1. An order generated from a due cycle reduces Shopify available and removes that cycle from unbilled demand exactly once.
2. An ordinary/POS order between planning and action invalidates outdated capacity and prompts a fresh check.
3. A provider feed outage marks counts incomplete; automatic enrollment changes stop until policy allows safe recovery.
4. A box with a missing component cannot be counted as fully fulfillable from aggregate bag totals.
5. Decaf, grind, size and location constraints survive allocation and substitution.
6. An issued physical reward appears once; a monetary voucher is not converted into a fictional bag quantity.
7. A customer crossing a threshold moves between cohorts; their issued reward is not also counted as a new near-threshold reward for the same earn event.
8. Duplicate refunds/earnings cannot create or erase extra reward exposure; refund after redemption creates the documented exception.
9. Payment retry, cancellation, customer edit and billing-in-progress races do not produce duplicate orders or silent entitlement loss.
10. A requested enrollment stop, skip or hold is pending until verified; an unknown timeout does not display success.
11. Prepaid scheduled fulfillment and future replenishment are not treated as stock reserved for every future cycle.
12. A repeated threshold breach creates an updated incident, not repeated emails for the same unchanged fact.

Delivery order

Merchant discovery → read-only scheduled-demand and reward counts → shadow scenarios and alerts → assisted allocation → narrowly validated automation. The first useful product may be visibility and timely review; automatic capacity promises require more work. Estimate this separately from the six shopper layouts, the loyalty ledger and the subscription engine. The current site is a reviewable demonstration of this proposed workflow.

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