Cost semantics

Understand the date range, segments, four costs, and missing values.

Sales-month range

The API groups all four costs by sales month. It does not query by arrival month, invoice month, or individual day.

Use the first day of the month for both month_from and month_to, in YYYY-MM-01 format. Both boundary months are included, month_to must not be earlier than month_from, and one request can cover at most 24 months including both boundaries.

For example, use month_from=2026-07-01&month_to=2026-07-01 for July 2026. Mid-month dates are not recommended inputs.

Product segments

Value	Meaning
`normal`	Normal products only. This is the default.
`sample`	Sample products only.
`all`	Normal and sample products combined.

Cost fields

Field	Product-profit meaning
`purchase_cost_usd`	Purchase cost from the page’s available Landing split.
`inbound_freight_usd`	Inbound freight from the same available Landing split.
`shipping_to_customer_usd`	Shipping-to-customer total where costed rows exist.
`warehouse_fees_usd`	Warehouse-fee total where costed rows exist.

All four amounts are totals in USD for the requested range.

Data freshness

Data is available after the most recent successful nightly T+1 pipeline. The completion time can vary and is not guaranteed at a fixed hour. Backfills or corrections may update historical sales months.

`null` versus `0`

null means Mellow could not calculate that cost with the page’s current coverage rules.
0 means the value was calculated and the result is a real zero.

Do not convert null to zero. They represent different business states.

Unmapped source rows remain in the response. Their product ID and SKU may be null; clients should not silently discard them.