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
- The
aggregator_cron.phpcron (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. - Records land in
cost_recordswith updates keyed by(connection_id, external_id). Re-syncing the same day is safe: spend is recalculated, not accumulated. - For each record, clicks of the same day are matched, from the most specific level to the broadest:
ad_id(alsocreative_id,creative);adset_id/adgroup_id(alsoadgroup,adgroupid,ad_group_id);campaign_id(alsocampaign,campaignid,ad_campaign_id).
- The day's spend is divided evenly among the matched clicks.
- Spend is converted to the tracker's currency (rates from
open.er-api.com, cached for 12 hours; custom rates via thefx_rates_manual_jsonsetting, 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:
| Code | Meaning |
|---|---|
no_spend | records arrived, but the spend in them is zero |
no_clicks | there are no clicks in Orbitra on those days |
no_ids | the 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 |
macros | clicks contain unresolved macros like __CID__ β the source did not substitute values |
ids_differ | IDs 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:
| Method | What you need |
|---|---|
| Connect via TikTok MCP | Only 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 |
| Manual | A 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.
Google Ads
- 1-Click (Sign in with Google) β finds direct accounts and MCC child accounts, creating a connection for each one you select. Requires a Developer Token (from the MCC) and an OAuth Client ID + Secret (Google Cloud Console, type "Web application", redirect URI
https://your-domain/api.php?action=google_ads_oauth_callback). - Manual β Customer ID, Developer Token, Client ID, Client Secret, Refresh Token.
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.envfile β PHP code does not load it..env.exampleis 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.
- The Agencies tab of the aggregator section manages agencies (name, fee %, contacts, payment terms, notes) and compares them by spend, CPC, CPM and ROI over a period.
- Each cost connection picks its agency in the editor.
- Reports gain Spend (cabinet) and Agency fee columns; every grouping splits both.
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.
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 βDocsInstallation and updates
Install Orbitra on a fresh Ubuntu or Debian server with one command, and update to new versions safely.
Read guide βDocsMigrating from Keitaro
Move campaigns, offers, sources and domains from Keitaro to Orbitra in one click β what transfers and what to check.
Read guide βDocsMigrating from Binom
Move campaigns and streams from Binom to Orbitra: what transfers automatically and what to set up by hand.
Read guide βDocsFeature overview
Everything Orbitra can do: campaigns and streams, cloaking, landings, PWA, postbacks, costs, reports and integrations.
Read guide βDocsCampaigns and streams
The complete reference: campaign settings, stream types, schemas, rotation, filters, test links and every option explained.
Read guide βDocsCloaking
Full cloaking reference: detection layers, global settings, per-stream filters, verdicts and reports.
Read guide βDocsBrowser check
How the JS check catches bots, VMs and emulators through contradictions in the browser environment.
Read guide βDocsLanding pages
Landing types, the {offer} macro, the JS adapter, LeadForge and multi-offer landings β the complete reference.
Read guide βDocsPWA and Web Push
Build installable PWA apps and collect push subscribers: settings, icons, events and notifications.
Read guide βDocsPWA Funnel
A multi-step PWA funnel: install prompts, event tracking and re-engagement notifications.
Read guide βDocsConversion popups
Show real conversion events as on-page popups: setup, triggers and placement.
Read guide βDocsSession recordings and heatmaps
Replay real visits and see click and scroll maps. Storage limits and privacy notes.
Read guide βDocsContent gallery
Central storage for icons, screenshots and creatives used across PWAs and landings.
Read guide βDocsCreatives library
Store creatives with subid tracking and test them across campaigns.
Read guide βDocsExternal PWA and Telegram channels
Publish PWAs to external domains and run Telegram channels as a traffic source.
Read guide βDocsPostbacks and conversions
Incoming postbacks, conversion statuses and types, and outgoing S2S postbacks to your traffic source.
Read guide βDocsCosts
Import spend from Facebook, TikTok and Google Ads, or update it via API and cron β and how the revenue aggregator works.
Read guide βDocsPush and pop networks
Working with push and pop traffic sources: feeds, zone optimization and the zone killer.
Read guide βDocsFacebook / Meta
Cost import from Meta Ads and the Conversions API: server-side events with deduplication.
Read guide βDocsDolphin / Fbtool
Receive Facebook costs through the Dolphin (Fbtool) API in real time.
Read guide βDocsFB comment cleaner
Bulk-moderate comments under Meta ads: hide, delete and filter by keywords.
Read guide βDocsTraffic sources and affiliate networks
Catalog of 50+ traffic sources and 440+ networks: templates, parameters and postback URLs.
Read guide βDocsReports, logs and metrics
The report builder, saved reports, click logs and every metric explained.
Read guide βDocsDomains and SSL
Add domains, DNS, free Let's Encrypt certificates, redirects, parking and every switch on the page.
Read guide βDocsCloudflare
How to run campaign domains through Cloudflare: DNS, SSL modes and what to turn off.
Read guide βDocsAdministration
Users, roles and permissions, security settings, geo databases, updates and system health.
Read guide βDocsTelegram bot
Manage the tracker from Telegram: stats, conversions and alerts in chat.
Read guide βDocsMCP: an AI assistant in the tracker
Connect Claude or any MCP client to Orbitra and manage campaigns with plain-language commands.
Read guide β