Today, we're opening API access.

What the API gives you​

The Valcr Data API serves the same benchmark intelligence that powers the Valcr platform — but programmatically, via authenticated HTTP endpoints, into whatever system you're building or operating.

That means:

• Benchmark percentiles — gross margin, revenue growth, LTV:CAC, cart abandonment, AOV, refund rate, and more, broken down by category and segment, updated quarterly
• Merchant VCFS profiles — submit and retrieve structured financial data in the Valcr Commerce Financial Schema
• Peer comparisons — rank a merchant's metrics against their actual peer group, not an industry average from a year-old report
• AI-generated insights — causal narratives that explain why a metric sits where it does, not just where it sits
• XBRL export — structured, taxonomy-tagged financial documents for audit, filing, and ERP integration

All of it behind a single base URL: https://api.valcr.site/data/v1

Who this is for​

We built this for three audiences:

Lenders and underwriters who need to contextualise a merchant's financials within their real peer group — not a national average, but a p25/p50/p75 distribution computed from verified data from comparable businesses in the same segment.

SaaS platforms and fintech developers who want to embed benchmark intelligence inside their own products without building or maintaining the underlying dataset. You plug in the API; your users see the intelligence.

Commerce operators and their teams who want programmatic access to their own VCFS profile, their Valcr Score, and their benchmark position — integrated into internal dashboards, underwriting pipelines, or investor reporting tools.

How it works​

Authentication is via bearer tokens. Create an API key in the Console, assign the scopes your integration needs, and you're making requests in under two minutes.

curl -X GET "https://api.valcr.site/data/v1/benchmarks?category=ecommerce" \
  -H "Authorization: Bearer vcr_live_your_key_here"

{
  "category": "ecommerce",
  "period": "2024-Q4",
  "metrics": {
    "gross_margin":   { "p25": 0.28, "p50": 0.41, "p75": 0.58, "p90": 0.67 },
    "revenue_growth": { "p25": 0.04, "p50": 0.12, "p75": 0.26, "p90": 0.48 }
  },
  "sample_size": 4812
}

The keys are scoped. You choose the access level you need — read-only benchmark access at $29/month, or full merchant intelligence with XBRL export at Enterprise tier. Every key is hashed server-side immediately after creation; we never store the raw value.

The VCFS layer​

Everything in the API is built on the Valcr Commerce Financial Schema — a canonical data model that maps the financial structures from Shopify, Amazon, WooCommerce, QuickBooks, and public filings into a single consistent representation.

VCFS is the reason the benchmarks are comparable. Without normalisation at the schema level, you're comparing numbers that were calculated differently, for different time periods, with different field definitions. The value of benchmark data scales directly with the rigour of the normalisation underneath it.

You can read the full VCFS schema documentation here.

What's next​

The dataset grows every month. Every new connected store, every public filing, every data partnership deepens the benchmark distributions and makes the percentiles more credible. That compounding is the fundamental thesis of the platform.

In the near term:

• Shopify and Amazon SP-API direct integrations for automated VCFS population
• Monthly benchmark updates (currently quarterly)
• Expanded geography coverage beyond US and UK
• Enterprise SLA and dedicated support tier

Create a free Console account and make your first request today. The Quickstart guide will get you there in under two minutes.

Questions or integration support: api@valcr.site

The problem is not the volume. The problem is that none of it speaks the same language.

The fragmentation problem​

Ask ten ecommerce operators what their gross margin is and you will get ten different answers — not because their businesses are different, but because they calculated it differently.

Some include shipping as cost of goods. Some don't. Some report net revenue after returns; others report gross. Some count a customer as "active" if they've purchased in the last 90 days; others use 12 months. Cart abandonment rate means something slightly different in every analytics platform that reports it.

This isn't a data problem. It's a schema problem. There is no agreed standard for what these numbers mean and how they should be calculated — so any comparison across merchants is, at best, approximate.

For an operator benchmarking their business, this is inconvenient. For a lender underwriting a merchant, it is a risk. For an investor evaluating a portfolio company against its peers, it quietly degrades every decision they make.

What VCFS does​

The Valcr Commerce Financial Schema is a canonical data model that maps every significant financial metric in ecommerce to a single, precisely defined field with a documented calculation methodology.

Every record that enters Valcr — from a connected Shopify store, an Amazon Seller Central account, an SEC filing, a Companies House submission, or a manual upload — is normalised to the same structure.

The same field names. The same calculation logic. The same confidence score.

