Docs

Costs

Orbitra pulls daily spend from ad accounts and distributes it across clicks, so ROI and profit in reports are calculated from real money, not from a manual cost per click.

Connections are in βš™ β†’ Integrations, in the ad networks group: Facebook Costs, TikTok Costs, Google Ads Costs. The campaign editor's Integrations tab shows whether the campaign's clicks carry IDs for matching, and lets you add a connection.

How spend lands on a click

  1. The aggregator_cron.php cron (the installer adds it every 15 minutes) walks the connections whose update interval is due. Every pass re-reads the last 5 days, and the first pass reads 30: ad accounts revise spend retroactively, and the current day grows until midnight.
  2. Records land in cost_records with updates keyed by (connection_id, external_id). Re-syncing the same day is safe: spend is recalculated, not accumulated.
  3. For each record, clicks of the same day are matched, from the most specific level to the broadest:
    1. ad_id (also creative_id, creative);
    2. adset_id / adgroup_id (also adgroup, adgroupid, ad_group_id);
    3. campaign_id (also campaign, campaignid, ad_campaign_id).
  1. The day's spend is divided evenly among the matched clicks.
  2. Spend is converted to the tracker's currency (rates from open.er-api.com, cached for 12 hours; custom rates via the fx_rates_manual_json setting, units per 1 USD).

The main requirement: the ad's link must pass the ad, group or campaign ID into the tracker. The easiest way is to pick a template traffic source (Facebook, TikTok, Google Ads) in the campaign β€” the template adds the needed macros itself.

Records that found no clicks retry matching on every sync: a late click, a fixed link or a new adgroup_id will pull the spend in.

"Received N, matched 0"

The Refresh costs button on a connection shows the specific reason:

CodeMeaning
no_spendrecords arrived, but the spend in them is zero
no_clicksthere are no clicks in Orbitra on those days
no_idsthe clicks carry no ad, group or campaign ID β€” the link does not lead straight to the Orbitra campaign, or parameters get lost along the way
macrosclicks contain unresolved macros like __CID__ β€” the source did not substitute values
ids_differIDs in the clicks and in the ad account report do not match; both are shown

In the click card, the "Parameters" section shows all captured parameters, with ad network IDs first.

Facebook / Meta

A Long-lived User Token or System User Token with ads_read + the ad account ID (act_…). You can specify the API version and a proxy. For details, see Facebook / Meta.

TikTok

Three ways to connect:

MethodWhat you need
Connect via TikTok MCPOnly a TikTok login. No developer app or token needed β€” the tracker registers itself through TikTok's official MCP server. Imports spend; does not import pixels. The panel must be opened over HTTPS (https:// on a bare IP works too)
1-Click (Sign in with TikTok)App ID and App Secret of your own TikTok for Business app: the ORBITRA_TIKTOK_APP_ID / ORBITRA_TIKTOK_APP_SECRET environment variables, or the manual connection fields. Finds ad accounts and pixels, imports pixels into Pixel Vault
ManualA Marketing API token from a free developer app (Developer Portal β†’ Apps & Agents β†’ Direct Advertiser, Ads Management and Reporting permissions) + Advertiser ID

An Events Manager token does not work for spend import β€” it only sends conversion events. If the ad account list cannot be read through MCP, you can paste Advertiser IDs manually, comma-separated.

The 1-Click keys are picked up in order: the ORBITRA_GOOGLE_CLIENT_ID, ORBITRA_GOOGLE_CLIENT_SECRET, ORBITRA_GOOGLE_DEVELOPER_TOKEN environment variables β†’ settings β†’ fields of an already saved manual connection. The simplest way is to save a manual connection once β€” after that the 1-Click button works too. To check the server setup: php check_google_ads_oauth.php.

Environment variables are read from the PHP-FPM environment (env[ORBITRA_GOOGLE_CLIENT_ID] = … in the pool config), not from the .env file β€” PHP code does not load it. .env.example is only a list of names.

Google and TikTok do not accept OAuth redirects to http://. On a bare IP without a certificate, use a manual connection.

Spend is matched by the ValueTrack parameters {campaignid} and {creative} β€” the Google Ads source template adds them.

Push and pop networks

Spend from push/pop advertiser networks β€” AdMaven, PropellerAds, Kadam, Galaxion, HilltopAds, Adsterra, Clickadu β€” imports through the same cron and lands on clicks per campaign and, where the network reports it, per zone (site). Zone Killer, which blocks zones burning money, works from this data. See Push & pop networks.

Dolphin and Fbtool

These services can only send spend to Keitaro via its Admin API. Orbitra accepts the same request at POST /admin_api/v1/campaigns/<ID>/update_costs. For details, see Dolphin / Fbtool.

Manual spend

The Refresh costs button in the campaign menu sets spend for a period manually (action update_costs).

Revenue aggregator

βš™ β†’ Revenue Aggregator β€” the inverse task: pull revenue from affiliate program accounts that do not send postbacks. Engines: ReferOn, Affilka, Generic API. For each connection you set the network, deal type, sync interval, and the name of the parameter where the affiliate program stores the Orbitra click ID. Revenues and sync logs are on the tabs of the same page.

Agencies and the commission

