Production reference

1. Product definition

Reelmerce is a Shopify app for turning merchant-owned product videos into responsive shoppable reels. Merchants can upload or select Shopify-hosted videos, tag products, design reusable storefront experiences in Widget Studio, place them with Shopify Theme Editor, optimize presentation with performance-aware merchandising and Conversion Lab, and measure engagement through to attributed paid sales.

2. Current production scope and app surfaces

3. The problem it solves

• Merchants can have useful product videos without a reusable Shopify-native way to make them shoppable.
• Custom-coded reels can require theme edits, be hard to reuse, and be fragile across theme changes.
• Heavy video widgets can hurt storefront performance when every full video eagerly loads or plays.
• Merchants need visual control without rebuilding the same layout for every placement.
• Multi-product videos need product-aware merchandising and sold-out behavior.
• Merchants need evidence beyond views: product clicks, add-to-cart intent, cart value, and paid-sales attribution.
• Merchants need a controlled way to compare storefront designs using real shopper behavior.

4. Product promise / USP

5. Product terminology

6. Merchant workflow and onboarding

1. Install and open Reelmerce inside Shopify Admin.
2. Add a video by uploading a file or choosing a Shopify Video from Shopify Files.
3. Optionally tag one or more Shopify products within the current plan limit.
4. Publish when Shopify processing is READY, or save as Draft.
5. Choose an included template and customize the Default design in Widget Studio.
6. Optionally create Saved designs for different storefront placements.
7. Open Shopify Theme Editor and add the Reelmerce reels app block.
8. Choose Default or a Saved design, configure placement behavior, and publish the theme change.
9. Verify the storefront and review Analytics after shopper traffic begins.

App Home detects whether a video exists, a Widget Studio design is configured, and the Reelmerce theme app extension is active on the published theme. Once all three are complete, onboarding is replaced by a live status card and performance summary.

6.2 Video creation and processing

• Upload from device: MP4, MOV, or WEBM, up to 1 GB.
• Choose from Shopify: Shopify's native Video file picker.
• Cover images: JPG, PNG, or WEBP, up to 20 MB.
• Drafts can be saved while Shopify is processing; publishing is blocked until status is READY.
• Failed Shopify processing is surfaced as Failed and cannot be published.
• Only published/ACTIVE Reelmerce videos count toward plan video capacity.

7. Video management and merchandising

7.1 Product tagging

Product tagging is optional. A video can remain video-only. Reelmerce stores both a primary product reference and a list of tagged products in the app-owned shoppable-video metaobject.

• The first tagged product is the primary product on general placements.
• Current-product mode shows only videos tagged to the current product page and uses the matching page product.
• On product templates using All videos, an untagged video can use the current page product as contextual commerce.
• Existing tags are preserved after downgrade, but only the first products within the new plan limit remain active on storefront.

7.2 Per-video merchandising controls

7.3 Video Library

• Status tabs: All, Live, Draft, Processing, and Failed when applicable.
• Search by product or offer text.
• Source filter for Shopify library or uploaded videos.
• Performance windows: all time, last 7, 30, or 90 days.
• Sort by recently added, oldest, most views, highest CTR, or most add-to-cart actions.
• Summary includes total videos, plan, live count, storefront views, plays, and added cart value.
• Per-video performance includes storefront views, CTR, and add-to-cart count.

8. Built-in templates

The Templates screen previews all eight on desktop, tablet, and mobile. Locked templates remain previewable but cannot be applied or customized until upgrade. The gallery uses sample content to judge design; storefront and Customize use the merchant's own published videos.

9. Widget Studio

9.1 Design model

• Default design: shared fallback for placements with no Saved design.
• Saved designs: named reusable configurations up to 80 characters, selectable from Theme Editor.
• Custom mix: each section can inherit from a different included template.
• Borrow settings: copy only Layout, Video, Product, Button, Navigation, Style, or Text from another included template.
• Live preview: desktop, tablet, and mobile inside the app.
• Changing a Saved design affects all placements using it; deleting one makes those placements fall back to Default.

9.2 Widget Studio controls

10. Theme Editor placement controls