{
  "revenue": {
    "gross_revenue":  480000,
    "net_revenue":    432000,
    "currency":       "USD"
  },
  "margins": {
    "gross_margin":     0.52,
    "operating_margin": 0.14,
    "net_margin":       0.09
  },
  "customers": {
    "active_customers":          3840,
    "average_order_value":       125,
    "customer_ltv":              310,
    "customer_acquisition_cost": 48,
    "cart_abandonment_rate":     0.66,
    "repeat_purchase_rate":      0.38
  }
}

The definitions matter. VCFS specifies:

• gross_margin = (net_revenue - COGS) / net_revenue — not revenue minus all costs, not including shipping as COGS unless it's a core fulfilment cost
• active_customers = unique customers with at least one order in the reporting period — not monthly actives, not email list size
• cart_abandonment_rate = abandoned_carts / initiated_carts where "initiated" means at least one item added — not page views on the cart

These distinctions sound pedantic. In practice, they are the difference between a benchmark that means something and a number that sounds authoritative but is actually noise.

Why XBRL​

VCFS maps directly to XBRL taxonomy elements. This is not an accident.

XBRL (eXtensible Business Reporting Language) is the global standard for structured financial data exchange — the format used by the SEC, Companies House, and financial regulators in over 50 jurisdictions. When a company files with the SEC, the data is tagged in XBRL so systems can automatically process and compare it without parsing prose documents.

By anchoring VCFS to XBRL, Valcr makes it possible to:

• Export merchant financial data as a standards-compliant XBRL document for regulatory submission or audit
• Compare ecommerce operator data directly against public company filings in the same taxonomy
• Integrate into ERP and accounting systems that already speak XBRL

The XBRL export endpoint takes a merchant's VCFS submission and returns a fully tagged XBRL instance document. Validated against our published taxonomy. Readable by any XBRL processor.

The benchmark value chain​

The reason VCFS matters for benchmarking specifically is this: the value of a percentile distribution is entirely dependent on the consistency of the underlying data.

If your benchmark says the median gross margin for ecommerce fashion businesses is 44%, that number is only useful if every business in the sample calculated gross margin the same way. If half of them included fulfilment costs and half didn't, the 44% is a blend of two different things — and benchmarking against it tells you almost nothing.

VCFS eliminates that uncertainty. Every merchant in the Valcr benchmark pool has had their data normalised to the same schema with the same calculation rules. The p50 means the median of businesses where gross margin was calculated identically. That's what makes it a useful number.

Getting started with VCFS​

If you're a developer integrating Valcr into a platform, start with the VCFS Schema guide — it documents every field, the calculation methodology, and the completeness scoring system that indicates how much of the schema a given merchant submission covers.

If you're an operator, the completeness score is worth understanding. VCFS submissions are scored 0–1. Higher completeness unlocks more granular benchmarking, AI insights, and the Valcr Score composite. A minimum viable submission (net revenue + gross margin) scores around 0.30. A fully populated profile with customer economics and channel breakdown scores above 0.85 and unlocks XBRL export.

The schema is open. The benchmark data that results from it is proprietary — and becomes more valuable with every additional record that enters the normalisation pipeline.

Read the full VCFS schema documentation →

The Valcr Score was designed with that danger front of mind. Here's exactly how it's constructed — and why.

What the score is​

The Valcr Score is a 0–100 composite that summarises a merchant's financial performance relative to their peer group in five dimensions. It is not an absolute measure of business quality. It is a relative measure — a percentile-anchored position within a defined comparison group.

A score of 74 means: across these five dimensions, this merchant outperforms approximately 74% of comparable businesses in the same category and segment.

That framing matters. A score of 74 for a $500K/year fashion DTC brand and a score of 74 for a $10M/year marketplace operator are not comparable — but both say something precise about where each business sits within its actual peer group.

The five components​

Valcr Score = weighted average of 5 component scores

Revenue Quality          25%
Margin Health            25%
Growth Trajectory        20%
Customer Economics       20%
Operational Efficiency   10%

Revenue Quality (25%)​

Evaluates the composition and reliability of the revenue base:

• Recurring revenue share (subscription, membership, replenishment)
• Channel concentration risk (overdependence on a single platform)
• Net revenue retention where applicable
• Revenue consistency across the trailing period

A business with 60% direct-channel revenue, 20% Amazon, and meaningful subscription revenue scores higher on revenue quality than one that is 90% Amazon with no recurring component — even if the gross numbers are identical. The former is more defensible.

Margin Health (25%)​

Gross margin percentile within peer group, adjusted for category norms. A 35% gross margin means something very different for an electronics seller (above median) than for a beauty brand (well below median). VCFS normalisation ensures these comparisons are valid.

Operating margin and net margin contribute when the data is available with sufficient confidence score (≥ 0.7 on the VCFS completeness scale).

Growth Trajectory (20%)​