Rented ad accounts cost more than the cabinet reports: the agency's percent is written into every import (cost_records.fee_amount; clicks.cost carries spend with the fee, clicks.fee the fee share) β€” so ROI/CPC are honest the moment spend lands, and changing the percent later never rewrites history.

Ad names, statuses, platform metrics

The cost sync also collects what the platform knows about the ads themselves: names and statuses into ad_entities (statuses refreshed hourly, in the same cron pass), impressions and the platform's own click counts onto the spend rows. In campaign reports grouped by ad / adset / campaign you get names instead of bare ids, a status chip, and the platform-side columns: Impressions, Clicks (platform), CPM, CTR (platform) and Click loss = 1 βˆ’ tracker visitors / platform clicks β€” the number that immediately exposes a cloaking or domain problem, which adset.pro does not have.

A top banner in the reports shows the share of revenue that cannot be tied to an ad id (an unreplaced __CID__ / {{ad.id}} macro counts as missing) and jumps into the offending source's editor.

Cron

*/15 * * * * php /var/www/orbitra/aggregator_cron.php >> /var/www/orbitra/var/logs/aggregator.log 2>&1

The interval is checked per connection, so a frequent cron is cheap; for intervals under 15 minutes, run it more often. Flags: --force (ignore the interval), --connection=5, --days=30.

← Previous
Postbacks and conversions
Next β†’
Push and pop networks
View source on GitHub: github.com/fenjo26/Orbitra.link/wiki
All guides
Docs

Quick start: your first campaign

The short path: install the tracker, create a campaign, and get your first clicks and conversions in under an hour.

Read guide β†’
Docs

Installation and updates

Install Orbitra on a fresh Ubuntu or Debian server with one command, and update to new versions safely.

Read guide β†’
Docs

Migrating from Keitaro

Move campaigns, offers, sources and domains from Keitaro to Orbitra in one click β€” what transfers and what to check.

Read guide β†’
Docs

Migrating from Binom

Move campaigns and streams from Binom to Orbitra: what transfers automatically and what to set up by hand.

Read guide β†’
Docs

Feature overview

Everything Orbitra can do: campaigns and streams, cloaking, landings, PWA, postbacks, costs, reports and integrations.

Read guide β†’
Docs

Campaigns and streams

The complete reference: campaign settings, stream types, schemas, rotation, filters, test links and every option explained.

Read guide β†’
Docs

Cloaking

Full cloaking reference: detection layers, global settings, per-stream filters, verdicts and reports.

Read guide β†’
Docs

Browser check

How the JS check catches bots, VMs and emulators through contradictions in the browser environment.

Read guide β†’
Docs

Landing pages

Landing types, the {offer} macro, the JS adapter, LeadForge and multi-offer landings β€” the complete reference.

Read guide β†’
Docs

PWA and Web Push

Build installable PWA apps and collect push subscribers: settings, icons, events and notifications.

Read guide β†’
Docs

PWA Funnel

A multi-step PWA funnel: install prompts, event tracking and re-engagement notifications.

Read guide β†’
Docs

Conversion popups

Show real conversion events as on-page popups: setup, triggers and placement.

Read guide β†’
Docs

Session recordings and heatmaps

Replay real visits and see click and scroll maps. Storage limits and privacy notes.

Read guide β†’
Docs

Content gallery

Central storage for icons, screenshots and creatives used across PWAs and landings.

Read guide β†’
Docs

Creatives library

Store creatives with subid tracking and test them across campaigns.

Read guide β†’
Docs

External PWA and Telegram channels

Publish PWAs to external domains and run Telegram channels as a traffic source.

Read guide β†’
Docs

Postbacks and conversions

Incoming postbacks, conversion statuses and types, and outgoing S2S postbacks to your traffic source.

Read guide β†’
Docs

Costs

Import spend from Facebook, TikTok and Google Ads, or update it via API and cron β€” and how the revenue aggregator works.

Read guide β†’
Docs

Push and pop networks

Working with push and pop traffic sources: feeds, zone optimization and the zone killer.

Read guide β†’
Docs

Facebook / Meta

Cost import from Meta Ads and the Conversions API: server-side events with deduplication.

Read guide β†’
Docs

Dolphin / Fbtool

Receive Facebook costs through the Dolphin (Fbtool) API in real time.

Read guide β†’
Docs

FB comment cleaner

Bulk-moderate comments under Meta ads: hide, delete and filter by keywords.

Read guide β†’
Docs

Traffic sources and affiliate networks

Catalog of 50+ traffic sources and 440+ networks: templates, parameters and postback URLs.

Read guide β†’
Docs

Reports, logs and metrics

The report builder, saved reports, click logs and every metric explained.

Read guide β†’
Docs

Domains and SSL

Add domains, DNS, free Let's Encrypt certificates, redirects, parking and every switch on the page.

Read guide β†’
Docs

Cloudflare

How to run campaign domains through Cloudflare: DNS, SSL modes and what to turn off.

Read guide β†’
Docs

Administration

Users, roles and permissions, security settings, geo databases, updates and system health.

Read guide β†’
Docs

Telegram bot

Manage the tracker from Telegram: stats, conversions and alerts in chat.

Read guide β†’
Docs

MCP: an AI assistant in the tracker

Connect Claude or any MCP client to Orbitra and manage campaigns with plain-language commands.

Read guide β†’