Theme Editor owns placement-specific decisions so one reusable design can be tuned for different sections without duplication.

11. Inventory-aware and contextual storefront behavior

• Current product mode shows only videos tagged with the product on the current product page.
• Sold-out behavior can keep the video visible and disable CTA, or hide videos whose selected product variant is unavailable.
• General placements use the first active tagged product as the primary product dock/CTA.
• Product information can show image, price, compare-at price, and discount according to the design.
• A video can remain non-shoppable when no product is tagged.

12. Storefront shopper experience

• Responsive card sizing with compact maximum widths and minimum readable widths.
• Short groups center when all cards fit; overflowing groups remain horizontally scrollable.
• Pointer hover lift/shadow with reduced-motion support.
• Recommended 5-second preview loops only the beginning of the original Shopify-hosted video; no separate five-second asset is generated.
• Full-video autoplay and open-on-click-only modes are available.
• Offscreen cards pause/reset; visible/hovered/focused cards coordinate playback to reduce simultaneous activity.
• Expanded viewer includes close/Escape, fullscreen, sound, actual views when enabled, Like, Share, Cart, and product CTA.
• Share uses Web Share, then clipboard fallback.
• Like is browser-local in localStorage; no global like count or like analytics.
• Direct Shopify cart add is attempted; common cart drawer/notification/header surfaces are refreshed where possible, with product-page fallback if cart flow cannot complete.

13. Performance-based video ordering

Each placement can stay in manual order or use a performance snapshot generated from the last 30 days of storefront events.

• Rate modes require at least 20 views so low-sample videos do not dominate.
• Low-sample or unranked videos retain manual ordering after ranked items.
• Up to 50 ranked video handles are stored.
• Snapshots refresh no more than about once every five minutes and are stored in an app-installation metafield.

14. Analytics

14.1 Event model

14.2 Analytics dashboard

• Top-level KPIs: storefront views, product clicks, add to carts, added cart value, and attributed paid sales when enabled.
• KPI comparison defaults to previous equivalent period; Unlimited can choose previous month, previous year, or custom comparison.
• Daily storefront-view trend, per-video table, search, status/source filters, and sorting.
• Per-video CTR and add-to-cart rate; rate calculations cap one conversion per view while raw counts remain unchanged.
• Sorting supports newest, oldest, views, clicks, add-to-carts, click rate, and add-to-cart rate.
• Paid sales are displayed per currency and never summed across multiple presentment currencies.

14.3 Analytics history by plan

15. Paid-order revenue attribution

Reelmerce uses a filtered Shopify orders/paid webhook to attribute paid merchandise sales to cart lines created through Reelmerce. The production app requires read_orders.

• Webhook subscription is filtered to order lines containing the Reelmerce _sv_video line property.
• Requested webhook fields are minimized to identifiers, quantities, prices, discount allocations, presentment currency, timestamps, and Reelmerce line properties required for attribution.
• The referenced Reelmerce video handle is validated before storing attribution.
• Conversion Lab experiment context is retained only when experiment fields are complete and the referenced Saved design exists.
• Attributed amount uses the line's net merchandise value after line-level discount allocations and proportionally allocates the paid order subtotal across lines.
• Shipping, tax, and duties are excluded.
• Rows are deduplicated so webhook retries do not double-count the same order line/video attribution.
• Revenue reporting includes attributed orders, attributed lines, attributed units, and attributed paid sales by currency and by video.
• Reelmerce does not calculate advertising spend or ROAS.

16. Conversion Lab

Conversion Lab is an Unlimited-plan feature for comparing two Saved storefront designs on real storefront traffic.

17. Pricing and plan entitlements

Launch pricing uses Shopify App Pricing. Reelmerce verifies the merchant's active Shopify subscription and maps it to app entitlements.

17.1 Template access by plan

• Free: Social / Reels; Commerce card.
• Starter: Social / Reels; Commerce card; Carousel; Product-first.
• Growth: all eight templates.
• Unlimited: all eight templates.

18. Entitlement enforcement and downgrade behavior

