Skip to main content

List Campaigns

GET 

/api/advertising/campaigns

Lists every synced ad campaign across all connected ad platforms, with performance metrics for a date window, the labels attached, products at stock-out risk and which inline edits each row supports (controls).

Required scope: advertising:read

Grant this scope to your token under Settings → Developer → Personal Access Tokens.

The metrics window defaults to the trailing 30 days ending yesterday (tenant timezone). Results are paginated (default 10, max 500 per page).

Sorts: id, name, state, campaign_type, daily_budget, target_value, platform, account, products_at_risk, spend, sales, impressions, clicks, orders, units, acos, roas, ctr, cpc, cvr, attributed_contribution, contribution_after_ads, poas (default -spend).

controls maps each lever (state, budget, target_value, roi_target, add_negative) to enabled plus a reason when the platform, account status or API access level blocks it.

Filter operators. Text filters accept filter[<field>]=value (exact match) or filter[<field>.<operator>]=value with operators contains, does_not_contain, is, is_not, is_one_of, is_not_one_of, starts_with, does_not_start_with, ends_with, does_not_end_with, is_empty, is_not_empty. Numeric filters accept is, is_not, is_one_of, is_not_one_of, greater_than, less_than, greater_than_or_equal, less_than_or_equal, between (comma-separated pair), is_empty, is_not_empty.

Every window metric (spend, sales, impressions, clicks, orders, units, acos, roas, ctr, cpc, cvr, attributed_contribution, contribution_after_ads, poas) is also a numeric filter and a sort key.

Ratios (acos, roas, ctr, cvr, poas) are fractions, so 0.2003 means 20.03%. poas and the contribution metrics are null when no product cost data is available; poas_estimated is true when part of the contribution uses an estimated unit contribution.

platform_link opens the row in the ad platform's own console: {url, label, scope} where label reads e.g. "Open in Meta Ads Manager" and scope is entity (the link opens this campaign, ad set or ad itself) or account (the console can't address it by URL, so the link opens its ad account). It is null when the console URL needs an ID SKU.io doesn't store (Amazon Ads, Google Ads and Walmart Connect today).

serving_status is the platform's own delivery status as reported (for example CAMPAIGN_STATUS_ENABLED or OUT_OF_BUDGET); serving_status_label is the same in words (for example "Out of budget", "Scheduled"), and is null when it would only repeat state or the campaign is archived or ended.

controls.state may also carry refused_values: an object mapping a state the platform refuses for this row to the reason (for example an eBay negative keyword can be removed but not paused: {"paused": "eBay negative keywords cannot be paused, only removed."}). Absent when every state is allowed.

Requires the advertising.view permission.

Request​

Responses​

OK

Response Headers
    Content-Type