Profitability: overview

What this analysis answersCopy Anchor Link

The Profitability API combines your store's revenue with your paid media spend (Meta Ads and Google Ads) to show whether acquiring and retaining customers is profitable. Every revenue-derived value can be converted into contribution margin, using the margin the organization configured in the V4MOS.AI platform.

Questions you can answer:

• How much does it cost to acquire a new customer (CAC)? And how much does each sale cost (CPV)?
• Does the value a customer generates over their lifetime (LTV) pay for acquiring them (LTV/CAC)?
• What is the return on media spend (ROI), and how many months does it take to pay back?
• How many customers buy for the first time, and how many come back?
• How much of each customer cohort's revenue comes back in the following months?
• Which entry products, channels, campaigns or coupons bring the customers who repurchase the most?
• How much of the revenue goes to the real cost of goods sold (COGS)?

Which endpoint to useCopy Anchor Link

Available endpointsCopy Anchor Link

• getGet Profitability Summary Cards/v1/profitability/cardsReturns the organization's consolidated profitability indicators for the period: revenue, media spend, orders, customers, CAC, CPV, LTV,…
• getGet New vs Recurring Customers Over Time/v1/profitability/new-vs-recurringReturns a time series of new customers (first purchase in the point's period) and returning customers (had bought before) who placed an…
• getGet Profitability Metrics Evolution/v1/profitability/metrics-evolutionReturns a monthly series with CAC, LTV, CPV, LTV/CAC, revenue, orders, spend, new customers and the real COGS block for each month.
• getGet Daily CMV Evolution/v1/profitability/cmv-evolutionReturns a daily series with each day's revenue, orders, average ticket and real cost of goods sold (COGS), using the same COGS fields as…
• getGet Profitability Cohort Analysis/v1/profitability/cohortReturns a retention matrix by cohort: each row groups customers by the start of their relationship with the store, and each column shows…

AuthenticationCopy Anchor Link

Send the x-client-id and x-client-secret headers on every request, together with the organizationId query parameter. See Authentication.

Common parametersCopy Anchor Link

All endpoints use the base URL https://data.v4mos.ai and accept the parameters below.

The /cohort endpoint also accepts view, groupBy and breakBy (see Cohorts).

• Unknown query parameters return 400.
• Values outside the allowed list for view, groupBy or breakBy also return 400.

ExamplesCopy Anchor Link

# Consolidated indicators from January to March 2025
curl "https://data.v4mos.ai/v1/profitability/cards?organizationId=YOUR_ORG&startDate=2025-01-01&endDate=2025-03-31" \
  -H "x-client-id: YOUR_CLIENT_ID" \
  -H "x-client-secret: YOUR_CLIENT_SECRET"

# Monthly metrics evolution in 2025
curl "https://data.v4mos.ai/v1/profitability/metrics-evolution?organizationId=YOUR_ORG&startDate=2025-01-01&endDate=2025-12-31" \
  -H "x-client-id: YOUR_CLIENT_ID" \
  -H "x-client-secret: YOUR_CLIENT_SECRET"

# Revenue retention by cohort, with quarterly columns
curl "https://data.v4mos.ai/v1/profitability/cohort?organizationId=YOUR_ORG&startDate=2024-01-01&endDate=2024-12-31&view=revenue&groupBy=quarter" \
  -H "x-client-id: YOUR_CLIENT_ID" \
  -H "x-client-secret: YOUR_CLIENT_SECRET"

MetricsCopy Anchor Link

Monetary values are in the store's currency, rounded to 2 decimal places. "× margin" means multiplied by marginPercent / 100 (see Contribution margin).

General indicators (/cards, /metrics-evolution)Copy Anchor Link

Indicators by campaign strategy (/cards)Copy Anchor Link

These depend on the campaign classification done in the V4MOS.AI platform (acquisition, brand, monetization).

Cost of goods sold (/cards, /metrics-evolution, /cmv-evolution)Copy Anchor Link

Cohorts (/cohort)Copy Anchor Link

Important rulesCopy Anchor Link

Contribution marginCopy Anchor Link

The organization can configure its contribution margin in the platform, that is, the share of revenue left after variable costs (product, taxes, shipping, payment fees). Every response that uses this margin reports:

• marginPercent: the percentage applied (0–100).
• marginConfigured: true if the organization configured a margin; false if it did not.
• marginCompleteness: complete, partial or none. Tells whether the margin was built item by item (gateway, tax, shipping and COGS) and whether every item is resolved. none when there is no item-by-item composition.
• marginItemStatus: the status of each item (synced = comes from orders, configured = entered by the user, pending = not configured or missing data). null when there is no item-by-item composition.

The retention percentage (pct) does not change with the margin, because the margin cancels out in the division.

null is not 0Copy Anchor Link

Many fields can be null. null means "could not be calculated" (there is no base, the division is undefined or the data is unavailable), while 0 is a measured value. Show a dash or "N/A" for null and never convert it to 0.

Comparison with the previous periodCopy Anchor Link

In /cards, when startDate and endDate are sent, the response includes:

• previousPeriod: the same indicators calculated for the period immediately before, with the same number of days. Example: for Mar 1 to Mar 31 (31 days), the previous period is Jan 29 to Feb 28.
• changes: the percentage change of each indicator: (current − previous) ÷ previous × 100. Each field is null when the previous value is 0 or null.

Exceptions: ltv and retentionLtv do not use the previous period. They compare the customer base acquired up to the end of the selected period with the base acquired up to its start. margin is the configured margin, which does not depend on the period, so its change is always 0.

Without startDate/endDate, previousPeriod and changes are null.

Time series granularityCopy Anchor Link

In monthly series, the month field is the first day of the month (2025-03-01). In the daily series of /new-vs-recurring, the same month field holds the day itself.

CohortsCopy Anchor Link

• view: logo (default) measures retention by number of customers; revenue measures it by revenue × margin.
• groupBy: month (default), quarter or semester. Changes only the size of the period columns (M1, M2… become Q1, Q2… or S1, S2…). Rows remain monthly cohorts. Column 0 is always the entry month.
• breakBy: cohort (default, one row per monthly cohort), product (one row per first-purchase product), origem (channel), campanha (campaign) or cupom (coupon). In every breakdown other than cohort, each customer starts at their own month 0, regardless of the calendar month.

• With breakBy=product, rows overlap: a customer whose first order has several products appears in several rows. Do not add rows together (overlappingRows: true).
• With breakBy=origem|campanha|cupom, each customer falls into exactly one row, so rows can be added together (overlappingRows: false). Customers with no identified value go into the Sem origem, Sem campanha or Sem cupom row.
• Attribution of customers to campaigns and coupons depends on the UTMs and coupons recorded on orders. Always show the coverage field next to the numbers to indicate how much of the base was attributed.
• With groupBy=quarter|semester and view=logo, counts add up the customers of each month. A customer active in several months of the same quarter counts once per month, so the number is an upper bound of distinct customers. Revenue sums are exact.

Real COGS and blendedContributionCopy Anchor Link

When the e-commerce platform reports product costs, the API splits revenue into two parts: with real COGS (revenueWithCmv) and without real COGS (revenueWithoutCmv).

If the margin was configured item by item and is complete (marginCompleteness = complete), each part deducts its own costs (gateway, tax, shipping and COGS) instead of the single percentage.

contribution is always revenue × margin, even when real COGS exists. When marginBasis is null, cost data was not available at query time, which is different from no_basis. In /cmv-evolution, this situation is flagged with degraded: true and data: [].

How customers are countedCopy Anchor Link

• newCustomers and recurringCustomers in /cards match the requested dates exactly.
• recurringCustomers (customers who had bought before the start of the period) and recurringOrders (orders from customers who had bought before that order) measure different things. Do not divide one by the other.
• cac uses total media spend. campaignCac uses only acquisition campaigns but divides by all new customers. acquisitionCac restricts both sides to acquisition campaigns. These are three different CACs, on purpose.
• The four spend slices by strategy (acquisitionInvestment + brandInvestment + monetizationInvestment + unclassifiedInvestment) add up to the organization's campaign spend, but may differ slightly from investment because of update timing and because zero or negative spend adjustments are included in the slices but not in investment.

ErrorsCopy Anchor Link