• Published-video capacity counts only ACTIVE Reelmerce videos; Draft and Processing videos do not count.
• On verified downgrade above the new live-video limit, Reelmerce preserves the earliest published items and automatically moves newer excess videos to Draft in small batches.
• If plan verification is temporarily unavailable or stale, Reelmerce does not alter existing storefront content; it blocks new publishing until verification succeeds.
• Saved-design creation is blocked at the current limit; existing designs are not deleted automatically.
• If a design uses a template no longer included after downgrade, app warns and storefront uses Social / Reels fallback until compliant.
• Existing product tags remain stored after downgrade, but only the first tags within the current plan limit are active on storefront.
• Conversion Lab remains visible as an upgrade surface on lower plans; live A/B experiments require Unlimited.

19. Data and storage architecture

Production uses PostgreSQL. The application is hosted on Google Cloud Run and is configured for a production PostgreSQL/Cloud SQL deployment model.

20. Shopify integrations, permissions, and webhooks

20.1 Merchant-facing integrations

• Shopify Online Store and Theme Editor
• Shopify Products
• Shopify Files / Video
• Shopify Orders for paid-sales attribution
• Shopify App Pricing
• No third-party social-media account integration in current production release

20.2 Current OAuth scopes

Reelmerce uses Shopify GraphQL Admin APIs; the current pre-submission review found no REST Admin API usage.

20.3 Webhooks

The released Shopify webhook API version is 2026-10. The orders/paid webhook is filtered to Reelmerce-attributed line-item properties with minimized include_fields.

21. Privacy and data processing

21.1 Data Reelmerce processes

• Merchant/store operational data: shop identity, authorized session data, product/file/metaobject references, app configuration, plan state.
• Storefront analytics: shop, Reelmerce video handle, optional product/variant identifier, event type, optional cart-value amount, placement identifier, optional Conversion Lab experiment context, timestamp.
• Paid-order attribution: shop domain, Shopify order/line-item identifiers, product/variant identifiers, quantity, merchandise subtotal and discount amounts, presentment currency, order timestamp, Reelmerce video handle, placement identifier, optional Conversion Lab context.
• Browser-local state: liked/favorited Reelmerce video handles and Conversion Lab A/B letter per experiment.

21.2 Data Reelmerce does not request/store for paid attribution

• Customer name
• Customer email
• Customer phone number
• Postal address
• IP address
• Payment credentials or payment-card data

21.3 Purpose, retention, and deletion

• Data is used only for merchant-requested Reelmerce functionality, including analytics, performance ordering, attributed paid-sales reporting, and Conversion Lab reporting.
• Reelmerce does not sell this data or use it for third-party advertising.
• Storefront analytics and paid-order attribution records are retained for no more than 365 days for active app usage.
• Expired VideoEvent and RevenueAttribution rows are pruned during analytics and paid-order processing.
• Uninstall cleanup deletes app-side revenue attribution, analytics events, legacy video records, and sessions when available.
• Shopify shop/redact cleanup deletes remaining app-side revenue attribution, analytics events, legacy video records, and sessions for the shop.
• Mandatory Shopify privacy webhook routes are implemented.

21.4 Security

• Application traffic uses HTTPS/TLS.
• Production app data is stored in managed database infrastructure that supports encryption at rest.
• Access is limited to services required to operate Reelmerce.
• Reelmerce does not create a cross-store or cross-experiment customer profile for storefront analytics.

22. Performance and reliability strategy

• Theme app extension assets are delivered through Shopify's theme-extension/CDN pipeline.
• Reel video elements use preload='none' and visibility-driven playback.
• Recommended mode plays only the first five seconds on cards and reserves full playback for expanded viewer.
• Offscreen previews pause/reset; card playback is coordinated to reduce unnecessary simultaneous playback.
• View tracking begins only after a card reaches the 68% visibility threshold.
• Performance-ordering snapshots keep storefront sorting lightweight instead of calculating rankings in Liquid from raw events.
• Direct cart add supports common Shopify cart surfaces and has a product-page fallback.
• Analytics and order attribution use dedupe/validation safeguards and 365-day pruning.
• Shopify plan verification uses confirmed/stale caching and avoids destructive enforcement when verification is unavailable.