Revenue growth rate (QoQ and YoY) benchmarked against category peers. A 15% YoQ growth rate might be strong for a mature retail category and weak for an early-stage DTC brand growing in a fast-moving segment. The benchmark distribution makes this contextual.

Unit growth (order volume, SKU count expansion) is incorporated where available as a leading indicator when revenue growth lags.

Customer Economics (20%)​

The most predictive component for long-term business health:

• LTV:CAC ratio percentile — the ratio of lifetime value to acquisition cost, benchmarked within segment
• Repeat purchase rate vs. peer median
• Cart abandonment rate (inverted — lower is better)
• Average order value trend

A business with a 6:1 LTV:CAC ratio, a 42% repeat purchase rate, and declining cart abandonment scores very well on this component regardless of where it sits on revenue or margin.

Operational Efficiency (10%)​

Fulfilment quality and return economics:

• Refund/return rate percentile (inverted)
• Fulfilment rate (orders delivered on time)
• Average delivery time vs. category benchmark

Weighted at 10% because operational metrics are often outside the merchant's direct control (carrier-dependent, geography-dependent) and are more volatile quarter-to-quarter.

Grade bands​

What it is not​

The Valcr Score is not a credit score. It does not incorporate repayment history, days outstanding, or liability structure. Lenders using Valcr data for underwriting combine the score with their own credit assessment — the score provides peer-relative financial context that their models typically lack, not a complete credit decision.

The score is not static. It is recalculated each time a new VCFS submission is processed, and the benchmark pool it draws from is updated quarterly. A score from six months ago reflects the merchant's position at that time relative to the peer group as it was constituted then.

Accessing the score​

The Valcr Score is available on Enterprise plans via the GET /merchant/score endpoint. It requires a VCFS completeness score of at least 0.70 to compute reliably.

The response includes not just the composite score but the individual component scores, the peer percentile rank, and the quarter-over-quarter trend — so the number is always accompanied by enough context to be genuinely useful.

{
  "valcr_score": 74,
  "grade": "B+",
  "components": {
    "revenue_quality":        { "score": 81, "weight": 0.25 },
    "margin_health":          { "score": 76, "weight": 0.25 },
    "growth_trajectory":      { "score": 68, "weight": 0.20 },
    "customer_economics":     { "score": 71, "weight": 0.20 },
    "operational_efficiency": { "score": 62, "weight": 0.10 }
  },
  "peer_percentile": 68.2,
  "trend": { "prev_score": 70, "delta": 4, "direction": "up" }
}

See the full score endpoint documentation →

Key generation​

Every Valcr API key is generated using Python's secrets.token_urlsafe(36) — a cryptographically secure random string drawing from /dev/urandom, producing 48 characters of URL-safe base64 encoding from 36 bytes of randomness.

That gives each key approximately 287 bits of effective entropy. For context, the absolute minimum considered adequate for API keys is 128 bits. 287 bits makes brute-force enumeration computationally infeasible for any foreseeable future.

Keys are prefixed with the environment:

vcr_live_xKj9RzMnP4qBvWsY...  ← production
vcr_test_aB2cDeFgHiJkLmNo...  ← sandbox

The prefix serves a practical purpose: it makes keys identifiable in logs, in code review, and in leaked credential scanning tools (similar to how GitHub tokens begin ghp_ and Stripe keys begin sk_live_). GitHub's secret scanning automatically flags patterns like these before they reach production.

What we store — and what we don't​

This is the critical decision. When you create an API key in the Valcr Console, the sequence is:

1. raw_key = f"vcr_{env}_{secrets.token_urlsafe(36)}"
2. key_hash = hashlib.sha256(raw_key.encode()).hexdigest()
3. Store key_hash in the database
4. Return raw_key in the API response — once, immediately
5. Discard raw_key from memory

We store the SHA-256 hash. We never store the raw key. After the creation response is returned, no system at Valcr holds the raw value — not the database, not logs, not application memory.

The consequence is intentional: if our database were completely compromised, the attacker gets a list of SHA-256 hashes with no practical path to recovering the raw keys. A 287-bit random value is not susceptible to rainbow table attacks or dictionary attacks.

The user consequence is also intentional: if you lose the key, it must be rotated. There is no "show me my key again" feature because there is no copy to show.

Why SHA-256 and not bcrypt?​

bcrypt is the right choice for passwords because passwords have low entropy — humans choose predictable strings from a limited character set, which makes offline dictionary attacks viable against unsalted or weakly salted hashes.

API keys with 287 bits of entropy are not susceptible to dictionary attacks. The computation overhead of bcrypt on every API request (which requires a hash lookup on every authenticated call) introduces unnecessary latency with no security benefit. SHA-256 lookup in an indexed database column is fast, correct, and appropriate.

Validation on every request​

Every authenticated request to the Data API runs this sequence:

