Skip to main content

List Advertising Decisions

GET 

/api/advertising/decisions

The ranked queue of advertising decisions waiting on a person, plus the KPI strip for the window. One feed combines guardrail signals, change sets waiting for approval (and failed ones that can still be retried, for 7 days), anomalies, goal suggestions, supply blocks, ad accounts that need setup or reconnection, and experiment results from the last 14 days. A signal whose proposed change set is pending is returned once, as the signal, carrying the set's approve and reject actions.

Required scope: advertising:read

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

Requires the advertising.view permission. Token scope: advertising:read (personal access and OAuth tokens). Read-only: each decision's actions list the endpoints that act on it, and those check their own permissions.

Query (all optional): type filter: approvals, stock, spend or setup (omit for all); include_cleared (boolean: also return decisions cleared since the start of today, flagged cleared: true); platforms (one or more of amazon_ads, ebay, google_ads, walmart_connect, meta_ads, tiktok_ads, comma-separated or as an array; the older single platform is still accepted and merged in); limit (default 100, max 250); date_from / date_to (m/d/Y, the KPI window; default the 30 days ending yesterday).

Ordering: decisions are ranked by urgency and money at stake and assigned a group: needs_you_now, today, fyi or cleared_today. Not paginated: limit caps data while meta.total is the full count.

Response: data (decisions), groups (count per group after the type filter), counts (open decisions: all plus one per type filter, ignoring type), kpis and meta (total, limit, type, include_cleared, generated_at, cleared_since).

Each decision: key (<type>:<id>, unique), type (signal, change_set, anomaly, goal_suggestion, supply_block, connection, experiment_result), id, severity (critical, high, medium, low), status, title, summary, money_at_stake with money_basis (e.g. daily_spend, daily_loss), platforms, products, entities, actions (each kind: api with method and path, or kind: link with url), filters, created_at, requires_action, cleared, cleared_at, evidence (type, id and the Get Decision Evidence path, or null), sku_url, details (type-specific; a change set, whether the decision itself or the one a signal proposed, carries change_count, pending_count (the number of its lines still pending, which is what approving the whole set applies) and reverted_by_change_set_id (the undo set that reverted it, else null); a reverted set's title and summary read "Reverted (undone by set #N)"), group, rank_score, age_hours, platform_link ({url, label, scope} opening the decision's campaign, or else its ad account, in the ad platform's console; scope is entity or account; null when the console URL needs an ID SKU.io doesn't store, as on Amazon Ads, Google Ads and Walmart Connect).

kpis: date_from, date_to, spend, attributed_sales, acos, tacos, poas, blended_poas, break_even_poas (1.0), contribution_after_ads, spend_at_risk (last-7-day spend on products with an open stock, delivery or margin signal), spend_7d (all ad spend over the same 7 days, ending date_to), spend_at_risk_share (spend_at_risk ÷ spend_7d, 0–1, null with no 7-day spend), spend_at_risk_basis, saved_by_guardrails with saved_basis (estimated from applied guardrail changes, counted per applied line from when it applied until it was undone or its hold was released, or measured once a guardrail experiment has completed), estimated, poas_estimated, provisional.

Event freezes: a signal raised while an event freeze is active gets no proposed change set (critical stock-outs excepted when the freeze allows them); its details.frozen_by names the freeze, otherwise it is null.

Signal details (guardrail signals): effective_mode (off, monitor, suggest or auto: the mode guardrails act in for the signal's product and ad account), proposable (true when Propose Guardrail Signal Fix can plan a fix now: the signal is open, actionable, has no set waiting for approval, and nothing blocks it), propose_path (that endpoint, when proposable), no_proposal_reason (plain-English reason the signal has no proposed change, or null) and no_proposal_code (its machine-readable code, e.g. monitor_only, frozen, mode_off, campaigns_off, holdout_control, not_actionable, kill_switch).

Every card carries money_unit (per_day, per_day_change or once: the unit word to print next to money_at_stake) and details.severity_reason (one sentence: why it has its severity). A card with no money at stake is never high or critical; an anomaly that is an improvement is always low. A pending change set past its expires_at is not offered (it can no longer be approved).

Guardrail signal cards add details.other_sku_sales_7d (sales the platform credited to these ads for OTHER products over the last 7 days; not part of poas_7d), details.pause_cover_days and details.resume_cover_days (the policy thresholds that apply), and details.after_approval (what happens once approved and how the ads come back in the current mode).

details.change_set.lines[] add entity_type_label ("Product ad", "Keyword", "Negative keyword", "Ad group", "Campaign"), campaign_id, campaign_name, ad_group_name and error. details.change_set.caps_breached_details[] are {key, label, value, limit, message} versions of caps_breached. Failed change set cards add details.change_set.failed_lines[] (same line shape, with the platform error) and details.retry_blocked_reason (null when a retry can work), plus a discard_failed action.

Anomaly cards have snooze and dismiss actions, an open_campaign link to the affected campaign, and details.metric_label, observed_display, baseline_display, improvement, campaign_id. Goal suggestion and experiment result cards have a dismiss ("Not now") action.

Signal details also include after_approval_later (only what happens after the change is made: whether SKU.io reverses it by itself, proposes reversing it, or leaves it to a person; null when approving changes nothing) and sales_without_stock (null, or {units_7d, sales_7d, last_order_date, message} when the platform credited this product's own sales to its ads in the last 7 days while it has none available; last_order_date is the product's latest order in SKU.io, Y-m-d).

Severity follows the money: a signal whose daily spend or loss is under 10.00 (tenant currency) is at most high, and under 2.00 at most medium; details.severity_reason names the level it missed.

Goal suggestions: title (e.g. "Suggest clearing aged stock: SKU") and summary (why, the goal switch and what the new goal does) are written when the feed is read.

Request​

Responses​

OK

Response Headers
    Content-Type