AI Try-On — Technical Documentation for Shopify Review

Prepared for Shopify App Store Review Team Version: 1.0.0 Date: January 2026

1. App Overview

Official support notice: FitRum support writes only from [email protected]. Any other email or person claiming to represent FitRum support is fraudulent.

1.1 What the App Does

AI Try-On enables Shopify merchants to offer virtual clothing try-on experiences to their customers. Using AI image generation, shoppers upload a photo and see a realistic preview of how a garment would look on them.

1.2 Key Features

• Theme App Extension: Configurable "Try It On" button on product pages
• AI Photo Validation: Lightweight pre-check before expensive generation
• AI Generation: Managed AI generation workflow
• Analytics: Revenue attribution, product-level metrics, shopper behavior
• Shopify Billing API: Native subscription management with usage-based overage
• Web Pixel Extension: Checkout/order attribution tracking
• GDPR Compliance: Automated data deletion via Shopify compliance webhooks

2. Architecture Overview

Shopify Store (Embedded Admin App)
├── Theme App Extension (Storefront Widget)
│   ├── try-on-button.liquid (Product page block)
│   ├── tryon-widget.js (Modal & interaction logic)
│   └── tryon-widget.css (Styling)
│
├── Web Pixel Extension
│   └── checkout_started / checkout_completed tracking
│
└── Backend (Remix + Node.js)
    ├── Shopify OAuth + App Bridge (Embedded)
    ├── App Proxy (/apps/ai-tryon → /api)
    ├── Admin Routes (/app/*)
    ├── API Routes (/api/*)
    └── Webhooks (/webhooks/*)

2.1 Technology Stack

3. Installation Flow

3.1 OAuth Flow

1. Merchant clicks "Add app" in Shopify App Store
2. Redirected to /auth route
3. Shopify OAuth grant screen with scopes:
   • read_products
   • read_orders
   • write_pixels
   • read_customer_events
   • write_app_proxy
   • read_themes
4. After authorization, afterAuth hook:
   • Upserts shop record
   • Ensures Free plan subscription
   • Activates Web Pixel (if possible)

3.2 Post-Install Setup

1. Merchant is redirected to Dashboard
2. Onboarding checklist displayed
3. Prompted to add Theme App Extension block
4. Prompted to select products

4. Core Functionality

4.1 Theme App Extension

File: extensions/ai-tryon-theme/blocks/try-on-button.liquid

The block renders conditionally based on:

• Product support classification (title, type, tags)
• Merchant settings (hide unsupported, tag filter, collection filter)
• Selected variant availability

Supported product categories:

• upper_body: T-shirts, shirts, hoodies, sweaters, jackets
• bottoms: Jeans, pants, skirts, shorts, leggings
• dress: Dresses, gowns
• one_piece: Jumpsuits, rompers, swimsuits
• set: Suits, tracksuits, matching sets

Unsupported terms (auto-hidden): shoes, bags, jewelry, accessories, etc.

4.2 Widget Flow (Storefront)

File: scripts/tryon-widget.source.js

1. Button Click → Open modal
2. File Selection → Client-side validation (size < 20MB, image type)
3. Local Preview → Object URL for instant preview
4. Generate Click → API call to /tryon/start (creates job)
5. Upload → FormData POST to /tryon/upload with photo
6. Server Validation → AI vision model checks photo suitability
7. Queue → Job queued for background processing
8. Worker Processing → AI generates try-on image
9. Polling → Client polls /tryon/status/:jobId
10. Result Display → Signed URL for result image
11. Add to Cart → Line item with _tryon_job_id property

4.3 AI Generation Pipeline

File: app/services/tryon-processing.server.ts

QUEUED → PROCESSING → [COMPLETED | FAILED]

• Retry limit: 2 attempts (configurable)
• Timeout: 180 seconds
• On failure: retries after 1.5s delay
• On success: deducts 1 credit, records analytics

Prompt Engineering: The app constructs category-specific prompts to instruct the AI:

• Preserve the same person, face, pose, background
• Replace only the relevant clothing area
• Maintain garment color, print, logo, structure

4.4 Photo Validation

File: app/services/photo-validation.server.ts

Pre-generation validation using a cheap vision model:

• Checks: person detection, single person, body visibility, resolution, brightness, sharpness, NSFW
• Model: Lightweight AI vision validation service
• Timeout: 10 seconds
• Cost: ~$0.001 per validation
• On rejection: no generation credit deducted

5. Billing Implementation

5.1 Shopify Billing API Integration

File: app/services/billing.server.ts

All charges use Shopify's GraphQL Billing API:

• appSubscriptionCreate for plan subscriptions
• appUsageRecordCreate for overage charges
• Test mode supported via SHOPIFY_BILLING_TEST=true

5.2 Plan Structure

5.3 Credit System

• Credits reset monthly (calendar month, UTC)
• Included monthly credits: Free 30, Basic 100, Pro 500, Premium 1600, Global 5000
• Overage charges appear on Shopify invoice
• Usage records tracked in UsageRecord table
• Threshold notifications sent at 80% usage
• Merchant settings include a per-user generation limit from 4 to 100, default 10. The limit is enforced per shopper and product.

6. Data Handling & Privacy

6.1 Data Collection Summary

6.2 GDPR / CPRA Compliance

Compliance Webhooks Implemented:

Data Deletion Process:

1. Webhook received → Log in WebhookLog table
2. Create DeletionRequest record
3. Process asynchronously:
   • Delete photos from private temporary media storage
   • Delete generated results from private temporary media storage
   • Nullify database references
   • Create DeletionAuditLog entries
4. Mark request as COMPLETED

6.3 Shopper Consent

• Explicit checkbox required before photo upload
• Consent text customizable by merchant
• Privacy policy link displayed
• No photo processed without consent

7. Security Measures

7.1 Authentication

• Shopify OAuth 2.0 with PKCE
• Session tokens encrypted with SESSION_ENCRYPTION_KEY
• Prisma ORM prevents SQL injection

7.2 Authorization

• App Proxy verifies Shopify signature on storefront requests
• Admin routes require Shopify session authentication
• Webhooks validate HMAC signature

7.3 Data Protection

• All API traffic over HTTPS/TLS 1.3
• Temporary media storage is private and not publicly browsable
• Signed URLs expire in 15 minutes
• Access tokens encrypted at rest (AES-256)

7.4 Input Validation

• File type validation: images only
• File size limit: 20MB
• Photo validation: AI-powered content check
• Rate limiting: 60 requests/minute per shop (upload), 30/minute (start)

8. Testing Instructions for Review

8.1 Development Store

• Store URL: suren-ai-try-on-dev.myshopify.com
• Test Products: Clothing items with supported tags

8.2 Test Scenarios

Scenario 1: Basic Try-On Flow

1. Install app on development store
2. Add Theme App Extension block to product page
3. Visit product page as customer
4. Click "Try It On"
5. Upload a clear photo (JPG/PNG)
6. Wait for generation (45-90s)
7. Verify result displays
8. Click "Add to Cart"
9. Verify cart contains product with _tryon_job_id

Scenario 2: Photo Validation Rejection

1. Try to upload:
   • Non-image file → Should reject immediately
   • Photo with multiple people → Should reject with reason
   • Very dark/blurry photo → Should reject with reason
2. Verify no generation credit deducted

Scenario 3: Plan Upgrade

1. Start on Free plan
2. Exceed 30 generations
3. Verify button hidden / upgrade prompt shown
4. Upgrade to Basic plan
5. Verify Shopify Billing approval flow
6. Verify generation resumes

Scenario 4: Data Deletion (GDPR)

1. Trigger customers/redact webhook via Shopify CLI
2. Verify webhook returns 200
3. Check database: customer data nullified
4. Check media storage: photos and results deleted

Scenario 5: Shop Uninstall

1. Uninstall app from Shopify admin
2. Verify app/uninstalled webhook received
3. Wait 48 hours
4. Verify all shop data deleted

8.3 Test Credentials

• Merchant Login: Standard Shopify development store
• No additional credentials required

8.4 Screencast

A video demonstrating the full try-on flow should be added before Shopify App Store submission.

9. API Endpoints

9.1 App Proxy (Storefront-facing)

Base path: /apps/ai-tryon → Proxied to /api

9.2 Admin Routes

9.3 Webhooks

10. Performance & Scalability

10.1 Response Times

10.2 Rate Limits

10.3 Scalability

• Horizontal scaling via load balancer
• Async job processing through a background queue
• Database connection pooling
• CDN-ready signed URLs for images

11. Known Limitations

1. AI Accuracy: Generated results are approximations, not photographs. Color, fit, and texture may vary.
2. Processing Time: Generation usually takes 45-90 seconds depending on image complexity and current service load.
3. Photo Requirements: Results depend heavily on photo quality and composition.
4. Product Support: Only clothing items are supported; accessories, shoes, and non-apparel are automatically excluded.
5. Mobile: Fully supported on mobile browsers, but very large images (>10MB) may upload slowly on weak connections.

12. Support & Maintenance

Emergency Contact: [email protected] Bug Reports: [email protected]

FitRum support writes only from [email protected]. Any other email or person claiming to represent FitRum support is fraudulent.

13. Changelog

v1.0.0 (January 2026)

• Initial release
• Theme App Extension for product pages
• AI generation workflow
• Shopify Billing API integration
• Web Pixel Extension for attribution
• GDPR compliance webhooks
• Multi-plan billing (Free, Basic, Pro, Premium, Global)

This documentation is provided for Shopify App Store review purposes. For the latest updates, refer to the app's listing page or contact support.