1. Extract token from Authorization: Bearer <token>
2. Compute SHA-256(token)
3. SELECT * FROM api_keys WHERE key_hash = $1 AND is_active = true
4. Check: key.environment matches request target
5. Check: required_scope ∈ key.scopes
6. Check: rate limit (per key, sliding window)
7. Check: account quota (per billing period)
8. Forward to handler

Steps 4–7 all happen before the request reaches any business logic. A request that fails any check never touches the data layer.

The hash lookup uses a database index on key_hash. Combined with the fixed-length output of SHA-256 (64 hex characters), this is a single indexed equality scan — consistently fast regardless of dataset size.

Scope enforcement​

Scopes follow the pattern resource:action and are stored as an array on the key record. The endpoint-to-scope mapping is maintained in the application layer:

ENDPOINT_SCOPE_MAP = {
    "GET /benchmarks":              "benchmarks:read",
    "GET /benchmarks/percentile":   "benchmarks:read",
    "GET /segments":                "segments:read",
    "GET /merchant/vcfs":           "merchant:read",
    "POST /merchant/vcfs":          "merchant:write",
    "GET /merchant/insights":       "insights:read",
    "GET /merchant/score":          "score:read",
    "GET /export/xbrl":             "export:read",
}

If the scope is not present on the key, the request returns 403 Forbidden — not 401 Unauthorized. This distinction is deliberate: 401 means "not authenticated," 403 means "authenticated but not permitted." The difference helps integration developers understand whether they have a key problem or a scope problem.

Key rotation​

Rotation is the recommended response to any suspected key exposure — or simply as a regular security hygiene practice (every 90 days is reasonable for production integrations).

When a key is rotated:

1. A new raw key is generated with the same process as creation
2. The key_hash column on the existing record is overwritten atomically with the new hash
3. The old hash is gone — immediately invalid
4. The new raw key is returned in the rotation response — once

The atomic overwrite means there is no window where both the old and new key are simultaneously valid. The trade-off is that any in-flight requests using the old key at the moment of rotation will fail. For production systems where this matters, coordinate rotations with a low-traffic window or implement a brief retry on 401.

What this means for your integration​

A few practical implications:

Store keys in environment variables, never in code. A key committed to a git repository is compromised — even if the repo is private, even if you delete the commit. Environment variables keep credentials out of version control entirely.

Use test keys during development. Test keys (vcr_test_*) return seeded data and never count against your quota or trigger billing. There is no reason to use a live key in a development or CI environment.

Assign minimum required scopes. If your integration only reads benchmarks, create a key with only benchmarks:read. A compromised key with minimal scopes has minimal blast radius.

Rotate if in doubt. Rotation takes 30 seconds in the Console. If a key was ever logged, ever appeared in an error message, ever shipped in a build artifact — rotate it. The old key is invalidated immediately.

Read the full authentication documentation →

Here is what the Q4 2024 Valcr benchmark data shows across categories — and more importantly, what the distributions reveal that headline averages hide.

The data​

Q4 2024 benchmark pool: 8,420 ecommerce merchants across seven sub-segments, with VCFS completeness scores of ≥ 0.50 (sufficient confidence for margin benchmarking).

All gross margin figures use the VCFS definition: (net_revenue - COGS) / net_revenue, where COGS excludes fulfilment and shipping unless it is a direct cost of the physical product.

By sub-segment​

What the distribution reveals​

The spread is the story​

The median is useful context. The distribution is where the real information lives.

Take fashion and apparel: the median is 44%, but the p25 is 31% and the p90 is 68%. That is a 37-point spread between the bottom quarter and the top 10% of the segment. A fashion brand at 44% is not doing well — it is average. A fashion brand at 62% is genuinely exceptional and likely has a structural advantage (direct-to-consumer with minimal marketplace dependency, owned manufacturing, or premium positioning with pricing power).

For underwriters: a fashion brand presenting a 31% gross margin is at the 25th percentile. Not a red flag on its own — a quarter of the segment sits there — but it warrants understanding why. Is it channel mix (heavy Amazon dependency eroding margin through fees)? Product category within fashion (accessories vs. basics)? Season-specific COGS inflation?

Beauty's structural advantage​

Beauty and personal care's 61% median is not an accident. The category benefits from:

• High perceived value at low material cost — a $40 serum with $4 of formulation is structurally different from a $40 electronics accessory that cost $28 to manufacture
• Direct channel dominance — beauty has the highest own-website share of any ecommerce category in the Valcr dataset (64% median vs. 41% for fashion and 28% for electronics)
• Replenishment economics — products that run out create recurring revenue without the acquisition cost overhead that compresses margin in single-purchase categories

Electronics' structural compression​

