CODITECT Checkout Process - Complete End-to-End Flow

Version: 1.0.0 Last Updated: December 29, 2025 Purpose: Comprehensive documentation of the complete checkout process from pricing page to product access

---

Table of Contents

1. Executive Summary
2. User Journey Overview
3. Phase 1: Product Discovery
4. Phase 2: Shopping Cart
5. Phase 3: Checkout Initiation
6. Phase 4: Payment Processing
7. Phase 5: Order Fulfillment
8. Phase 6: Entitlement Provisioning
9. Post-Purchase Workflows
10. API Reference
11. Sequence Diagrams
12. Error Handling
13. Related Documents

---

1. Executive Summary

The CODITECT checkout process enables users to purchase multiple products through a unified shopping cart experience with dual payment method support (Google Pay + Stripe). The complete flow spans from product discovery to fully provisioned entitlements.

Key Workflows Involved

Workflow	Purpose	Duration
WF-001	User Registration	2-5s
WF-002	Subscription Checkout (Stripe redirect)	3-8s
WF-003	Stripe Webhook Handler	1-3s
WF-004	Workstation Provisioning	30-120s
Commerce Workflows 1-14	Product catalog, cart, checkout, entitlements	varies

CODITECT Product Catalog

Product	Slug	Type	Price	Requires	Provisions
CODITECT Core	core	base	$49/mo	-	GCP Workstation + coditect-core
CODITECT DMS	dms	addon	$29/mo	core	dms.coditect.ai access
Workflow Analyzer	workflow	addon	$19/mo	core	workflow.coditect.ai access
Enterprise Bundle	enterprise	bundle	$149/mo	-	All products + priority support

---

2. User Journey Overview

┌─────────────────────────────────────────────────────────────────────────────┐
│                         CODITECT CHECKOUT JOURNEY                            │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                              │
│  ┌──────────┐    ┌──────────┐    ┌──────────┐    ┌──────────┐    ┌────────┐│
│  │ PRICING  │───▶│ CART     │───▶│ CHECKOUT │───▶│ PAYMENT  │───▶│ ACCESS ││
│  │ /pricing │    │ /cart    │    │ /checkout│    │ Stripe/  │    │ /dash  ││
│  └──────────┘    └──────────┘    └──────────┘    │ G-Pay    │    └────────┘│
│       │              │              │            └──────────┘        │      │
│       ▼              ▼              ▼                 │              ▼      │
│  Browse         Add items      Validate cart    Process         Provision   │
│  products       Check deps     Create session   payment         entitlements│
│                                                                              │
│  Duration: ~2s      ~1-3s          ~2-5s          ~3-30s         ~30s-5min  │
└─────────────────────────────────────────────────────────────────────────────┘

Complete Flow States

User arrives at /pricing
        │
        ▼
[1] Browse Products ──────── GET /api/v1/products
        │
        ▼
[2] View Product Details ─── GET /api/v1/products/{slug}
        │
        ▼
[3] Add to Cart ──────────── POST /api/v1/cart/items
        │                         │
        │    ◄────────────────────┘ (dependency validation)
        │
        ▼
[4] View Cart ────────────── GET /api/v1/cart
        │
        ▼
[5] Initiate Checkout ────── POST /api/v1/checkout
        │
        ├─────────────────────┬───────────────────────┐
        ▼                     ▼                       ▼
[6a] Google Pay         [6b] Stripe Redirect    [6c] Cancel
     One-tap                  /checkout/stripe        │
        │                          │                  │
        ▼                          ▼                  ▼
[7] Payment Processed      User on Stripe.com    Return to cart
        │                          │
        │    ◄─────────────────────┘ (webhook callback)
        ▼
[8] Order Created ────────── Stripe webhook: checkout.session.completed
        │
        ▼
[9] Provision Entitlements ─ POST /api/v1/entitlements (internal)
        │
        ├─── If Core purchased ──▶ Provision GCP Workstation (WF-004)
        │
        ├─── If DMS purchased ───▶ Enable dms.coditect.ai
        │
        └─── If Workflow ────────▶ Enable workflow.coditect.ai
        │
        ▼
