PriceLedger User Guide
Everything you need to know about automated EU Omnibus Directive compliance, placing the storefront badge, and exporting audit records.
Quick Start & Installation
Getting your store connected and automatically logging prices in under 2 minutes.
PriceLedger installs directly through the Shopify App Store with zero coding required. Upon installation, the app performs an automated initial synchronization to capture existing variant prices as baseline records.
The app requests two standard Shopify access scopes: `write_products` (to update the lowest price metafield on your product variants) and `read_themes` (to verify your active theme and detect the storefront app block).
Step-by-step instructions:
Install from the Shopify App Store
Visit the PriceLedger listing in the Shopify App Store and click 'Install'. Review the standard read/write permissions and approve the installation.
Automated Store Registration & Initial Sync
Once authorized, PriceLedger instantly registers your store in our compliance database, establishes your store's install timestamp anchor, and initiates automated price logging.
Add the Storefront Badge
Navigate to the Theme Editor and drag the PriceLedger Compliance Badge block directly below your product price.
Automated Background Operation
Once installed, PriceLedger runs entirely in the background. You do not need to keep the admin app open for price changes to be logged.
Adding & Positioning the Storefront Badge
How to add the compliance badge to your product pages using the Shopify Theme Editor.
Under the EU Omnibus Directive (Article 6a), whenever a product is offered at a discounted price, shoppers must clearly see the prior lowest price applied within a period of at least 30 days.
The PriceLedger storefront badge is an Online Store 2.0 Theme App Block that renders cleanly without layout shifts or slowing down page load times. It only displays when a product variant has an active discount (`compare_at_price > price`).
Step-by-step instructions:
Open the Shopify Theme Editor
From your Shopify Admin, go to Online Store → Themes, click 'Customize' on your active theme, and open any Product page template (Default product).
Add App Block to Product Information
In the left sidebar under the 'Product information' section, click '+ Add block', switch to the 'Apps' tab, and select 'Compliance Badge (PriceLedger)'.
Recommended Placement: Directly Below the Price
Drag the Compliance Badge block directly underneath the default 'Price' block. EU consumer protection guidelines recommend placing the 30-day baseline price in close proximity to the current sale price so shoppers can immediately verify the discount.
Customize Styling Settings
Click the badge block in the Theme Editor sidebar to adjust font size, top/bottom margin spacing, text alignment (left, center, right), and text color to match your store's brand typography.
Shopify Theme Editor: Badge Block Placement
[ Screenshot Asset Placeholder ]
Recommended placement of the PriceLedger Compliance Badge directly below the main Product Price block in the Theme Editor.
Placement Recommendation
Placing the compliance badge directly below or adjacent to the sale price provides the highest clarity for EU shoppers and ensures full compliance with consumer transparency regulations.
Automatic Hide on Non-Sale Items
The badge is smart: if an item is sold at its regular price without a discount, the block remains invisible and takes up 0px of space.
The 30-Day Cold Start Period
Understanding the initial 30 days after installation and how legal compliance is maintained.
When you first install PriceLedger, the app begins logging prices from day one. However, by definition, the app does not have 30 days of historical data on day 1.
To prevent merchants from making misleading 'lowest in 30 days' claims before 30 days of data exist, PriceLedger implements an intelligent, legally vetted Cold Start mechanism.
Step-by-step instructions:
Days 1 to 29 (Cold Start Period)
During the first 29 days after installation, if a product is put on sale, the badge displays: 'Lowest price since tracking began: €85.00'. This informs shoppers and EU regulators of the exact verified historical floor without making an unverified 30-day claim.
Day 30 and Beyond (Full Compliance)
Exactly 30 days after your install date, the badge automatically transitions to: 'Lowest price in the last 30 days: €85.00'. No manual action or theme reconfiguration is required.
Why this matters legally
Under EU consumer protection rules, advertising a '30-day lowest price' when tracking started 3 days ago can be deemed misleading advertising. PriceLedger's dual-anchor logic protects your store from regulatory fines from day one.
Automated Price Tracking Pipeline
How background workers calculate and update the 30-day lowest price on autopilot.
Every time you update a product or variant price in your Shopify Admin, via CSV import, or through an ERP/inventory tool, Shopify fires a secure `products/update` webhook to PriceLedger.
Our distributed background workers process this event within milliseconds, compute the historical lookback, and write the verified lowest price into a dedicated Shopify metafield (`priceledger.lowest_price`).
Step-by-step instructions:
Webhook Ingestion & Idempotency
The incoming payload is verified via Shopify HMAC signature. Duplicate webhooks sent by Shopify within seconds are safely deduped using SHA-256 payload hashing.
30-Day Prior Lookback Calculation
PriceLedger queries all logged prices for that variant strictly *prior* to the moment the current discount was applied. If today's sale price is €79.00 and the lowest price over the past 30 days was €85.00, the baseline is set to €85.00.
Metafield Synchronization
The calculated lowest price is stored as an integer subunit metafield on the variant, allowing the Liquid theme block to render instantly without client-side API requests.
Multi-Currency & International Stores
PriceLedger natively handles multi-currency stores, 0-decimal currencies (JPY, KRW), standard 2-decimal currencies (EUR, USD, GBP), and 3-decimal currencies (KWD, BHD, JOD) with zero rounding loss.
App Lifecycle: Uninstalls, Reinstalls & GDPR
What happens to your store's data, price logs, and compliance records during lifecycle events.
We believe in total transparency regarding your store data. PriceLedger is engineered with strict lifecycle state machines to ensure compliance with both EU trade laws and GDPR requirements.
Step-by-step instructions:
When You Uninstall the App
Background queue workers stop immediately for your store, all access tokens and active sessions are wiped from the server, and the storefront badge stops rendering. Historical price logs are securely preserved for 60 days so you have audit records if an EU consumer authority audits a past promotional campaign.
When You Reinstall the App
If you reinstall within 60 days, PriceLedger recognizes your store domain, reconnects your historical price logs, restores your install coverage anchors, and immediately resumes price tracking without starting from scratch.
GDPR Store Redaction (shop/redact)
When you permanently close your Shopify account or request data erasure via Shopify, Shopify sends a GDPR `shop/redact` webhook. PriceLedger permanently deletes all store records, settings, and price logs within 48 hours in full compliance with GDPR Article 17.
60-Day Legal Retention Guarantee
EU consumer protection laws allow authorities to investigate promotional pricing retroactively. Our 60-day post-uninstall retention safeguards you against compliance inquiries after promotional events.
Plans & Variant Tracking Limits
How plan tiers work, variant limits, and automated limit notifications.
PriceLedger offers transparent pricing based on the total number of product variants tracked in your store. Every plan includes full EU Omnibus compliance, real-time logging, and audit exports.
Step-by-step instructions:
Free Plan (Up to 200 Variants)
Ideal for boutique stores, single-product brands, and emerging merchants. Completely free forever with all core compliance features enabled.
Growth Plan ($14/month — Up to 2,500 Variants)
Designed for growing Shopify stores with diverse product catalogs, seasonal collections, and multi-option apparel.
Pro Plan ($29/month — Unlimited Variants)
Built for high-volume retailers, large catalog merchants, and enterprise stores tracking tens of thousands of variants.
What happens if you exceed your plan limit?
Existing tracked variants continue to be tracked normally. However, new variant price updates beyond your plan limit will be skipped until you upgrade. An alert banner appears in your dashboard notifying you if catalog growth exceeds your current tier.
Audit Log & Legal Proof Export
Searching historical price logs and generating timestamped CSV exports for regulatory authorities.
The Audit Log in your PriceLedger dashboard acts as an immutable ledger of every price change recorded for your store. If an EU market surveillance authority requests evidence of prior promotional pricing, you can export certified records in seconds.
Step-by-step instructions:
Search and Filter by SKU or Product Title
In the PriceLedger Admin → Audit Log, use the search bar to locate specific products, variants, or SKUs. Filter by sync status (Success, Pending, Failed).
Inspect Historical Price Trajectory
Each row displays the recorded timestamp (UTC), previous price, new price, compare-at price, and the calculated 30-day lowest baseline.
One-Click CSV Export
Click the 'Export CSV' button to download a standardized CSV file formatted specifically for regulatory compliance audits.
PriceLedger Admin: Audit Log & CSV Export
[ Screenshot Asset Placeholder ]
Reviewing recorded price events and exporting compliant CSV audit reports in the PriceLedger admin interface.
Export Format Standards
The CSV export includes ISO-8601 UTC timestamps, product IDs, variant IDs, SKU codes, monetary subunit values, and currency symbols.
Troubleshooting & Frequently Asked Questions
Answers to common merchant questions and troubleshooting steps.
Here are solutions to the most common configuration and storefront display questions.
Step-by-step instructions:
Why is the badge not appearing on my product page?
1. Ensure the product variant is currently on sale with 'Compare-at price' greater than 'Price'. 2. Confirm the Compliance Badge app block is added to the active Product template in the Theme Editor. 3. Make sure the theme template is saved and published.
Does PriceLedger work with custom or headless storefronts?
PriceLedger writes the calculated lowest price directly to standard Shopify variant metafields (`priceledger.lowest_price`). Headless storefronts (Hydrogen, Next.js, Gatsby) can read this metafield directly via the Storefront GraphQL API.
How do I contact customer support?
Need help with setup, custom theme styling, or compliance questions? Contact our dedicated support team at [email protected].
Need custom theme styling?
If your store uses a custom theme layout, you can adjust the badge's CSS directly in the Theme Editor block settings or reach out to support for personalized CSS assistance.