Electronics trails every category at 28% median. The reasons are well understood but worth stating precisely:

• Commodity component pricing — electronics COGS is high relative to retail price, and component costs are transparent (competitive reference pricing exists for almost every component)
• Marketplace dependency — electronics has the highest Amazon revenue share in the dataset (median 44% of revenue through Amazon), and Amazon's referral fees (6–8% for electronics) directly compress margin before operating costs
• Price comparison pressure — price comparison tools make premium positioning structurally difficult; most SKUs trade at near-identical prices across platforms

A well-run electronics operation at 41% gross margin (p75) has likely achieved either category specialisation (professional/B2B equipment with lower competition and lower price comparison pressure) or meaningful private-label positioning.

Quarter-over-quarter trend​

Comparing Q3 2024 to Q4 2024 across the full ecommerce pool:

The 1pp uplift at all percentiles in Q4 reflects two things: seasonal pricing power (premium pricing during peak gifting season) and sample composition shift (Q4 skews toward fashion and beauty in the dataset as Amazon sellers activate holiday inventory).

Using the API​

All of this data is available programmatically via the Valcr Data API:

import requests

r = requests.get(
    "https://api.valcr.site/data/v1/benchmarks",
    headers={"Authorization": "Bearer vcr_live_your_key"},
    params={"category": "ecommerce", "segment": "fashion", "period": "2024-Q4"},
)
data = r.json()
gm = data["metrics"]["gross_margin"]
print(f"p50: {gm['p50']:.1%}  p75: {gm['p75']:.1%}  p90: {gm['p90']:.1%}")
# → p50: 44.0%  p75: 59.0%  p90: 68.0%

To rank a specific merchant's gross margin against the distribution:

r = requests.get(
    "https://api.valcr.site/data/v1/benchmarks/percentile",
    headers={"Authorization": "Bearer vcr_live_your_key"},
    params={"metric": "gross_margin", "value": 0.52, "category": "ecommerce", "segment": "fashion"},
)
result = r.json()
print(f"{result['percentile']:.0f}th percentile")  # → 71st percentile

Access the benchmarks API → · Get a free Console account →

Data from the Valcr benchmark pool, Q4 2024. N=8,420. All figures use VCFS-normalised calculation methodology.

It's a simple question. Building an answer to it is not. You need a dataset of comparable businesses, a consistent normalisation methodology, regular updates, and enough sample depth per segment to produce credible distributions. Most SaaS companies decide the build cost isn't worth it and ship a chart with industry averages from a three-year-old report instead.

The Valcr API exists specifically to solve this. Here's how to integrate it.

The integration pattern​

The core pattern is straightforward:

1. Your user's financial data lives in your platform (or you calculate it from transactions)
2. You call the Valcr API to get the benchmark distribution for their category and metric
3. You call the percentile endpoint to rank their specific value
4. You render the result — a chart, a badge, a scorecard, whatever fits your UI

You don't need to move user data to Valcr's servers unless you want to use the VCFS profile features. The benchmark endpoints are read-only lookups against the Valcr dataset — you bring the merchant's metric, Valcr tells you where it sits.

Step 1: Create a server-side API key​

Create a key with benchmarks:read and segments:read scopes in the Console. Store it as an environment variable on your backend. Never expose it client-side.

VALCR_API_KEY=vcr_live_your_key_here

Step 2: Build a benchmark lookup function​

# Python / FastAPI backend

import os, requests
from functools import lru_cache

VALCR_BASE = "https://api.valcr.site/data/v1"
VALCR_KEY  = os.environ["VALCR_API_KEY"]
HEADERS    = {"Authorization": f"Bearer {VALCR_KEY}"}

@lru_cache(maxsize=128)
def get_benchmark_distribution(category: str, metric: str, period: str = None):
    """Cache benchmark distributions — they update quarterly, not per-request."""
    params = {"category": category, "metric": metric}
    if period: params["period"] = period
    r = requests.get(f"{VALCR_BASE}/benchmarks", headers=HEADERS, params=params)
    r.raise_for_status()
    return r.json()["metrics"][metric]

def get_merchant_percentile(category: str, metric: str, value: float):
    r = requests.get(
        f"{VALCR_BASE}/benchmarks/percentile",
        headers=HEADERS,
        params={"category": category, "metric": metric, "value": value},
    )
    r.raise_for_status()
    return r.json()

# Usage in your route handler:
@app.get("/api/merchant/{merchant_id}/benchmark")
async def merchant_benchmark(merchant_id: str, metric: str = "gross_margin"):
    merchant = await db.get_merchant(merchant_id)
    merchant_value = merchant.calculate_metric(metric)  # your own calculation

    distribution = get_benchmark_distribution(merchant.category, metric)
    rank = get_merchant_percentile(merchant.category, metric, merchant_value)

    return {
        "metric":        metric,
        "merchant_value": merchant_value,
        "percentile":    rank["percentile"],
        "distribution":  distribution,
        "interpretation": rank["interpretation"],
    }