[10] Success Page ────────── GET /checkout/success?session_id={id}
        │
        ▼
[11] User Dashboard ──────── Full product access granted

---

3. Phase 1: Product Discovery

3.1 Product Catalog Browse (Workflow #1)

Trigger: User visits /pricing Duration: 1-2 seconds

Steps:

1. Frontend loads ProductCatalog component
2. GET /api/v1/products fetches all available products
3. Backend filters by availability and user eligibility
4. Calculates display prices (applies promotions if any)
5. Renders ProductCard grid with pricing comparison

API Request:

GET /api/v1/products
Authorization: Bearer {jwt_token}  (optional for guest)

Response 200:
{
  "products": [
    {
      "id": "uuid",
      "slug": "core",
      "name": "CODITECT Core",
      "description": "Full cloud development workstation",
      "type": "base",
      "price_cents": 4900,
      "stripe_price_id": "price_xxx",
      "requires": [],
      "provisions": ["GCP Workstation", "coditect-core framework"]
    },
    {
      "id": "uuid",
      "slug": "dms",
      "name": "CODITECT DMS",
      "description": "Document Management System",
      "type": "addon",
      "price_cents": 2900,
      "stripe_price_id": "price_yyy",
      "requires": ["core"],
      "subdomain": "dms.coditect.ai"
    }
  ]
}

3.2 Product Details View (Workflow #2)

Trigger: User clicks product card or navigates to /products/{slug} Duration: 1-2 seconds

Steps:

1. GET /api/v1/products/{slug} fetches full product details
2. Load product requirements (dependencies)
3. Load recommended add-ons
4. Check if user already owns this product
5. Render full product page with "Add to Cart" CTA

---

4. Phase 2: Shopping Cart

4.1 Add Item to Cart (Workflow #3)

Trigger: User clicks "Add to Cart" Duration: 1-3 seconds

Critical Logic - Dependency Validation:

IF adding "dms" or "workflow" addon:
    IF "core" NOT in cart AND user does NOT own "core":
        SHOW: "This product requires CODITECT Core"
        OPTION: "Add Core + DMS to Cart" (auto-add dependency)
    ELSE:
        Add item normally

API Request:

POST /api/v1/cart/items
Authorization: Bearer {jwt_token}
Content-Type: application/json

{
  "product_slug": "dms"
}

Response 200:
{
  "cart_id": "cart-uuid",
  "items": [
    {"product_slug": "core", "price_cents": 4900},
    {"product_slug": "dms", "price_cents": 2900}
  ],
  "total_cents": 7800,
  "expires_at": "2025-12-30T12:00:00Z"
}

Response 400 (missing dependency):
{
  "error": "dependency_required",
  "message": "CODITECT DMS requires CODITECT Core",
  "required_product": "core"
}

4.2 Cart Storage Architecture

┌─────────────────────────────────────────────────────┐
│                    CART LAYER                        │
├─────────────────────────────────────────────────────┤
│                                                      │
│   ┌──────────────┐        ┌──────────────┐          │
│   │    Redis     │◄──────▶│  PostgreSQL  │          │
│   │  (Hot Cache) │        │  (Durable)   │          │
│   └──────────────┘        └──────────────┘          │
│         │                        │                   │
│    5 min TTL              24 hour expiry            │
│    Fast access            Backup/recovery           │
│                                                      │
└─────────────────────────────────────────────────────┘

Cart Table Schema:

CREATE TABLE carts (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    user_id UUID REFERENCES users(id),
    session_id VARCHAR(255),  -- For guest carts
    items JSONB NOT NULL DEFAULT '[]',
    total_cents INTEGER NOT NULL DEFAULT 0,
    status VARCHAR(50) DEFAULT 'active',
    created_at TIMESTAMP DEFAULT NOW(),
    updated_at TIMESTAMP DEFAULT NOW(),
    expires_at TIMESTAMP DEFAULT NOW() + INTERVAL '24 hours'
);

4.3 Remove Item from Cart (Workflow #4)

Critical Logic - Cascade Removal:

IF removing "core":
    IF cart contains "dms" or "workflow":
        SHOW: "Removing Core will also remove DMS/Workflow"
        REQUIRE: User confirmation
        THEN: Remove all dependent items

4.4 View Cart (Workflow #5)

Trigger: User clicks cart icon or navigates to /cart Duration: 1-2 seconds

UI Components:

• ShoppingCart sidebar (slide-in)
• CartItem rows with remove button
• CartSummary with total
• Google Pay button (if available)
• "Pay with Card" button (Stripe fallback)

---

5. Phase 3: Checkout Initiation

5.1 Initiate Checkout (Workflow #7)

Trigger: User clicks "Checkout" button Duration: 2-5 seconds

Pre-Checkout Validation:

1. Verify cart is not empty
2. Verify cart has not expired
3. Verify all products still available
4. Verify user is authenticated (redirect to login if not)
5. Final dependency check
6. Lock cart (set status to checkout_pending)

API Request:

POST /api/v1/checkout
Authorization: Bearer {jwt_token}
Content-Type: application/json

{}

Response 200:
{
  "checkout_session_id": "cs_xxx",
  "payment_options": {
    "google_pay_available": true,
    "stripe_checkout_url": "https://checkout.stripe.com/c/pay/cs_xxx"
  },
  "expires_at": "2025-12-29T13:00:00Z"
}

---

6. Phase 4: Payment Processing

6.1 Option A: Google Pay One-Tap (Workflow #8)

Flow:

User taps Google Pay button
        │
        ▼
Payment Request API opens ──── Browser native UI
        │
        ▼
User authenticates ────────── Face ID / Fingerprint / PIN
        │
        ▼
Payment token received ─────── Encrypted by Google
        │
        ▼
POST /api/v1/checkout/google-pay
        │
        ▼
Backend creates Stripe PaymentIntent with Google Pay source
        │
        ▼
Stripe charges payment method
        │
        ▼
On success: Create order, provision entitlements
        │
        ▼
Redirect to /checkout/success

API Request:

POST /api/v1/checkout/google-pay
Authorization: Bearer {jwt_token}
Content-Type: application/json

{
  "checkout_session_id": "cs_xxx",
  "payment_token": {
    "signature": "MEUCIQDHmP...",
    "protocolVersion": "ECv2",
    "signedMessage": "..."
  }
}

Response 200:
{
  "success": true,
  "order_id": "order-uuid",
  "redirect_url": "/checkout/success?order_id=xxx"
}

6.2 Option B: Stripe Checkout Redirect (Workflow #9)

Flow (WF-002 Subscription Checkout):

User clicks "Pay with Card"
        │
        ▼
POST /api/v1/checkout creates Stripe Checkout Session
        │
        ├── line_items: [{price: 'price_xxx', quantity: 1}, ...]
        ├── success_url: /checkout/success?session_id={CHECKOUT_SESSION_ID}
        ├── cancel_url: /cart
        └── metadata: {user_id, org_id, cart_id}
        │
        ▼
Browser redirects to checkout.stripe.com
        │
        ▼
User enters card details on Stripe-hosted page
        │
        ├── Card number, expiry, CVC
        ├── Billing address (if required)
        └── 3D Secure authentication (if required)
        │
        ▼
Stripe processes payment
        │
        ├── On success: Webhook to /api/v1/webH.P.005-HOOKS/stripe
        └── On failure: User sees error, can retry
        │
        ▼
User redirected to /checkout/success?session_id=xxx

6.3 Stripe Webhook Handler (WF-003)

Trigger: POST from Stripe to /api/v1/webH.P.005-HOOKS/stripe Duration: 1-3 seconds

Step-by-Step:

1. Verify signature - Validate Stripe-Signature header
2. Parse event - Extract event type and data
3. Route by type:

checkout.session.completed ────▶ [A] Create order, provision entitlements
invoice.paid ──────────────────▶ [B] Extend subscription period
invoice.payment_failed ────────▶ [C] Start dunning (WF-025)
customer.subscription.deleted ─▶ [D] Revoke entitlements (WF-008)
charge.refunded ───────────────▶ [E] Revoke entitlements

Route A: Checkout Session Completed

Extract metadata: {user_id, org_id, cart_id}
        │
        ▼
Update organization subscription ───▶ PostgreSQL
        │
        ├── subscription_tier = purchased tier
        ├── subscription_status = 'active'
        ├── stripe_subscription_id = sub_xxx
        └── subscription_started_at = NOW()
        │
        ▼
Publish provisioning event ─────────▶ Pub/Sub: workstation-provisioning-requests
        │
        ▼
Send confirmation email ────────────▶ "Payment confirmed, workstation creating..."
        │
        ▼
Return 200 to Stripe

---

7. Phase 5: Order Fulfillment

7.1 Create Order Record

Order Table Schema:

CREATE TABLE orders (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    user_id UUID NOT NULL REFERENCES users(id),
    org_id UUID NOT NULL REFERENCES organizations(id),
    stripe_payment_intent_id VARCHAR(255) UNIQUE,
    stripe_checkout_session_id VARCHAR(255) UNIQUE,
    line_items JSONB NOT NULL,
    subtotal_cents INTEGER NOT NULL,
    tax_cents INTEGER DEFAULT 0,
    total_cents INTEGER NOT NULL,
    currency VARCHAR(3) DEFAULT 'USD',
    status VARCHAR(50) DEFAULT 'completed',
    created_at TIMESTAMP DEFAULT NOW()
);

Order Line Items Example:

{
  "line_items": [
    {
      "product_id": "uuid",
      "product_slug": "core",
      "product_name": "CODITECT Core",
      "quantity": 1,
      "unit_price_cents": 4900,
      "subtotal_cents": 4900
    },
    {
      "product_id": "uuid",
      "product_slug": "dms",
      "product_name": "CODITECT DMS",
      "quantity": 1,
      "unit_price_cents": 2900,
      "subtotal_cents": 2900
    }
  ]
}

7.2 Success Page (Workflow #10)

Trigger: User redirected to /checkout/success?session_id={id} Duration: 2-3 seconds

Steps:

1. Verify session_id is valid and completed
2. Retrieve order by stripe_payment_intent_id
3. Load newly granted entitlements
4. Display order confirmation with:
   • Products purchased
   • Total amount charged
   • Receipt link (Stripe hosted)
   • "Go to Dashboard" CTA
5. Send order confirmation email
6. Track conversion event for analytics

---

8. Phase 6: Entitlement Provisioning

8.1 Entitlement Provision (Workflow #11)

Trigger: Successful payment completion Duration: 30 seconds to 5 minutes (depending on products)

Entitlement Table Schema:

CREATE TABLE entitlements (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    user_id UUID NOT NULL REFERENCES users(id),
    org_id UUID NOT NULL REFERENCES organizations(id),
    product_id UUID NOT NULL REFERENCES products(id),
    product_slug VARCHAR(50) NOT NULL,
    status VARCHAR(50) DEFAULT 'active',
    source VARCHAR(50) DEFAULT 'purchase',  -- purchase, trial, admin_grant
    granted_at TIMESTAMP DEFAULT NOW(),
    expires_at TIMESTAMP,  -- NULL for lifetime
    order_id UUID REFERENCES orders(id),
    stripe_subscription_id VARCHAR(255)
);

Provisioning Logic by Product:

FOR EACH line_item IN order.line_items:
        │
        ▼
    INSERT INTO entitlements (user_id, product_slug, ...)
        │
        ├── IF product_slug == 'core':
        │       │
        │       ▼
        │   Publish to Pub/Sub: workstation-provisioning-requests
        │       │
        │       ▼
        │   WF-004 picks up message
        │       │
        │       ▼
        │   Create GCP Workstation (30-120 seconds)
        │       │
        │       ├── Starter: e2-medium, 50GB
        │       ├── Professional: e2-highmem-4, 100GB
        │       ├── Business: n2-highmem-8, 200GB
        │       └── Enterprise: n2-highmem-16, 500GB
        │
        ├── IF product_slug == 'dms':
        │       │
        │       ▼
        │   Enable dms.coditect.ai for user
        │       │
        │       ▼
        │   Grant DMS-specific RBAC permissions
        │
        └── IF product_slug == 'workflow':
                │
                ▼
            Enable workflow.coditect.ai for user
                │
                ▼
            Grant Workflow Analyzer RBAC permissions

8.2 Entitlement Check (Workflow #12)

Trigger: User accesses product subdomain or feature Duration: <100ms (cached)

Check Flow:

User requests dms.coditect.ai
        │
        ▼
API Gateway middleware: EntitlementCheck
        │
        ▼
Extract user_id from JWT
        │
        ▼
CHECK Redis cache: entitlement:{user_id}:{product_slug}
        │
        ├── Cache HIT: Return cached result
        │
        └── Cache MISS:
                │
                ▼
            Query PostgreSQL:
            SELECT * FROM entitlements
            WHERE user_id = $1 AND product_slug = 'dms' AND status = 'active'
                │
                ▼
            Cache result in Redis (5 min TTL)
                │
                ▼
            Return access grant/deny

---

9. Post-Purchase Workflows

9.1 Subscription Upgrade (WF-021)

Trigger: User clicks "Upgrade" in billing settings Duration: 8-12 seconds

Proration Example:

Current: Starter ($29/mo)
New: Professional ($99/mo)
Days remaining: 15 of 30

Unused credit: ($29/30) * 15 = $14.50
New charge: ($99/30) * 15 = $49.50
Proration: $49.50 - $14.50 = $35.00 charged immediately

9.2 Payment Method Update (WF-024)

Two-Phase Flow:

1. Phase 1: Create SetupIntent, return client_secret
2. Phase 2: Frontend uses Stripe.js for card entry (PCI compliant)
3. Post-update: Automatically retry any past-due invoices

9.3 Failed Payment Retry (WF-025)

Smart Dunning Strategy:

Day 0:  Attempt 1 (immediate) + Friendly email
Day 3:  Attempt 2 + Urgent email (12 days warning)
Day 8:  Attempt 3 + Final notice (7 days warning)
Day 15: Suspend subscription, stop workstation

Recovery Rates:

• Attempt 1: 45% success (insufficient funds cleared)
• Attempt 2: 18% success (user updated payment)
• Attempt 3: 10% success (final grace)
• Total recovery: 73% before suspension

9.4 Subscription Cancellation

Flow:

1. User initiates cancellation
2. Set subscription_status = 'canceled'
3. Begin 30-day data retention period
4. Send cancellation confirmation email
5. After 30 days: WF-008 (User Offboarding) executes

---

10. API Reference

Commerce API Endpoints

Method	Endpoint	Description	Auth
GET	/api/v1/products	List all products	Optional
GET	/api/v1/products/{slug}	Get product details	Optional
POST	/api/v1/cart/items	Add product to cart	Required
GET	/api/v1/cart	Get current cart	Required
DELETE	/api/v1/cart/items/{id}	Remove from cart	Required
DELETE	/api/v1/cart	Clear cart	Required
POST	/api/v1/checkout	Initiate checkout	Required
POST	/api/v1/checkout/google-pay	Process Google Pay	Required
GET	/api/v1/checkout/success	Post-payment redirect	Required
POST	/api/v1/webH.P.005-HOOKS/stripe	Stripe webhook	Stripe Signature
GET	/api/v1/entitlements	List user entitlements	Required
GET	/api/v1/entitlements/{slug}	Check specific entitlement	Required

Response Codes

Code	Meaning	Example
200	Success	Cart updated, checkout complete
201	Created	New cart item added
400	Bad Request	Missing dependency, invalid product
401	Unauthorized	Invalid/missing JWT
402	Payment Required	Payment failed
404	Not Found	Product/cart not found
409	Conflict	Item already in cart
429	Rate Limited	Too many requests
500	Server Error	Internal error

---

11. Sequence Diagrams

Complete Checkout Sequence

┌──────┐     ┌─────────┐    ┌────────┐    ┌──────┐    ┌──────────┐
│ User │     │Frontend │    │  API   │    │Stripe│    │  Pub/Sub │
└──┬───┘     └────┬────┘    └───┬────┘    └──┬───┘    └────┬─────┘
   │              │             │            │              │
   │  Click       │             │            │              │
   │  "Checkout"  │             │            │              │
   │─────────────▶│             │            │              │
   │              │             │            │              │
   │              │ POST        │            │              │
   │              │ /checkout   │            │              │
   │              │────────────▶│            │              │
   │              │             │            │              │
   │              │             │ Create     │              │
   │              │             │ Session    │              │
   │              │             │───────────▶│              │
   │              │             │            │              │
   │              │             │ session_id │              │
   │              │             │◀───────────│              │
   │              │             │            │              │
   │              │ checkout_url│            │              │
   │              │◀────────────│            │              │
   │              │             │            │              │
   │  Redirect to │             │            │              │
   │  Stripe      │             │            │              │
   │◀─────────────│             │            │              │
   │              │             │            │              │
   │  User enters │             │            │              │
   │  card details│             │            │              │
   │─────────────────────────────────────────▶              │
   │              │             │            │              │
   │              │             │            │  webhook     │
   │              │             │            │  checkout.   │
   │              │             │            │  session.    │
   │              │             │◀───────────│  completed   │
   │              │             │            │              │
   │              │             │ Publish    │              │
   │              │             │ provision  │              │
   │              │             │ event      │              │
   │              │             │────────────────────────▶  │
   │              │             │            │              │
   │  Redirect    │             │            │              │
   │  /success    │             │            │              │
   │◀─────────────────────────────────────────              │
   │              │             │            │              │

---

12. Error Handling

Common Errors and Recovery

Error	Cause	User Message	Recovery
Cart expired	24h timeout	"Your cart has expired"	Recreate cart
Dependency missing	Adding addon without base	"DMS requires Core"	Auto-add Core
Payment declined	Insufficient funds	"Card declined"	Try another card
Product unavailable	Product discontinued	"Product no longer available"	Remove from cart
Rate limited	Too many requests	"Please wait and try again"	Exponential backoff
Webhook failure	Signature mismatch	(Silent)	Alert ops, retry

Webhook Retry Policy

Stripe automatically retries failed webH.P.005-HOOKS:

• Immediate retry
• 1 hour
• 3 hours
• 6 hours
• 12 hours
• 24 hours (then stops)

---

13. Related Documents

Architecture

• ADR-014: Commerce and Product Catalog
• SDD Section 4.2.1: Commerce Service
• TDD Sections 6.1.7-6.1.10: Commerce Schema

Workflows

• COMMERCE-CHECKOUT-WORKFLOWS.md - 14 detailed commerce H.P.006-WORKFLOWS
• WF-001: User Registration
• WF-002: Subscription Checkout
• WF-003: Stripe Webhook Handler
• WF-004: Workstation Provisioning
• WF-021: Subscription Upgrade
• WF-024: Payment Method Update
• WF-025: Failed Payment Retry

Frontend Components

src/
├── pages/
│   ├── Pricing.tsx              # Product catalog page
│   └── Checkout/
│       └── Success.tsx          # Post-payment success
├── components/
│   ├── products/
│   │   ├── ProductCatalog.tsx   # Product grid
│   │   └── ProductCard.tsx      # Individual product
│   ├── cart/
│   │   ├── ShoppingCart.tsx     # Cart sidebar
│   │   └── CartSummary.tsx      # Total + checkout
│   └── checkout/
│       ├── GooglePayButton.tsx  # Google Pay integration
│       └── StripeCheckout.tsx   # Stripe redirect
└── H.P.005-HOOKS/
    ├── useCart.ts               # Cart state management
    └── useProducts.ts           # Product fetching

---

Last Updated: December 29, 2025 Owner: CODITECT Commerce Team