Demonstration — Kibble & Co. is a fictional merchant. An independent demonstration by Nino Chavez of a scoping method — not a BigCommerce product, and not a real procurement.

3. User Journeys

Kibble & Co. is a fictional mid-market pet-supply retailer used throughout this package to demonstrate a scoping method against a live BigCommerce storefront. Nothing below describes a real merchant, a real engagement, or a real bid.

The journeys below are behavioral requirements, not illustrations — each step is something the build must do. Every step traces to a domain in the companion work-breakdown (07-work-breakdown.md); the domain tags below anchor traceability without reproducing story-level detail. Where a journey names a specific BigCommerce platform capability (the BigCommerce Payments API, a Stripe-based processor adapter, B2B Edition company accounts), that capability is cited from BigCommerce's own developer documentation — the build integrates against it, it does not reimplement it. 05-platform-integration-contract.md carries the full integration contract.

3.1 Merchant journeys

(a) Onboard & configure

Trigger: Kibble & Co. decides to enable subscriptions on its BigCommerce store.

  1. Merchant → enables Subscriptions for the store from the BigCommerce control panel (native functionality — no marketplace install; see 05-platform-integration-contract.md §5.2.10) → system provisions a store record, registers the merchant-facing configuration panels on the Products, Orders, and Customers pages, and wires up the platform events the capability depends on (order created/updated, customer updated, product updated/deleted).
  2. Merchant → opens payment processor setup → system detects whether BigCommerce Payments is already enabled on the store and, if so, auto-registers it as the connected processor; if not, the merchant connects a Stripe account as the alternate processor.
  3. Merchant → opens a product's configuration panel in the BigCommerce control panel — a 30-lb bag of salmon-formula dog food, say → system shows the product's current plan status (none / draft / active) and, if none exists, offers to configure one.
  4. Merchant → completes the plan-configuration wizard: choosing offered interval(s) (feeding cadence varies by pet size and household, so a merchant might offer 4-, 6-, and 8-week intervals on the same product), a pricing strategy (a fixed discount, a linked BigCommerce Price List, or a fixed price), eligible variants (bag size, flavor), and optional trial/commitment terms → system saves the plan and, on activation, exposes the storefront subscribe option for that product.

Outcome: The product is subscribable; the storefront widget renders the subscribe option to shoppers within the platform's cache-propagation window, with no SKU duplication in the catalog.

Traces to: Onboarding, Catalog

(b) Operate

Trigger: Kibble & Co.'s recurring check-in on subscription business health.

  1. Merchant → opens the dashboard in the merchant admin surface → system shows recurring-revenue and active-subscriber tiles, upcoming-charge value across a near-term and medium-term horizon (illustrative windows for this demonstration — the actual horizons are a configuration choice, not a fixed requirement), and a count of items needing attention.
  2. Merchant → opens the exception queue → system presents a prioritized list of subscriptions needing attention — failed-charge dunning, out-of-stock renewals (a formula reformulation or a vendor stockout on a specific SKU), reconciliation drift — each carrying a proposed remediation.
  3. Merchant → resolves or escalates an exception item → system logs the resolution against the subscription's event history and removes the item from the queue.
  4. Merchant → reviews subscriptions currently mid-dunning → system shows the retry stage reached, the next retry time, and — where retries have exhausted — the resulting subscription status.

Outcome: The merchant has one screen answering "what's working and what needs attention" without querying orders, customers, or payment data directly.

Traces to: Operations, Billing

(c) Support intervention

Trigger: A subscriber contacts support, or support proactively identifies a billing issue.

  1. Support rep → looks up the customer from the exception queue or the subscription list → system surfaces the customer's subscription(s), charge history, and event timeline.
  2. Support rep → issues a full or partial refund against a past charge, with a reason (a duplicate charge on a monthly treats box, for example) → system routes the refund through the connected processor and updates the linked BigCommerce order's status.
  3. Support rep → creates a subscription manually for a phone order, a recovered cart, or a comped account — a customer who called in to set up a senior dog's joint-supplement subscription, say — selecting customer, plan, payment method, and start date → system creates the subscription with an event marking its manual origin.
  4. Support rep → force-triggers an out-of-cycle charge on a subscription, or attaches a manual note → system executes the charge through the normal processor path and records the note against the subscription.