// TypeScript / Next.js API route

const VALCR_BASE = "https://api.valcr.site/data/v1"
const HEADERS    = { Authorization: `Bearer ${process.env.VALCR_API_KEY}` }

// Cache with a simple in-memory map — distributions update quarterly
const distributionCache = new Map<string, { data: any; ts: number }>()
const CACHE_TTL = 6 * 60 * 60 * 1000  // 6 hours

async function getBenchmarkDistribution(category: string, metric: string) {
  const key = `${category}:${metric}`
  const cached = distributionCache.get(key)
  if (cached && Date.now() - cached.ts < CACHE_TTL) return cached.data

  const res = await fetch(
    `${VALCR_BASE}/benchmarks?category=${category}`,
    { headers: HEADERS }
  )
  const data = await res.json()
  const dist = data.metrics[metric]
  distributionCache.set(key, { data: dist, ts: Date.now() })
  return dist
}

export async function GET(req: Request) {
  const { searchParams } = new URL(req.url)
  const category = searchParams.get("category") ?? "ecommerce"
  const metric   = searchParams.get("metric")   ?? "gross_margin"
  const value    = parseFloat(searchParams.get("value") ?? "0")

  const [distribution, rank] = await Promise.all([
    getBenchmarkDistribution(category, metric),
    fetch(`${VALCR_BASE}/benchmarks/percentile?category=${category}&metric=${metric}&value=${value}`, { headers: HEADERS })
      .then(r => r.json()),
  ])

  return Response.json({ distribution, rank })
}

Step 3: Cache aggressively​

Benchmark distributions update quarterly. Hitting the Valcr API on every page load for benchmark data is wasteful and unnecessary. Cache at the application layer:

• Distribution data (/benchmarks) — cache for 6–24 hours. The data doesn't change intra-day.
• Percentile lookups (/benchmarks/percentile) — cache per merchant, per metric, per period. Recalculate when the merchant's own metrics update.
• Segment lists (/segments) — cache for 24+ hours. New segments are added quarterly.

This also means your Valcr API quota goes almost entirely to percentile lookups (one per merchant metric update) rather than distribution fetches — making the economics of embedding benchmarks very favourable even at Developer tier.

Step 4: Design the UI​

The most effective benchmark visualisations are not pie charts. They are distribution charts with the merchant's position marked — showing where they sit, who they're near, and what the top quartile looks like.

A minimal implementation:

// React component — benchmark position visualiser

function BenchmarkBar({ metric, merchantValue, distribution }) {
  const pct = (v: number) => `${(v * 100).toFixed(0)}%`
  const merchantPct = distribution.p50
    ? Math.min(Math.round((merchantValue / distribution.p90) * 90), 100)
    : 50

  return (
    <div className="benchmark-bar">
      <div className="bar-track">
        <div className="bar-zone p25-p75" style={{
          left:  pct(distribution.p25 / distribution.p90),
          width: pct((distribution.p75 - distribution.p25) / distribution.p90),
        }} />
        <div className="bar-median" style={{ left: pct(distribution.p50 / distribution.p90) }} />
        <div className="bar-merchant" style={{ left: `${merchantPct}%` }}>
          <span className="merchant-label">{pct(merchantValue)}</span>
        </div>
      </div>
      <div className="bar-labels">
        <span>p25: {pct(distribution.p25)}</span>
        <span>Median: {pct(distribution.p50)}</span>
        <span>p75: {pct(distribution.p75)}</span>
      </div>
    </div>
  )
}

The middle 50% (p25–p75) shaded, the median marked, the merchant's position as a pin. Users immediately understand where they sit without needing to read a number.

What you don't need to build​

Using the Valcr API for benchmarking means you don't have to:

• Recruit a benchmark panel of comparable businesses
• Design and maintain a data normalisation pipeline
• Decide how to handle outliers and sample size minimums
• Update the data every quarter
• Handle the methodology questions that users inevitably ask ("how was this calculated?")

The methodology is documented in the VCFS schema guide and benchmark API reference. Your users can read it. You didn't have to write it.

Start with the Quickstart → · API key scopes reference →

The problem: that number didn't come from a distribution. It came from a SaaS heuristic from the early 2010s, applied to a subscription business model, and has since been cargo-culted onto every business model in the internet economy regardless of whether it makes sense.

Here is what the actual data shows.

First: how Valcr calculates LTV:CAC​

VCFS defines these fields precisely because imprecision makes the ratio meaningless:

Customer LTV = projected net revenue from a customer over their lifetime with the business. Valcr uses a cohort-based calculation where available: average_order_value × purchase_frequency × gross_margin × (1 / churn_rate). Where churn data is unavailable, a simplified version using trailing 12-month repeat purchase rates is used, with a confidence score adjustment applied to the benchmark.

Customer Acquisition Cost = total marketing and sales spend in the period divided by new customers acquired. "Total" means all paid channels, all agency fees, all content production costs attributed to acquisition. Not just ad spend.

The ratio = customer_ltv / customer_acquisition_cost.

If your platform calculates these differently, your ratio is not comparable to the benchmark. This is not a criticism — it is a measurement problem that VCFS exists to solve.

What the data shows​

From the Q4 2024 Valcr dataset, LTV:CAC ratio by ecommerce category:

The ecommerce-wide p50 is 3.8:1 — above the 3:1 baseline. But that aggregate masks enormous variation across categories.

The 3:1 myth in context​

A fashion brand with a 3.1:1 LTV:CAC ratio is at the median for its category. That is not great — it is average. A health & wellness brand with a 3.1:1 ratio is in the bottom quartile. The same number means opposite things.

This is exactly why context-free benchmarks are dangerous. The 3:1 heuristic was derived from SaaS subscription businesses with predictable churn and no inventory. It has been applied as a universal standard to businesses where:

• Repeat purchase rates vary from 8% (one-time gift electronics) to 62% (pet food)
• COGS varies from 18% (software subscription) to 72% (commodity electronics)
• Customer lifecycle varies from 14 months (fast fashion) to 8+ years (premium pet supply)

A 3:1 ratio for a consumables brand with 55% gross margin and 52% repeat purchase rate is a sign of a broken acquisition funnel. A 3:1 ratio for a premium furniture brand where customers buy once every five years is structurally reasonable.

What a good ratio looks like by model​

High-replenishment consumables (beauty, pet, F&B): The benchmark should be 5:1 or above. These categories have the economics to support high LTV — high gross margin, frequent repeat purchases, predictable consumption cycles. A sub-4:1 ratio in these categories usually indicates an acquisition efficiency problem or a retention problem. Both are fixable.

Fashion and apparel: 3:1 is roughly median. Optimise for repeat purchase rate (which is the main LTV lever in this category) before assuming an acquisition problem. A fashion brand at 2.5:1 that improves repeat purchase rate from 28% to 38% will see a meaningful ratio improvement without touching acquisition costs.

Electronics: 2:1 can be healthy. The category is structurally different — per-unit revenue is high but repeat frequency is low. A consumer electronics brand at 2.1:1 is at the median and should not feel pressure to match a benchmark designed for a consumables business.

Home and garden: 2.5:1 is reasonable given purchase frequency. The LTV uplift opportunity is usually cross-category (furniture → accessories → tools) rather than repeat purchase of the same SKU.

Accessing LTV:CAC benchmarks via API​

import requests

# Get the LTV:CAC distribution for a segment
r = requests.get(
    "https://api.valcr.site/data/v1/benchmarks",
    headers={"Authorization": "Bearer vcr_live_your_key"},
    params={"category": "ecommerce", "segment": "beauty"},
)
metrics = r.json()["metrics"]
ltv_cac = metrics.get("ltv_cac_ratio")
print(f"Beauty LTV:CAC p50: {ltv_cac['p50']:.1f}x, p75: {ltv_cac['p75']:.1f}x")

# Rank a specific merchant's LTV:CAC
r2 = requests.get(
    "https://api.valcr.site/data/v1/benchmarks/percentile",
    headers={"Authorization": "Bearer vcr_live_your_key"},
    params={
        "metric":   "ltv_cac_ratio",
        "value":    5.8,
        "category": "ecommerce",
        "segment":  "beauty",
    },
)
print(f"Merchant is at the {r2.json()['percentile']:.0f}th percentile")

The number to watch alongside LTV:CAC​

LTV:CAC in isolation is incomplete. The payback period — how many months of gross margin it takes to recover the acquisition cost — is equally important for cash flow management.

A 6:1 LTV:CAC ratio with a 36-month payback period is a cash flow problem even if the unit economics eventually work. A 3:1 ratio with a 9-month payback is often more operationally sound.

Payback period = CAC / (AOV × gross_margin × purchase_frequency_per_month)

The Valcr benchmark dataset includes payback period distributions within the customer economics metric set. At median for ecommerce broadly: 11 months. Top quartile: under 7 months. Bottom quartile: over 18 months.

Data from the Valcr Q4 2024 benchmark pool. All calculations use VCFS-normalised LTV and CAC methodology.

