Documentation

Cost models and allocation

Updated 17 Nov 2026

Each campaign has a cost model. CPC and CPM write a cost on the click. CPA, manual, and auto write zero at click time. Manual and auto campaigns can receive a daily total that is split across that day's clicks. Automatic pull from ad accounts is a Pro feature.

Cost on the click

priceClick runs when the click is logged.

  • cpc: the campaign’s cost_value.
  • cpm: cost_value / 1000.
  • cpa, manual, and auto: 0 at click time.

On a CPC campaign, a cost parameter from the traffic source is kept only up to 10 times the campaign CPC, or up to 5 in the main currency when the campaign CPC is empty. allow_cost_override accepts a cost query parameter only when sig is an HMAC of campaign id|cost using the master key. Later allocation does not overwrite a cost that was signed that way.

Enter a daily total

For cost_model=manual, the admin and the MCP tools record_campaign_cost and list_campaign_cost store a spend amount for a calendar day in the campaign timezone. Allocation divides that total by the number of clicks in the local day and writes the share onto each click in ClickHouse.

Sync from an ad account

cost_sync is on for Pro, Team, and Founder, and off for Free. An integration with kind cost can be meta, tiktok, or google. Sync pulls daily spend into ClickHouse cost_snapshots. The integration’s campaign_map_json maps the external campaign id to a Velotrak campaign. Allocation runs for campaigns whose model is auto or manual: daily total divided by that day’s click count. Trigger it from the admin or with the MCP tool sync_costs.

Reports read the cost column when they compute profit, ROI, CPA, and CPC. See reports.