Outcome: Support resolves billing issues without direct data access; every manual action is captured in the subscription's audit trail.

Traces to: Billing, Operations

(d) Migrate from an incumbent subscription app

Trigger: Kibble & Co. currently runs subscriptions through an incumbent subscription application and decides to switch.

  1. Merchant → selects their current provider and uploads its export file (or, where an authoritative API path exists, connects directly) → system validates each row against the target schema and reports pass/fail counts with reason codes for failures.
  2. Merchant → reviews payment-instrument migration status → system reports which subscribers' stored cards were successfully carried over via the processor's own account-data migration process, and which subscribers will need to re-add a payment method.
  3. Merchant → runs a dry-run simulation before committing → system reports subscriptions to be created, instruments successfully mapped, estimated recurring revenue migrated, and revenue at risk from any unmapped instruments — including the lead time the payment-instrument migration step requires before activation.
  4. Merchant → commits the migration → system creates each subscription, preserving the subscriber's existing next-charge date exactly (so a customer's senior-dog food delivery isn't double-charged or skips a cycle), and places any subscription with no mapped payment instrument into a paused-pending-payment-method state with an automatic email prompting the subscriber to add one.

Outcome: Subscribers move to the new platform without being asked to re-enter payment details, except where the incumbent provider's stored tokens are not portable to the new processor.

Traces to: Onboarding

3.2 Shopper journeys

(a) Discover & subscribe

Trigger: A shopper lands on the product page of a subscribable product — a 15-lb bag of grain-free chicken formula, say.

  1. Shopper → views the product page → system renders a purchase widget offering a "one-time purchase" versus "subscribe & save" choice, an interval selector where more than one interval is offered, and a preview of the next charge date and amount.
  2. Shopper → selects the subscription option and interval → system discloses the recurring terms — amount, billing frequency, when the first and subsequent charges occur, and how to cancel — adjacent to an explicit, not-pre-checked consent control; the purchase cannot proceed without that affirmative consent (this is a negative-option-law requirement, not a UX nicety, and it must be non-removable even where the disclosure copy itself is merchant-themeable).
  3. Shopper → gives consent and adds the item to cart → system records the subscription intent (plan, interval, quantity) against the cart, along with the disclosed terms and a timestamped consent record.
  4. Shopper → completes checkout through the standard BigCommerce checkout — no separate subscription-specific checkout exists → system reads the recorded subscription intent once the order is created and creates the subscription record, linked to that originating order.
  5. Shopper → lands on the order confirmation page → the subscription's first charge is already recorded as succeeded (it is the checkout payment itself), and the subscription is visible to the shopper immediately after purchase.

Outcome: A shopper converts to a subscriber using BigCommerce's own checkout, with a persisted, legally sufficient record of consent to the recurring terms; subscription and one-time items — a subscribed bag of food alongside a one-time toy purchase — can coexist in the same cart and order.

Traces to: Purchase

(b) Post-purchase activation

Trigger: Immediately following a successful subscription order.

  1. Shopper → returns to the storefront, or follows a link from a welcome notification → system offers portal access without requiring the creation of a new password.
  2. Shopper → requests portal access by entering their email → system emails a time-limited, single-use sign-in link.
  3. Shopper → follows the link within its validity window → system authenticates the shopper into a portal scoped to their own subscriptions only; an expired or already-used link routes to a "request a new link" state rather than a dead end.

Outcome: The subscriber gains self-service portal access with no separate account or password to manage.

Traces to: Self-Service

(c) Self-service lifecycle