Access customer economics benchmarks → · VCFS field definitions →

These descriptions are not wrong exactly — Valcr does produce analytics, benchmarks, and reports. But they point to the wrong part of the product. And that distinction matters enormously, because analytics and infrastructure are different businesses with different economics, different buyers, and different reasons to exist.

What analytics does​

An analytics product takes your data and shows it back to you in a more useful form. A well-designed analytics product surfaces patterns you would have missed, answers questions faster than a spreadsheet would, and helps you make better decisions.

Analytics is valuable. But it has a characteristic problem: it is downstream of the data. The data exists somewhere. The analytics product reads it, transforms it, and displays it. The intelligence produced is, ultimately, a function of the input data — and the input data is almost always the customer's own.

This creates a ceiling. An analytics product can only tell you things that are knowable from your own data. And most of the most important questions in business cannot be answered from your own data alone.

"Is my gross margin good?" Your analytics product knows your gross margin. It does not know what a comparable business's gross margin looks like. It cannot tell you whether 44% is exceptional or mediocre without something to compare it against.

That something is what Valcr is.

What infrastructure does​

Infrastructure sits beneath other products and enables capabilities that those products could not economically build themselves.

Stripe is infrastructure. Every developer who integrates Stripe could, in principle, build their own payment processing system. Almost none of them do — because the build cost is enormous, the maintenance burden is ongoing, the regulatory complexity is significant, and Stripe's product is already better than anything a single engineering team would produce as a side project to their main product.

The result is that Stripe becomes embedded in thousands of products. The switching cost is real — moving payment infrastructure is a multi-month project. And Stripe's value compounds with scale because the fraud models, the bank relationships, and the reliability that come from processing trillions in volume cannot be replicated by a newer entrant.

Plaid is infrastructure. Plaid normalises bank data from thousands of financial institutions into a single API. Every application that builds on Plaid — budgeting apps, lending products, payroll tools — could theoretically negotiate direct data agreements with each bank. None of them do.

Valcr is in this category. The benchmark dataset that powers the API cannot be assembled by a SaaS accounting platform as a side project. Building a representative benchmark pool requires:

• Recruiting a sufficiently large, demographically representative merchant sample
• Designing a normalisation methodology that produces comparable numbers across merchants using different accounting approaches
• Maintaining the dataset as the sample grows and the merchant universe shifts
• Computing distributions per segment with sufficient sample depth to produce credible percentile data
• Updating it regularly enough to remain accurate

This is not analytics. This is data infrastructure — the kind of foundational capability that enables other products to offer analytics features they could not otherwise provide.

The correct one-liner​

Valcr is financial benchmarking infrastructure for commerce — operator tools on the surface, proprietary financial dataset underneath.

The "operator tools on the surface" part — the dashboard, the benchmarking UI, the Valcr Score display — are the consumer interface. They are how direct users experience the product. They matter and they will keep improving.

The "proprietary financial dataset underneath" is the infrastructure layer. It is what the API serves. It is what compounds in value as the merchant pool grows. It is what gives Valcr the same characteristic that good infrastructure always has: it becomes more valuable to every user as the total number of users grows.

Why this distinction matters for buyers​

For SaaS platforms and developers: You are not buying a dashboard to embed. You are licensing access to a dataset and the normalisation infrastructure that makes it useful. The value proposition is the same as Stripe's or Plaid's — you get a capability that would cost you orders of magnitude more to build yourself, delivered via an API you can integrate in a day.

For lenders and underwriters: You are not buying a reporting tool. You are buying the ability to contextualise a merchant's financials against their actual peer group at the moment of underwriting. That context is not available anywhere else in a normalised, API-accessible form. It integrates into your existing pipeline; it does not replace it.

For commerce operators: The dashboard and the benchmarks are genuinely useful — but the deeper value is that your VCFS profile, once submitted, produces intelligence that improves as the benchmark pool grows. You contributed data to a system that makes the benchmarks more precise, and you benefit from every other merchant who does the same.

The compounding dataset​

This is the part that is hardest to communicate quickly but most important to understand about Valcr's long-term position.

Every merchant whose VCFS data enters the Valcr pipeline deepens the benchmark distributions — more observations, more precise percentiles, narrower confidence intervals, better sub-segment coverage. The benchmarks that the API serves in 2026 will be materially more credible than the benchmarks it serves today, because the dataset will be larger.

This compounding does not happen in analytics products. Adding a new user to a dashboarding tool makes the vendor's revenue larger. It does not make the product more valuable to existing users.

Adding a new merchant to the Valcr benchmark pool makes the platform more valuable to every lender, every developer, every operator who queries the API. That is the infrastructure model. And it is a fundamentally different business.

Read more about the data model → · Start building with the API →