Skip to main content

WF-002: Subscription Checkout Workflow

Overview​

This workflow handles subscription upgrades and new subscription purchases, integrating with Stripe for payment processing and preparing the system for workstation provisioning.

Trigger: HTTP POST to /checkout endpoint Duration: ~3-8 seconds (redirect to Stripe) Related Workflows: WF-003 (Stripe Webhook), WF-004 (Workstation Provisioning)

Prerequisites​

Before starting, ensure you have:

  • Required tools installed
  • Access to necessary resources
  • Basic understanding of concepts

Verify setup:

# Verification command

Workflow Diagram​

Subscription Checkout Flow

Step-by-Step Narrative​

Step 1: Checkout Request Received​

  • Node: Checkout Webhook
  • Type: HTTP POST Endpoint
  • Path: /checkout
  • Actions:
    • Receives checkout request from web application
    • Validates required fields: user_id, org_id, tier
    • Authenticates request via session token
    • Retrieves user email from database

Step 2: Validate Selected Tier​

  • Node: Validate Tier
  • Type: Code (JavaScript)
  • Actions:
    • Confirms tier is valid: starter, professional, business, enterprise
    • Looks up corresponding Stripe price ID
    • Calculates any prorated amounts for upgrades
    • Checks for existing subscriptions to handle upgrade vs new

Step 3: Create or Retrieve Stripe Customer​

  • Node: Stripe Customer
  • Type: Stripe API Call
  • Actions:
    • Checks if organization has existing Stripe customer ID
    • If not, creates new Stripe customer
    • Associates customer with organization email
    • Stores Stripe customer ID in organizations table

Step 4: Create Checkout Session​

  • Node: Create Checkout Session
  • Type: Stripe API Call
  • Endpoint: stripe.checkout.sessions.create
  • Actions:
    • Creates Stripe Checkout Session
    • Sets line items with selected price ID
    • Configures success URL: https://app.coditect.ai/checkout/success?session_id={CHECKOUT_SESSION_ID}
    • Configures cancel URL: https://app.coditect.ai/checkout/cancel
    • Attaches metadata: org_id, user_id, tier

Step 5: Return Checkout URL​

  • Node: Success Response
  • Type: Webhook Response
  • Actions:
    • Returns HTTP 200 with checkout URL
    • Client redirects user to Stripe Checkout
    • User completes payment on Stripe-hosted page

Data Flow​

Input:
{
  "user_id": "user-uuid",
  "org_id": "org-uuid",
  "tier": "professional"
}

Output:
{
  "success": true,
  "checkout_url": "https://checkout.stripe.com/c/pay/cs_live_xxx"
}

Tier Pricing Reference​

TierMonthly PriceAnnual PriceStripe Price ID
Starter$29/mo$290/yrprice_starter_monthly
Professional$99/mo$990/yrprice_professional_monthly
Business$299/mo$2,990/yrprice_business_monthly
EnterpriseCustomCustomContact Sales

Post-Checkout Flow​

After the user completes payment on Stripe:

  1. Stripe sends webhook to /stripe/webhook (WF-003)
  2. Webhook handler verifies signature and event type
  3. On checkout.session.completed:
    • Updates organization subscription tier
    • Publishes provisioning event to Pub/Sub
    • WF-004 automatically provisions workstation

Error Handling​

ErrorCauseResponse
400 Bad RequestInvalid tier{ "error": "Invalid subscription tier" }
401 UnauthorizedInvalid session{ "error": "Authentication required" }
402 Payment RequiredStripe error{ "error": "Payment processing failed" }
500 Internal ErrorDatabase failure{ "error": "Checkout initialization failed" }

Security Considerations​

  • User must be authenticated to initiate checkout
  • Only organization admins/owners can upgrade subscriptions
  • Stripe customer ID never exposed to frontend
  • All payment data handled by Stripe (PCI compliant)
  • Checkout session expires after 24 hours

Troubleshooting​

Common Issue 1​

Problem: Description of issue Solution: Steps to resolve

Common Issue 2​

Problem: Description of issue Solution: Steps to resolve

Next Steps​

After completing this guide:

  1. Explore: Additional related features
  2. Practice: Apply concepts in your project
  3. Reference: Related documentation