Trigger: A subscriber wants to change or stop an upcoming charge without contacting support.

  1. Subscriber → opens a subscription in the portal → system shows current status, next charge date and amount, and the lifecycle actions available for that status.
  2. Subscriber → skips the next charge — they still have half a bag left → system marks the upcoming charge abandoned and advances the next-charge date by one interval; the skip stays reversible for a defined window before the original charge date.
  3. Subscriber → swaps the subscribed product or variant — moving a dog from adult formula to senior formula, or sizing up the bag → system shows the new estimated charge amount for confirmation before applying the change, effective the next cycle.
  4. Subscriber → pauses the subscription for a chosen duration, or indefinitely — a two-week boarding stay, or an extended trip where a pet sitter is stocked separately → system halts all charges until the chosen resume date, or until the subscriber manually resumes.
  5. Subscriber → reschedules the next charge to a different date within the allowed window → system shifts all subsequent charges to match.
  6. Subscriber → initiates cancellation from the same portal medium they subscribed through → system first routes through the churn-save intervention path below; if the subscriber proceeds past it, cancellation completes within the same session — no mandatory phone call, no forced multi-day processing delay, and the intervention offers cannot loop or gate the cancel once the subscriber declines them — and the subscription transitions to cancelled with the stated reason logged and a confirmation sent.

Outcome: The subscriber resolves the highest-volume support-ticket categories — skip, swap, pause, reschedule, cancel — entirely inside the portal, and cancellation is never harder than sign-up was (a same-medium, non-obstructed cancel path is itself a negative-option-law requirement, not a discretionary UX choice).

Traces to: Self-Service

(d) Payment method & address update

Trigger: A subscriber's card is expiring or was declined, or they have moved.

  1. Subscriber → opens "update payment method" on a subscription → system presents the subscriber's saved BigCommerce Payments vaulted cards, or a Stripe-hosted card-entry element for stores on the Stripe adapter — raw card data never passes through the platform's own systems in either path.
  2. Subscriber → selects or adds a payment instrument → system points the subscription at the new instrument and, if the subscription was in a failed-payment state, immediately resets the retry counter and re-attempts the failed charge.
  3. Subscriber → updates their shipping address → system recalculates tax and shipping against the new address starting at the next renewal.

Outcome: Renewal failures caused by stale payment or address data self-resolve without a support ticket.

Traces to: Self-Service, Billing

(e) Churn-save

Trigger: A subscriber initiates cancellation from the portal.

  1. Subscriber → clicks cancel → system asks why first, presenting a merchant-configured reason list ("too expensive," "my pet's dietary needs changed," "I'm falling behind on the bags I already have," "switched to a different brand," "my pet passed away") plus an "other" option.
  2. Subscriber → selects a reason → system offers a matched intervention: a pause option for "falling behind," a merchant-configured discount for "too expensive," a formula-swap prompt or support escalation for "dietary needs changed." For "my pet passed away," the system skips the intervention step entirely — no discount offer, no pause prompt — and moves straight to a compassionate acknowledgment and cancellation, because a retention offer at that moment is the wrong instinct even when it's technically available.
  3. Subscriber → accepts the offered intervention → system applies it (pause, discount, or cadence change) and the cancellation flow ends without cancelling the subscription.
  4. Subscriber → declines every intervention and confirms, or was routed straight to cancellation → system cancels the subscription and logs the captured reason for merchant reporting.

Outcome: Preventable cancellations are addressed before they complete, and the one class of cancellation that isn't preventable is never treated as a sales opportunity; every cancellation, prevented or completed, carries an attributed reason.

Traces to: Self-Service

3.3 System journeys

(a) Renewal cycle

