UPI Storefront
A shareable Indian shop with Razorpay UPI, inventory and order admin, configurable branding, and three theme presets.
This is a software spec on Spekkr, published by dwrtz. It is listed with the other specs. Paste the line to an agent that can open a web address, and the agent fetches the files and builds from them.
- Spec
dwrtz/upi-storefront- Version
- 1.0.1
- Published by
- dwrtz
- Updated
- 15 Nov 2026
Build this spec
Build the spec at https://spekkr.com/dwrtz/upi-storefront/start.md.
Paste this to your AI agent. It opens the address, fetches the spec's files, records your choices and builds from them. Nothing to install, no account.
Published by dwrtz.
What does the result look like?
What can I customize?
Your choices go into the line you copy. Anything else is yours to edit, but it leaves the tested path.
What do I get?
-
README.mdPackage status and publishing notes.UPI Storefront spec package
Version 1.0.1, prepared 2026-11-15. A buildable design for a configurable Indian e-commerce site with Razorpay, inventory/admin, shareable products and three theme directions.
Read
spec.md, thendesign.mdandacceptance.md.spekkr.jsondescribes customization;theme.schema.jsonvalidates the supplied theme presets. The sample catalog is synthetic.This package is a specification, not application source or a verified commerce implementation. No store has been built, no Razorpay merchant account created, and no live payment made. The specification is published at https://spekkr.com/dwrtz/upi-storefront/.
The published namespace is
dwrtz/upi-storefront. To update it, increment the version and use Spekkr’s publish workflow. Specs live on Spekkr, not in the platform repository.Validation: Spekkr live
check_specreturnedready: truewith no problems on 2026-11-15. All listed files exist; all three presets pass JSON Schema validation. These checks do not validate a built application.Four labeled concept previews illustrate the storefront themes and merchant admin. They are rendered static HTML designs with synthetic products/data, not screenshots of a functional application. PNGs are listed as demo screenshots, with editable HTML under previews/.
# UPI Storefront spec package Version 1.0.1, prepared 2026-11-15. A buildable design for a configurable Indian e-commerce site with Razorpay, inventory/admin, shareable products and three theme directions. Read `spec.md`, then `design.md` and `acceptance.md`. `spekkr.json` describes customization; `theme.schema.json` validates the supplied theme presets. The sample catalog is synthetic. This package is a specification, not application source or a verified commerce implementation. No store has been built, no Razorpay merchant account created, and no live payment made. The specification is published at https://spekkr.com/dwrtz/upi-storefront/. The published namespace is `dwrtz/upi-storefront`. To update it, increment the version and use Spekkr’s publish workflow. Specs live on Spekkr, not in the platform repository. Validation: Spekkr live `check_spec` returned `ready: true` with no problems on 2026-11-15. All listed files exist; all three presets pass JSON Schema validation. These checks do not validate a built application. Four labeled concept previews illustrate the storefront themes and merchant admin. They are rendered static HTML designs with synthetic products/data, not screenshots of a functional application. PNGs are listed as demo screenshots, with editable HTML under previews/.
-
spec.mdExperience and product requirements.UPI Storefront
A mobile-first, single-merchant Indian shop that turns a shared product link into a paid, fulfilled order. Merchants manage their catalog and operations from a phone, and can change their brand without rebuilding commerce.
Build contract
Build the complete experience described here, using
design.md,acceptance.mdandtheme.schema.json. This is a specification, not a tested application. Supply working code, migrations, seed data, automated tests, an operator guide and a verification report. Use synthetic data and Razorpay test credentials until the merchant approves a live rollout. Do not label integrations working unless verified.Default implementation: TypeScript, Next.js server-rendered storefront/admin, PostgreSQL, S3-compatible image storage, Razorpay Standard Checkout and a persistent background worker. Use supported stable dependency versions and a lockfile. Deploy to the owner's chosen compatible host; document required services and recurring costs. Switching infrastructure requires preserving the transaction and job semantics in this spec.
Customer experience
- Branded home with editable hero, collection grid, featured products, announcement and trust/support sections. Product and collection URLs are stable across theme changes.
- Product pages show photos with alt text, description, INR price, variants/SKUs, availability, delivery estimate, return policy and related products. Each variant may override image and price. Search and filters work with pagination; unavailable variants are visibly disabled.
- Cart supports quantity changes and removal. Guest checkout is the default: name, contact email, phone and delivery address, with six-digit PIN validation and merchant-configured serviceability. Show item, discount, tax and shipping amounts before payment. Never invent delivery coverage from PIN syntax alone.
- Razorpay checkout offers UPI through supported provider/device flows. The customer returns to a resilient order-status page after switching apps. Pending payment is a real state, with retry/recheck guidance. Selecting an uninstalled app, cancelling or closing the browser must not lose the order.
- A private, unguessable order-status link shows only necessary order information, never indexed or included in public sharing. Sensitive actions and full address visibility require verified access. Reordering rechecks catalog prices and stock.
Merchant admin
- Owner and staff access with server-enforced roles: owner controls credentials, staff access, policies and refunds; catalog staff edit catalog/stock; fulfillment staff process orders. Maintain an audit log with actor, timestamp, reason and before/after values for sensitive changes.
- Draft/publish/archive products; reorder images; manage variants, SKU uniqueness, collections, featured products, prices and inventory. Preserve order snapshots when products change or disappear.
- Stock adjustment ledger and low-stock queue; physical stock and reserved stock displayed separately. CSV catalog/inventory import with downloadable template, dry-run errors, explicit preview and atomic commit; exports escape spreadsheet formulas. Imports use optimistic versions and cannot silently overwrite newer edits.
- Order queue filters by payment and fulfillment state. Pack, ship, record carrier/tracking URL, mark delivery or pickup, cancel eligible quantities and process authorized full/partial refunds. Internal notes remain private. Prevent shipping unpaid or exception orders.
- Inventory restocking is an explicit, idempotent operation, separate from refunding money. Support partial line cancellations and quantities without refunding more than captured funds or restocking twice.
- Sales dashboard: paid order count, gross merchandise value, discounts, refunds, net receipts, average order value and top products, with defined time zone and date range. Separate payment totals from shipping/tax; never imply these are audited accounting figures. Show payment/notification failures and operational exceptions.
Brand and theme editor
Use schema-validated theme documents independent of catalog/order data. Presets
minimal,editorialandbolddiffer in composition, typography and density, not just colors. Edit logo, colors, font choices, imagery, corner radius, spacing and home-page section order. Support draft preview on desktop/mobile, publish and rollback to an immutable prior version. Preview URLs require authorization. Reject arbitrary script/HTML injection; rich text uses a safe block model.The same seeded catalog must look convincingly distinct in all three presets. Preserve contrast, keyboard navigation, focus visibility, readable error messages and reduced-motion behavior. Target WCAG 2.2 AA on core flows. All screens work at 360px width without horizontal scrolling.
Sharing and discovery
- Server-rendered product/collection pages have canonical URLs, titles, descriptions, Open Graph images and product structured data matching current visible content. Archived pages show a useful unavailable state; redirects preserve changed slugs.
- Native share, copy link, WhatsApp link and downloadable branded product cards/QR codes. Sharing is user initiated; no automatic contacts access or unsolicited messages.
- Share a product with a selected variant, a collection, or a curated bundle/cart. Public share records contain only published product/variant IDs and quantities, never buyer details, discounts tied to a customer, payment IDs or private order tokens. Rate-limit creation; cap line counts; support expiry and removal. Recipients receive independent carts and current quotes.
- Optional campaign tags attribute visits and purchases without embedding personal data. Minimize analytics identifiers; honor applicable consent choices. Public previews show no private or draft data. Generate images from trusted assets; prevent server-side URL-fetch abuse.
Delivery, promotions and communication
Shipping is required by default; pickup is configurable. Merchant-defined PIN zones support flat rates and free-shipping thresholds, with explicit priority for overlapping zones. Quote shipping against discounted merchandise subtotal, excluding tax, and freeze the accepted quote on the order. Outside coverage cannot check out. Display merchant-authored estimates, not carrier promises. Carrier booking is a future adapter; initial tracking is manual.
Coupons support percentage or fixed discounts, expiry, minimum subtotal, usage caps and eligible products. One coupon per order, discount capped at eligible subtotal, deterministic allocation across lines. Reserve limited uses transactionally and release on expiry; confirm on payment. Publish tax-inclusive or tax-exclusive pricing explicitly. Merchant supplies tax categories/rates and registration/invoice details; implement deterministic line rounding and tax snapshots, and have the merchant verify applicable tax requirements before launch.
Order confirmations, shipping updates and refund updates use a transactional outbox. Provide a functional email adapter and delivery/error log. WhatsApp support is a click-to-chat link; automated WhatsApp requires a separately connected approved service, consent and templates. Keep disabled integrations visibly unconfigured. Never show a message as sent until the provider accepts it; acceptance is not delivery. Provide downloadable receipts and configurable invoice fields.
Configuration
Manifest inputs seed the shop; ongoing changes happen through admin. Shipping remains enabled;
pickup,couponsandreviewsare optional. If reviews are enabled, link verified-purchase eligibility to actual paid orders, moderate text safely, rate-limit and allow abuse reports; never seed fake customer endorsements. Demo reviews must be labeled synthetic.Razorpay is the payment implementation, not an optional mock for production. Each shop uses its own activated merchant account and settlement bank account. Spekkr does not receive or settle shoppers' money. No payment credentials belong in theme or exported public configuration.
# UPI Storefront A mobile-first, single-merchant Indian shop that turns a shared product link into a paid, fulfilled order. Merchants manage their catalog and operations from a phone, and can change their brand without rebuilding commerce. ## Build contract Build the complete experience described here, using `design.md`, `acceptance.md` and `theme.schema.json`. This is a specification, not a tested application. Supply working code, migrations, seed data, automated tests, an operator guide and a verification report. Use synthetic data and Razorpay test credentials until the merchant approves a live rollout. Do not label integrations working unless verified. Default implementation: TypeScript, Next.js server-rendered storefront/admin, PostgreSQL, S3-compatible image storage, Razorpay Standard Checkout and a persistent background worker. Use supported stable dependency versions and a lockfile. Deploy to the owner's chosen compatible host; document required services and recurring costs. Switching infrastructure requires preserving the transaction and job semantics in this spec. ## Customer experience - Branded home with editable hero, collection grid, featured products, announcement and trust/support sections. Product and collection URLs are stable across theme changes. - Product pages show photos with alt text, description, INR price, variants/SKUs, availability, delivery estimate, return policy and related products. Each variant may override image and price. Search and filters work with pagination; unavailable variants are visibly disabled. - Cart supports quantity changes and removal. Guest checkout is the default: name, contact email, phone and delivery address, with six-digit PIN validation and merchant-configured serviceability. Show item, discount, tax and shipping amounts before payment. Never invent delivery coverage from PIN syntax alone. - Razorpay checkout offers UPI through supported provider/device flows. The customer returns to a resilient order-status page after switching apps. Pending payment is a real state, with retry/recheck guidance. Selecting an uninstalled app, cancelling or closing the browser must not lose the order. - A private, unguessable order-status link shows only necessary order information, never indexed or included in public sharing. Sensitive actions and full address visibility require verified access. Reordering rechecks catalog prices and stock. ## Merchant admin - Owner and staff access with server-enforced roles: owner controls credentials, staff access, policies and refunds; catalog staff edit catalog/stock; fulfillment staff process orders. Maintain an audit log with actor, timestamp, reason and before/after values for sensitive changes. - Draft/publish/archive products; reorder images; manage variants, SKU uniqueness, collections, featured products, prices and inventory. Preserve order snapshots when products change or disappear. - Stock adjustment ledger and low-stock queue; physical stock and reserved stock displayed separately. CSV catalog/inventory import with downloadable template, dry-run errors, explicit preview and atomic commit; exports escape spreadsheet formulas. Imports use optimistic versions and cannot silently overwrite newer edits. - Order queue filters by payment and fulfillment state. Pack, ship, record carrier/tracking URL, mark delivery or pickup, cancel eligible quantities and process authorized full/partial refunds. Internal notes remain private. Prevent shipping unpaid or exception orders. - Inventory restocking is an explicit, idempotent operation, separate from refunding money. Support partial line cancellations and quantities without refunding more than captured funds or restocking twice. - Sales dashboard: paid order count, gross merchandise value, discounts, refunds, net receipts, average order value and top products, with defined time zone and date range. Separate payment totals from shipping/tax; never imply these are audited accounting figures. Show payment/notification failures and operational exceptions. ## Brand and theme editor Use schema-validated theme documents independent of catalog/order data. Presets `minimal`, `editorial` and `bold` differ in composition, typography and density, not just colors. Edit logo, colors, font choices, imagery, corner radius, spacing and home-page section order. Support draft preview on desktop/mobile, publish and rollback to an immutable prior version. Preview URLs require authorization. Reject arbitrary script/HTML injection; rich text uses a safe block model. The same seeded catalog must look convincingly distinct in all three presets. Preserve contrast, keyboard navigation, focus visibility, readable error messages and reduced-motion behavior. Target WCAG 2.2 AA on core flows. All screens work at 360px width without horizontal scrolling. ## Sharing and discovery - Server-rendered product/collection pages have canonical URLs, titles, descriptions, Open Graph images and product structured data matching current visible content. Archived pages show a useful unavailable state; redirects preserve changed slugs. - Native share, copy link, WhatsApp link and downloadable branded product cards/QR codes. Sharing is user initiated; no automatic contacts access or unsolicited messages. - Share a product with a selected variant, a collection, or a curated bundle/cart. Public share records contain only published product/variant IDs and quantities, never buyer details, discounts tied to a customer, payment IDs or private order tokens. Rate-limit creation; cap line counts; support expiry and removal. Recipients receive independent carts and current quotes. - Optional campaign tags attribute visits and purchases without embedding personal data. Minimize analytics identifiers; honor applicable consent choices. Public previews show no private or draft data. Generate images from trusted assets; prevent server-side URL-fetch abuse. ## Delivery, promotions and communication Shipping is required by default; pickup is configurable. Merchant-defined PIN zones support flat rates and free-shipping thresholds, with explicit priority for overlapping zones. Quote shipping against discounted merchandise subtotal, excluding tax, and freeze the accepted quote on the order. Outside coverage cannot check out. Display merchant-authored estimates, not carrier promises. Carrier booking is a future adapter; initial tracking is manual. Coupons support percentage or fixed discounts, expiry, minimum subtotal, usage caps and eligible products. One coupon per order, discount capped at eligible subtotal, deterministic allocation across lines. Reserve limited uses transactionally and release on expiry; confirm on payment. Publish tax-inclusive or tax-exclusive pricing explicitly. Merchant supplies tax categories/rates and registration/invoice details; implement deterministic line rounding and tax snapshots, and have the merchant verify applicable tax requirements before launch. Order confirmations, shipping updates and refund updates use a transactional outbox. Provide a functional email adapter and delivery/error log. WhatsApp support is a click-to-chat link; automated WhatsApp requires a separately connected approved service, consent and templates. Keep disabled integrations visibly unconfigured. Never show a message as sent until the provider accepts it; acceptance is not delivery. Provide downloadable receipts and configurable invoice fields. ## Configuration Manifest inputs seed the shop; ongoing changes happen through admin. Shipping remains enabled; `pickup`, `coupons` and `reviews` are optional. If reviews are enabled, link verified-purchase eligibility to actual paid orders, moderate text safely, rate-limit and allow abuse reports; never seed fake customer endorsements. Demo reviews must be labeled synthetic. Razorpay is the payment implementation, not an optional mock for production. Each shop uses its own activated merchant account and settlement bank account. Spekkr does not receive or settle shoppers' money. No payment credentials belong in theme or exported public configuration.
-
design.mdArchitecture and commerce invariants.Architecture and invariants
Components
Next.js serves public SSR pages and authenticated admin/API routes. PostgreSQL owns commerce state; object storage/CDN owns sanitized product images. A worker processes persisted jobs, payment reconciliation, reservation expiry and notifications. Jobs must continue when no visitors are present. Separate modules: catalog, inventory, checkout/orders, payments, fulfillment/refunds, themes, sharing, analytics and identity.
Use migrations and transactional constraints, not browser state, for correctness. Store money as integer paise with INR currency; timestamps in UTC and reporting in the configured shop time zone. Use safe integer bounds. Taxes and coupon allocation have deterministic rounding and documented examples.
Minimal data model
Products + variants (SKU, price, tax category, active version); inventory balances + immutable movements; collections; media; cart/share records; orders + immutable line/price/address snapshots; reservation groups + lines; checkout idempotency records; payment attempts + provider order/payment IDs; received webhook events; fulfillment lines; refund requests + allocations; coupons + reserved/consumed uses; theme versions; staff/roles; audit events; outbox + jobs. Add foreign keys, uniqueness and indexes for every frequent lookup and identity boundary.
Checkout and inventory
- Client sends variant IDs, quantities, coupon, delivery details and a unique checkout key. Server validates and calculates all prices. Repeated identical key returns the same result; different payload with the same key returns conflict.
- In one database transaction, lock affected inventory rows in a stable order, validate
on_hand - reserved >= requested, reserve stock/coupon usage, create pending local order and a payment-attempt intent. Default reservation is 15 minutes, configurable. Persist quote and expiry. - Create the Razorpay order server-side, outside the stock transaction. Record its identity uniquely. Do not assume the provider supports an idempotency key it does not document. If the create result is ambiguous, reconcile by recorded provider metadata/receipt where supported; otherwise pause that attempt for investigation instead of blindly creating repeated payable orders.
- Issue checkout parameters only for a persisted attempt. A retry must not create concurrent payable attempts unknowingly. If multiple payments nevertheless succeed, accept at most one for fulfillment and route extra captures to a refund exception.
- Verified captured/paid status transitions the order exactly once, consuming reserved stock and coupon usage transactionally. Inventory movement unique key includes the order and transition. Authorized-only payment is not captured money.
- Expiry, cancellation and payment settlement lock the same order/reservation records and apply conditional state transitions. Expiry releases reservations once. A late payment atomically reacquires every item and coupon eligibility against the original financial snapshot, or enters
paid_exceptionfor refund/manual resolution; never silently oversell or change what the customer paid. Payment failure cannot downgrade a successful order.
Inventory adjustment cannot reduce physical stock below currently reserved quantities without an explicit exception workflow. API actions use version checks to reject stale edits. There is no external network call inside a held database transaction.
Payment verification
Razorpay Standard Checkout uses current supported intent/QR behavior; provider controls app/device compatibility. Verify checkout signatures server-side, using the server-recorded provider order ID. Verify raw-body webhook HMAC before parsing/trusting fields, with separate webhook secret and documented secret rotation. Validate account/mode, order, amount and currency; fetch authoritative provider status as needed. A browser callback, UPI return, screenshot or buyer-supplied reference is never sufficient to fulfill.
Persist verified webhook events durably with unique provider event ID before acknowledging; process idempotently. Duplicate/reordered events, worker crashes and replay after timeout must converge to the same state. Reconcile pending/ambiguous orders periodically through provider APIs with backoff/rate limits. Alert on unresolved paid exceptions, reconciliation age and failed jobs. Webhook outage recovery must not depend on the customer returning.
Payment attempts:
created,pending,authorized,captured,failed,unknown. Orders:awaiting_payment,paid,paid_exception,cancelled,closed. Fulfillment and refunds are separate line-level records with their own lifecycle; UI may derive combined badges. A refund does not erase capture history.Refund intent is persisted with a unique operation key and amount allocation. Concurrent requests lock captured/refunded/reserved-refund totals. After provider timeout, reconcile rather than issuing another refund blindly. Pending refunds reserve refundable balance. Only verified processed refunds count as complete. Provider rejection or lost response remains visible. Define who may approve refunds and log the actor/reason.
Access and safety
Use a maintained authentication implementation, secure cookies, CSRF protection, session revocation and rate limits. Owner bootstrap is one-time, and never a public fixed password. Owner MFA is required before live payments. Enforce permissions server-side on every endpoint and export. Keep customer PII out of logs, metrics, QR codes and public previews. Private order tokens have high entropy, expiry/revocation, no-referrer and no-store policies; do not expose full addresses through bearer links alone.
Validate uploads by decoded format, byte size and dimensions, strip metadata and re-encode supported raster formats. No executable uploads. Use safe redirect/tracking URL schemes; protect SSRF and open redirects. Secrets stay server-side in the host's secret store. Apply a CSP compatible with the verified payment integration. Redact exports and backups to authorized roles and define retention/deletion with merchant policy.
Operations and deployment
Transactional outbox separates committed commerce changes from notifications; at-least-once delivery plus stable message keys prevents duplicate customer messages where provider support permits. Do not promise exactly-once external delivery. Background processing uses retry budgets, leases, dead letters and observable status.
Before live launch: migrations tested, backup restore demonstrated, HTTPS/domain configured, image storage access scoped, worker/reconciliation scheduled, merchant activation confirmed, live webhook verified, policies/contact/returns/shipping/tax settings reviewed, staff access audited and a merchant-approved real-device payment/refund test performed. Never charge or refund real money without the owner's approval. Backups include database and object references; document RPO/RTO and how inventory/payment state is reconciled after restore.
Provider references
Verify current provider behavior during implementation; this spec's references were consulted 2026-11-15.
- https://razorpay.com/docs/payments/payment-methods/upi/
- https://razorpay.com/docs/payments/payment-gateway/web-integration/standard/integration-steps/
- https://razorpay.com/docs/webhooks/validate-test/
Use the chosen product's test mode, not assumptions from another Razorpay product. Report sandbox checks separately from real-device/live checks and merchant-account eligibility.
# Architecture and invariants ## Components Next.js serves public SSR pages and authenticated admin/API routes. PostgreSQL owns commerce state; object storage/CDN owns sanitized product images. A worker processes persisted jobs, payment reconciliation, reservation expiry and notifications. Jobs must continue when no visitors are present. Separate modules: catalog, inventory, checkout/orders, payments, fulfillment/refunds, themes, sharing, analytics and identity. Use migrations and transactional constraints, not browser state, for correctness. Store money as integer paise with INR currency; timestamps in UTC and reporting in the configured shop time zone. Use safe integer bounds. Taxes and coupon allocation have deterministic rounding and documented examples. ## Minimal data model Products + variants (SKU, price, tax category, active version); inventory balances + immutable movements; collections; media; cart/share records; orders + immutable line/price/address snapshots; reservation groups + lines; checkout idempotency records; payment attempts + provider order/payment IDs; received webhook events; fulfillment lines; refund requests + allocations; coupons + reserved/consumed uses; theme versions; staff/roles; audit events; outbox + jobs. Add foreign keys, uniqueness and indexes for every frequent lookup and identity boundary. ## Checkout and inventory 1. Client sends variant IDs, quantities, coupon, delivery details and a unique checkout key. Server validates and calculates all prices. Repeated identical key returns the same result; different payload with the same key returns conflict. 2. In one database transaction, lock affected inventory rows in a stable order, validate `on_hand - reserved >= requested`, reserve stock/coupon usage, create pending local order and a payment-attempt intent. Default reservation is 15 minutes, configurable. Persist quote and expiry. 3. Create the Razorpay order server-side, outside the stock transaction. Record its identity uniquely. Do not assume the provider supports an idempotency key it does not document. If the create result is ambiguous, reconcile by recorded provider metadata/receipt where supported; otherwise pause that attempt for investigation instead of blindly creating repeated payable orders. 4. Issue checkout parameters only for a persisted attempt. A retry must not create concurrent payable attempts unknowingly. If multiple payments nevertheless succeed, accept at most one for fulfillment and route extra captures to a refund exception. 5. Verified captured/paid status transitions the order exactly once, consuming reserved stock and coupon usage transactionally. Inventory movement unique key includes the order and transition. Authorized-only payment is not captured money. 6. Expiry, cancellation and payment settlement lock the same order/reservation records and apply conditional state transitions. Expiry releases reservations once. A late payment atomically reacquires every item and coupon eligibility against the original financial snapshot, or enters `paid_exception` for refund/manual resolution; never silently oversell or change what the customer paid. Payment failure cannot downgrade a successful order. Inventory adjustment cannot reduce physical stock below currently reserved quantities without an explicit exception workflow. API actions use version checks to reject stale edits. There is no external network call inside a held database transaction. ## Payment verification Razorpay Standard Checkout uses current supported intent/QR behavior; provider controls app/device compatibility. Verify checkout signatures server-side, using the server-recorded provider order ID. Verify raw-body webhook HMAC before parsing/trusting fields, with separate webhook secret and documented secret rotation. Validate account/mode, order, amount and currency; fetch authoritative provider status as needed. A browser callback, UPI return, screenshot or buyer-supplied reference is never sufficient to fulfill. Persist verified webhook events durably with unique provider event ID before acknowledging; process idempotently. Duplicate/reordered events, worker crashes and replay after timeout must converge to the same state. Reconcile pending/ambiguous orders periodically through provider APIs with backoff/rate limits. Alert on unresolved paid exceptions, reconciliation age and failed jobs. Webhook outage recovery must not depend on the customer returning. Payment attempts: `created`, `pending`, `authorized`, `captured`, `failed`, `unknown`. Orders: `awaiting_payment`, `paid`, `paid_exception`, `cancelled`, `closed`. Fulfillment and refunds are separate line-level records with their own lifecycle; UI may derive combined badges. A refund does not erase capture history. Refund intent is persisted with a unique operation key and amount allocation. Concurrent requests lock captured/refunded/reserved-refund totals. After provider timeout, reconcile rather than issuing another refund blindly. Pending refunds reserve refundable balance. Only verified processed refunds count as complete. Provider rejection or lost response remains visible. Define who may approve refunds and log the actor/reason. ## Access and safety Use a maintained authentication implementation, secure cookies, CSRF protection, session revocation and rate limits. Owner bootstrap is one-time, and never a public fixed password. Owner MFA is required before live payments. Enforce permissions server-side on every endpoint and export. Keep customer PII out of logs, metrics, QR codes and public previews. Private order tokens have high entropy, expiry/revocation, no-referrer and no-store policies; do not expose full addresses through bearer links alone. Validate uploads by decoded format, byte size and dimensions, strip metadata and re-encode supported raster formats. No executable uploads. Use safe redirect/tracking URL schemes; protect SSRF and open redirects. Secrets stay server-side in the host's secret store. Apply a CSP compatible with the verified payment integration. Redact exports and backups to authorized roles and define retention/deletion with merchant policy. ## Operations and deployment Transactional outbox separates committed commerce changes from notifications; at-least-once delivery plus stable message keys prevents duplicate customer messages where provider support permits. Do not promise exactly-once external delivery. Background processing uses retry budgets, leases, dead letters and observable status. Before live launch: migrations tested, backup restore demonstrated, HTTPS/domain configured, image storage access scoped, worker/reconciliation scheduled, merchant activation confirmed, live webhook verified, policies/contact/returns/shipping/tax settings reviewed, staff access audited and a merchant-approved real-device payment/refund test performed. Never charge or refund real money without the owner's approval. Backups include database and object references; document RPO/RTO and how inventory/payment state is reconciled after restore. ## Provider references Verify current provider behavior during implementation; this spec's references were consulted 2026-11-15. - https://razorpay.com/docs/payments/payment-methods/upi/ - https://razorpay.com/docs/payments/payment-gateway/web-integration/standard/integration-steps/ - https://razorpay.com/docs/webhooks/validate-test/ Use the chosen product's test mode, not assumptions from another Razorpay product. Report sandbox checks separately from real-device/live checks and merchant-account eligibility.
-
acceptance.mdRequired acceptance and failure-mode tests.Acceptance checks
An implementation is complete only with automated evidence where practical and a written manual test report. These are required scenarios, not claims that a build has passed.
Storefront and branding
- Seed 12 synthetic products, three collections and at least three variant products, including sold-out stock. Browse, search, filter, add variants and edit the cart at 360px and desktop widths.
- Render the same catalog under minimal, editorial and bold presets. Changing a theme alters layout and typography without changing SKUs, prices, order data or canonical URLs. Preview, publish, rollback and concurrent edits work; stale edits conflict.
- Core browse/checkout/admin flows work by keyboard and screen reader; audit contrast/focus/error announcements. Reduced motion is respected. Measure public product page performance using realistic image/network budgets and document results; optimize responsive images and avoid loading admin code publicly.
- Product and collection HTML exposes accurate metadata before JavaScript runs. A variant share reopens the right option; QR, WhatsApp and native share fallback work. A shared cart leaks no PII and revalidates price/stock. Draft/archived products cannot be purchased through stale links.
Payment and stock (use deterministic concurrency barriers)
- Two buyers compete for the last unit: exactly one reservation succeeds. Concurrent multi-SKU carts cannot deadlock indefinitely or partly reserve stock.
- Repeated checkout key returns one order; changed payload conflicts. Provider-create timeout does not produce uncontrolled duplicate payable attempts.
- Duplicate and out-of-order captured/failed webhooks produce one inventory consumption and one confirmation intent; mismatched amount/currency/order, bad signature and test/live mismatch do not mark paid.
- Crash before/after event persistence and before/after order transition; replay recovers without double consumption. Polling and webhook settlement racing give the same result.
- Reservation expiry racing capture releases or consumes once. Late success with available stock reacquires atomically; unavailable stock creates a visible paid exception and refund path. No paid order silently disappears.
- Two captured attempts on one order do not ship twice; extra payment is flagged. Two parallel refunds cannot exceed capture, including pending refunds. Timeout/retry does not issue a duplicate refund; rejected refund remains visible. Refund does not automatically restock; explicit restock is idempotent.
- Mobile Android/iOS UPI round trip, unavailable UPI app, back/cancel, browser termination/reopen, in-app browser and desktop QR have documented real-device results. Mock/sandbox tests do not substitute for these. Do not execute live transactions without approval.
Operations
- Import malformed/duplicate SKU/negative stock/stale CSV: dry-run identifies rows and commits nothing. Valid import commits once; formula-like cells are safely exported. Stock corrections preserve reservations and audit history.
- Delivery outside allowed PIN zones is rejected; overlapping-zone precedence, free-shipping threshold, pickup, coupon expiry/caps and tax rounding match documented examples. Concurrent final coupon use is not oversubscribed. Order snapshots survive later edits.
- Catalog staff cannot refund or change credentials; fulfillment staff cannot alter prices; logged-out and cross-role API requests fail. Owner MFA/session revocation/CSRF/rate limits are tested. Private links and exports do not leak addresses or payment data.
- Partial cancellation, shipment and refund quantities reconcile per line. A notification-provider outage does not roll back payment; retry and dead-letter state are visible. Disabled email/WhatsApp integrations never claim delivery.
- Restore a backup into an isolated environment; verify image references, order history and recovery procedure. Reconcile payment state safely without sending duplicate messages or making financial writes automatically.
- With coupons/reviews/pickup switched off, their entry points disappear without broken routes. If reviews are enabled, non-purchasers cannot impersonate verified buyers and moderation/rate limits work.
- Validate dashboard against a fixed fixture with taxes, shipping, discounts, partial refunds and day-boundary timestamps. Shared campaign attribution contains no buyer PII.
Handoff evidence
Provide test commands/results, dependency versions, migration/rollback instructions, configuration inventory, screenshots for all three themes, failure-mode runbook and known limitations. Label each integration: unconfigured, sandbox-verified or live-verified. No real customer data, secrets, fake endorsements or fabricated validation claims in fixtures or demos.
# Acceptance checks An implementation is complete only with automated evidence where practical and a written manual test report. These are required scenarios, not claims that a build has passed. ## Storefront and branding 1. Seed 12 synthetic products, three collections and at least three variant products, including sold-out stock. Browse, search, filter, add variants and edit the cart at 360px and desktop widths. 2. Render the same catalog under minimal, editorial and bold presets. Changing a theme alters layout and typography without changing SKUs, prices, order data or canonical URLs. Preview, publish, rollback and concurrent edits work; stale edits conflict. 3. Core browse/checkout/admin flows work by keyboard and screen reader; audit contrast/focus/error announcements. Reduced motion is respected. Measure public product page performance using realistic image/network budgets and document results; optimize responsive images and avoid loading admin code publicly. 4. Product and collection HTML exposes accurate metadata before JavaScript runs. A variant share reopens the right option; QR, WhatsApp and native share fallback work. A shared cart leaks no PII and revalidates price/stock. Draft/archived products cannot be purchased through stale links. ## Payment and stock (use deterministic concurrency barriers) 5. Two buyers compete for the last unit: exactly one reservation succeeds. Concurrent multi-SKU carts cannot deadlock indefinitely or partly reserve stock. 6. Repeated checkout key returns one order; changed payload conflicts. Provider-create timeout does not produce uncontrolled duplicate payable attempts. 7. Duplicate and out-of-order captured/failed webhooks produce one inventory consumption and one confirmation intent; mismatched amount/currency/order, bad signature and test/live mismatch do not mark paid. 8. Crash before/after event persistence and before/after order transition; replay recovers without double consumption. Polling and webhook settlement racing give the same result. 9. Reservation expiry racing capture releases or consumes once. Late success with available stock reacquires atomically; unavailable stock creates a visible paid exception and refund path. No paid order silently disappears. 10. Two captured attempts on one order do not ship twice; extra payment is flagged. Two parallel refunds cannot exceed capture, including pending refunds. Timeout/retry does not issue a duplicate refund; rejected refund remains visible. Refund does not automatically restock; explicit restock is idempotent. 11. Mobile Android/iOS UPI round trip, unavailable UPI app, back/cancel, browser termination/reopen, in-app browser and desktop QR have documented real-device results. Mock/sandbox tests do not substitute for these. Do not execute live transactions without approval. ## Operations 12. Import malformed/duplicate SKU/negative stock/stale CSV: dry-run identifies rows and commits nothing. Valid import commits once; formula-like cells are safely exported. Stock corrections preserve reservations and audit history. 13. Delivery outside allowed PIN zones is rejected; overlapping-zone precedence, free-shipping threshold, pickup, coupon expiry/caps and tax rounding match documented examples. Concurrent final coupon use is not oversubscribed. Order snapshots survive later edits. 14. Catalog staff cannot refund or change credentials; fulfillment staff cannot alter prices; logged-out and cross-role API requests fail. Owner MFA/session revocation/CSRF/rate limits are tested. Private links and exports do not leak addresses or payment data. 15. Partial cancellation, shipment and refund quantities reconcile per line. A notification-provider outage does not roll back payment; retry and dead-letter state are visible. Disabled email/WhatsApp integrations never claim delivery. 16. Restore a backup into an isolated environment; verify image references, order history and recovery procedure. Reconcile payment state safely without sending duplicate messages or making financial writes automatically. 17. With coupons/reviews/pickup switched off, their entry points disappear without broken routes. If reviews are enabled, non-purchasers cannot impersonate verified buyers and moderation/rate limits work. 18. Validate dashboard against a fixed fixture with taxes, shipping, discounts, partial refunds and day-boundary timestamps. Shared campaign attribution contains no buyer PII. ## Handoff evidence Provide test commands/results, dependency versions, migration/rollback instructions, configuration inventory, screenshots for all three themes, failure-mode runbook and known limitations. Label each integration: unconfigured, sandbox-verified or live-verified. No real customer data, secrets, fake endorsements or fabricated validation claims in fixtures or demos.
-
theme.schema.jsonTheme configuration schema. -
themesThree theme configurations. -
sample-catalog.csvSynthetic catalog fixture. -
previewsStatic HTML concept sources, not application code.
Is it for me?
- Kind
- App part
- Platforms
- web
- Clouds
- Any
- Stack
- TypeScript, Next.js, PostgreSQL, Razorpay
What does it need?
- Accounts
- Activated Razorpay merchant account for live payments, Application host and PostgreSQL, S3-compatible object storage, Transactional email service
- Agent permissions
- shell, network
- Secrets it reads
DATABASE_URLSESSION_SECRETRAZORPAY_KEY_IDRAZORPAY_KEY_SECRETRAZORPAY_WEBHOOK_SECRETOBJECT_STORAGE_ACCESS_KEYOBJECT_STORAGE_SECRET_KEYEMAIL_API_KEY
What changed?
- 1.0.115 Nov 2026Record live publication and clarify concept-preview status.
- 1.0.015 Nov 2026Initial UPI storefront specification.
For agents: start.md says how to build this spec, spec.json holds everything on this page, and bundle.tar.gz holds its files.