23. Current limitations / intentionally not offered

• No Instagram, TikTok, or YouTube import workflow in current production release.
• No collection-specific content filter; contextual filtering is product-page based.
• No server-side global like count or like analytics; likes are browser-local favorites.
• No automatic Conversion Lab winner selection.
• No advertising-spend tracking or ROAS calculation.
• No external checkout or payment gateway.
• No external merchant billing; paid plans use Shopify App Pricing.
• No direct theme-code mutation; placement uses a theme app extension/app block.
• No placement-count-based pricing guardrail.

24. Merchant FAQ

Do I need to edit theme code?

No. Add Reelmerce through the Shopify Theme Editor app block. Custom CSS is optional and placement-scoped.

Do I have to tag a product?

No. Product tagging is optional; video-only reels are supported.

Can one video tag multiple products?

Yes, within plan limit: Free 1, Starter 3, Growth 10, Unlimited unlimited.

What happens on product pages?

Current-product mode shows only videos tagged with that product and uses the matching product. In All mode, an untagged reel can use the current page product context.

What happens when a product is sold out?

Theme Editor can keep the video and disable CTA, or hide sold-out videos.

Can I use different designs on different pages?

Yes. Use Default or create Saved designs and select them per placement.

What is the five-second preview?

It loops only the first ~5 seconds of the original video on reel cards; full video plays after shopper opens the reel.

Does cart value mean revenue?

No. Added cart value is intent value. Attributed paid sales are reported separately from paid orders.

How does paid-sales attribution work?

Reelmerce carries cart-line metadata into the paid order and uses the filtered orders/paid webhook to attribute merchandise subtotal to valid Reelmerce lines.

Does Conversion Lab automatically pick a winner?

No. Each variant must reach at least 100 views before review; merchant makes the decision.

Are likes global?

No. The current Like control is browser-local and does not create a global count.

What happens after a downgrade?

Newer excess published videos are automatically moved to Draft after verified downgrade. Other plan limits are enforced without deleting stored content where possible.

25. Support / troubleshooting

26. Current product / App Store messaging source

27. Reviewer / App Store test path

1. Install and open Reelmerce from Shopify Admin. No external Reelmerce account is required.
2. Go to Videos and upload a supported video or choose one from Shopify Files.
3. Optionally tag products within plan limit and publish after Shopify processing is READY.
4. Open Widget Studio, choose an included template, customize layout/video/product/button/navigation/style/text settings, and save.
5. Optionally create a reusable Saved design.
6. Open Online Store → Themes → Customize and add the Reelmerce reels app block.
7. Choose content mode, inventory behavior, ordering, and placement settings; publish theme change.
8. Open storefront and verify playback, product CTA, direct add-to-cart, and product fallback.
9. Open Analytics and confirm engagement metrics and attributed paid sales after qualifying events/orders exist.
10. On Unlimited, choose two different Saved designs in Theme Editor, enable Conversion Lab, then review A/B results after traffic is recorded.

App Store listing, pricing, privacy, screenshots, reviewer instructions, and support content must match deployed behavior exactly.

28. Source-of-truth checklist before public reuse

• Confirm Shopify App Pricing handles/prices and entitlements still match Free / Starter / Growth / Unlimited.
• Confirm published-video limits: 5 / 25 / 100 / Unlimited.
• Confirm product-tag limits: 1 / 3 / 10 / Unlimited.
• Confirm Saved-design limits: 1 / 5 / 20 / Unlimited.
• Confirm template access: 2 / 4 / 8 / 8.
• Confirm analytics history: 7 / 30 / 90 / up to 365 days and Unlimited custom comparisons.
• Confirm Conversion Lab remains Unlimited-only with 100 views per variant review rule.
• Confirm read_orders and filtered orders/paid remain in released Shopify configuration.
• Confirm analytics and attribution retention remains 365 days.
• Confirm privacy page text/effective date match production.
• Confirm any future social import, global likes, collection filtering, or post-launch features before adding public claims.
• Confirm final support contact/legal entity details in App Store listing.
• Confirm listing screenshots use factual production UI or clearly identified illustrative/sample data.