Trigger: A subscription's next-charge date arrives.

  1. System → the scheduler scans for charges due within the next processing window and enqueues each for execution; a charge already in progress is never re-enqueued.
  2. System → the executor acquires an exclusive lock on the charge, then loads the subscription, its plan, and its connected processor.
  3. System → checks current inventory for the subscribed variant → per the merchant's configured backorder policy, proceeds, abandons the cycle, substitutes a configured alternate SKU (two 8-lb bags in place of one 15-lb bag, if the merchant has mapped that substitution), or pauses the subscription.
  4. System → recalculates price (per the plan's pricing strategy, unless the subscriber's price was locked at signup), tax (against the subscriber's current address), and shipping (against current shipping rules and address) to arrive at the final charge amount.
  5. System → dispatches the charge to the connected processor (BigCommerce Payments or Stripe) against the subscription's stored payment instrument, using an idempotency key tied to the charge so a retried attempt can never double-charge.
  6. System → on a successful charge, creates a native BigCommerce order carrying the subscriber's current billing/shipping details and tagged with the subscription's identifying metadata → the merchant's existing fulfillment operations process it exactly like any other order, with no parallel system to reconcile.
  7. System → schedules the next charge from the subscription's original anchor date, not from this charge's completion time, so cadence never drifts across cycles, and sends the subscriber a renewal confirmation.
  8. System → where the subscription instead carries a defined term-end — a prepaid cycle-count exhaustion (a 12-box treat-of-the-month program purchased upfront) or a negotiated B2B supply term (see §3.4) — rather than an open-ended cadence → the standard step-5 charge above does not apply at term-end; instead the system sends a distinct "renew your subscription" nudge ahead of the term-end date and requires an explicit re-up confirmation before extending the term, unless the merchant has configured silent auto-renewal for that plan.

Outcome: A renewal order is indistinguishable, on the merchant's fulfillment side, from a normal storefront order; a retried or restarted execution never produces a duplicate order or a duplicate processor charge; and a subscriber under a fixed-term commitment is never auto-renewed into a new term without the disclosure the term itself requires.

Traces to: Billing, Orders, Platform

(b) Decline & dunning recovery

Trigger: A renewal charge is declined by the connected payment processor.

  1. System → classifies the decline as soft (retriable) or hard (not retriable) → a hard decline moves directly to the merchant-configured exhaustion action; a soft decline schedules a retry per the merchant's configured policy (retry intervals and total attempts).
  2. System → notifies the subscriber of the failed charge, including a direct link to update their payment method.
  3. Subscriber → updates their payment method before the next scheduled retry → system immediately resets the retry counter and re-attempts the charge.
  4. System → once every configured retry is exhausted without a successful charge → applies the merchant's configured exhaustion policy (cancel, pause, or leave active with no further automated action) and sends a final notification to the subscriber.

Outcome: Transient payment failures — an expired card on file, a bank's fraud hold — recover without merchant intervention; subscriptions that exhaust every retry land in a predictable, merchant-chosen end state rather than an indefinite retry loop.

Traces to: Billing

3.4 B2B journey

Scoped strictly to what the written requirements support. Note the phase boundary: the B2B domain is tagged P3 in the companion work-breakdown (08-scope-boundary-and-engagement-model.md §8.3), so this journey defines the target behavior for a separately priced B2B option, not the initial fixed-scope build. Within that option, B2B enrollment is an assisted flow through the merchant admin surface, not a fully self-service storefront sign-up.

Trigger: A company-account buyer on a BigCommerce B2B Edition–enabled store — a veterinary clinic's office manager, a boarding kennel, a groomer restocking consumables — needs a subscription set up on behalf of their organization.

  1. Merchant admin (or, on the storefront path, a company buyer at checkout) → enrolls a company account into a subscription for recurring bulk supply (prescription diet cases, grooming consumables, cleaning supplies) → system associates the resulting subscription with the company account rather than the individual buyer, so any authorized company user can see it.
  2. Company user, any authorized role → opens the subscriber portal → system shows the subscriptions belonging to the company, not only the ones a single buyer personally created.
  3. A buyer with restricted permissions → attempts a self-service change (pause, cancel, quantity) → system either blocks the action with an explanation, or — where an approval workflow is enabled — routes the requested change to the company's designated approver as a pending item.
  4. Approver → reviews the pending change → approves it, and the system applies the change immediately, or rejects it with a reason, and the system discards the change and notifies the requesting buyer.
  5. Company → settles renewals under agreed purchase-order terms rather than a card on file → system generates the renewal's BigCommerce order with a pending-payment status for manual reconciliation against the purchase order, rather than attempting an automatic card charge.

Outcome: Company accounts get subscription visibility and change controls that match how the organization actually authorizes purchasing, without assuming individual-buyer semantics carry over unmodified from the consumer journeys above.

Traces to: Platform

Kibble & Co. is a fictional demo merchant. This package is an independent demonstration by Nino Chavez of a scoping method — not a BigCommerce product, and not a real procurement.