API reference

Generate a key in any business dashboard under the API tab. Keys are account-level: one key works for every business you own. The key is shown once at creation, so store it securely and pass it on every request.

Read & write keys can launch campaigns, pause/resume, change budgets, and upload creatives. Read only keys can fetch stats and structure but never change anything: hand those to agents you don't want touching spend. Keys support optional expiry and instant revocation from the API tab.

Every error uses one envelope with a stable code you can branch on.

Each key gets 600 requests/minute by default; higher per-key limits are available for large integrations. Expensive endpoints add tighter budgets on top: launch 10/min, entity updates and pixel 30/min, uploads 10/min, sync 4/min. 429 responses include a Retry-After header. For updates, prefer webhooks over polling.

Connect AI tools (Claude Code, Claude Desktop, Cursor, or any MCP client) straight to your account: add the server with your API key and the agent gets typed tools for the most common operations, with no HTTP code to write. The same key rules apply: a read only key makes the write tools fail with FORBIDDEN, every call counts against the key's rate limit, and everything shows up in the key's usage log.

The transport is Streamable HTTP (stateless, plain JSON responses), with the key passed as a header. The named tools cover the everyday operations; the call_api tool reaches every other endpoint in this reference — ad groups below a launched campaign, keywords, automated rules, audiences, catalogs, webhooks — so nothing is out of an agent's reach. That includes uploads, which used to be the exception: POST …/ads/media and the app-media fields all take a public https URL that we fetch server-side, so an agent never needs to send a file part.

Campaign creation is a named tool, not an escape-hatch call. launch_ad_campaign builds a whole stack on any of the five networks and is the only place the per-network objective vocabulary is written down for an agent — it is objective on Meta and TikTok (which do not accept the same set: Meta spells its conversion objective sales and TikTok spells it conversions), goal on Snapchat, the campaign type on Google, and a placement plus a bidding strategy on Apple. Meta, TikTok and Snapchat read an unrecognised value as traffic rather than refusing it, so a word borrowed from the wrong network launches the wrong campaign and answers 201.

The discovery endpoint: every business the key can act on, with each ad network's connection status and every app's id, slug, type, and status (source of the {appId} used by the apps + affiliates endpoints). Call this first to find the slug used in all other paths.

Every app on the business — every type, any status — newest first. The id/slug source for the create/edit flows below; full settings live on the single-app GET.

Create an app with the wizard's field names (see the samples; the GET /api/v1 endpoint index lists every field). name, content_type, and the per-type essentials are required: clipping needs platforms, a reward (cpm_cents per 1k views or per_platform_rewards), and at least one requirement; web traffic needs website_url + cpm_cents (per click); collab needs collab_kind (placement or content), ad_placements, and retention_days; affiliate needs a commission rate above zero plus at least one rail — provider with an https website_url for the web side, mobile_provider with at least one store URL for the mobile side, or both on the same app.

The same server-side rules as the dashboard apply: percent commission is capped at 90% (70% for a store-mediated mobile-only app, with a 1% floor), flat commission at $50, and the app name becomes the URL slug — globally unique, so a taken or reserved name is a hard 400 you resolve by renaming. On a dual-rail app the single rate is deliberately not refused at 90%: it is clamped per sale instead, to 70% when the sale went through Apple or Google and 90% otherwise. The web rail supports provider: "stripe" only via the API; Polar, Paddle, Whop, Shopify, and WooCommerce apps are created in the dashboard wizard (their connect steps only exist there).

Media: send JSON with thumbnail_url / media_urls (public https URLs — fetched server-side behind an SSRF guard and validated by content, PNG/JPEG for thumbnails; placement collabs require at least one creative) or multipart with thumbnail / collab_media_0..4 file parts. Creates are idempotent on the field fingerprint, so an accidental double-post returns the first result. Requires a read_write key; 10 creates/minute.

Send only the fields to change — everything the dashboard edit dialog can touch: name (re-derives the slug, same global-uniqueness rule), description, category, requirements, FAQs, visibility (public / private / private_only / invite_only), commission rate/type and per-product rates, URLs, platforms, rewards, submission window, retention, placements, and media (thumbnail_url, remove_thumbnail, media_urls as the full desired set — kept CDN URLs stay, new https URLs are fetched, removed ones are deleted).

Commission changes notify the app's affiliates automatically and apply to new customers only — already-referred customers keep the rate stamped at their first conversion. Affiliates on a personal deal are unaffected by program-rate changes. Locked fields (content_type, status, budget_cents) return an explicit VALIDATION_ERROR instead of being silently ignored. Requires a read_write key.

Adding a rail. provider and mobile_provider are settable here when the app does not have one yet — that is how a website-only affiliate app grows a mobile rail (send mobile_provider plus a store URL), and how a mobile-only app grows a web rail (send provider plus an https website_url). Changing a provider that is already connected is still refused: disconnect it in the dashboard first, because the disconnect has to revoke the provider-side credentials too.

Everything you need to render the "join and earn X%" pitch screen before the user enrolls: the commission rate and type (percent or flat dollars), the affiliate count, total commission paid out, and the app status and application gates the create call will enforce. This is the same information the public app page shows prospective affiliates.

commission.products lists the app's visible catalog entries with their per-product rate, display price, billing interval, and an estimated_commission_cents (≈ payout per sale). Entries the owner hid are omitted, matching the public app card; a hidden product still earns its rate if bought. When the owner uses one rate for everything, has_custom_product_rates is false and every product carries the default rate. range is the min/max across visible rates when they differ.

For web_traffic apps commission is null and a click_payout object carries the per-click rate (cpc_cents), the budget, and the remaining budget instead: everything you need for an "earn $X per visitor" pitch screen. Exactly one of commission / click_payout is set per app. Its budget_remaining_cents is budget_cents minus spent_cents, which is gross: the 1% platform fee on each click payout comes out of that same budget, so about 4.8% of the remainder is already earmarked. Use settings.payable_capacity_cents for the amount that can still reach affiliates.

The response also carries a settings object with the full owner-facing field set (the key holder is always the business owner), including payable_capacity_cents for budget apps — read it before a PATCH so an edit changes only what you mean to change.

Your whole affiliate program in one call: affiliate counts, lifetime totals (clicks, sales, renewals, revenue, commission), and the payout buckets — pending, payable, paid, refunded — summed across every affiliate of the app. It's what the per-affiliate numbers from List affiliates add up to, without paging through them yourself. Works the same for Affiliate and Web Traffic apps (Web Traffic pays per qualified click, so its conversion money stays at zero), and on an Affiliate app the totals cover both rails together.

Add ?from=&to= for a window object with the same numbers scoped to those dates (UTC days, inclusive): clicks, initial sales, renewals, trials, refund count, and net revenue/commission. Money in the window is net — a refund shows as a negative in the window it happened, the Stripe convention. Add &include=daily for a per-day series of the same fields, ready for charting; days with no activity are omitted.

The owner's personal tracking link and organic (non-affiliate) sales are excluded everywhere, matching List affiliates and the webhooks — so this summary reconciles with the roster.

The whole enrollment in one call: finds or creates the Affiliateo account for email, auto-joins your business, enrolls the user as an affiliate of the app, and returns their referral links plus starting stats. Safely repeatable: call it every time the user opens your affiliate screen, and an existing affiliate returns 200 with current links and stats instead of creating anything (account_created / affiliate_created tell you what actually happened).

The links.short URL is the canonical one (opaque code, survives renames): render QR codes from it. links.username is the readable variant. links.direct is your own domain with ?ref= appended (no redirect hop; the same parameter the short link hands off after its redirect, and ?via= / ?source= are read as aliases); it needs the tracking SDK or script live on the site to capture the click. For mobile apps it points at the app's landing page and requires the t.js snippet there (normal or instant-redirect mode) — or, fastest, your server can 302?ref= arrivals straight to the app's affiliateo.com/r/ link so the bounce happens before the page loads (see the mobile app docs); it's null when the app has no website or landing page URL.

links.coupon is the odd one out and the only member that is not a URL: it's the discount code the buyer types at your Stripe checkout (e.g. SWIFTPANDA), derived from the affiliate's username. It exists so someone on a podcast, a video or a livestream can be credited without anyone ever clicking a link. Don't render it as a link and don't encode it in a QR code — a bare code scans to nothing. It's null unless the app has coupon codes switched on and its Stripe account is still connected, so a merchant who disconnects Stripe stops advertising codes immediately (the codes themselves stay alive in Stripe on purpose — one already said on a podcast keeps working).

One thing you have to switch on yourself: your Checkout session needs allow_promotion_codes: true (or, on a Stripe Payment Link, the promotion-codes checkbox in the Stripe dashboard). Without it Stripe renders no "Have a promo code?" box, so the codes exist and no customer can ever type one in. We can neither set it for you nor detect that it's missing — the only symptom is that nothing is ever redeemed. It's the same setting that lets you run ordinary Stripe discounts, so most merchants already have it on. Store ref_code against your own user record so you can look the affiliate up later. The person can also sign into the Affiliateo dashboard any time with a magic link to the same email; it's the same account.

New accounts get an auto-generated username (the ref_code) unless you send one; name seeds the profile display name at creation only and never overwrites an existing profile. Apps with "require application approval" enabled reject this endpoint; those affiliates must apply in the dashboard.

Letting them pick their handle. Send an optional username and you can put a handle field next to the email field on your signup screen. It becomes the ref_code, so it is the readable half of every link that person hands out for the rest of their life on your app: affiliateo.com/r/acme-chat/janedoe instead of …/swiftpanda. Rules: 3–30 characters, lowercase letters, numbers, dots and underscores. We trim and lowercase for you, so JaneDoe arrives as janedoe.

It can never fail the signup. If the handle is taken, malformed, or on the reserved list, the account is still created and still enrolled — it just keeps the random one. That is deliberate: a cosmetic preference should not be able to break enrollment, so there is no error to catch here and no retry to write.

Because of that, you have to read the outcome rather than assume it. username_applied (boolean) and username_status come back on the response whenever you sent a username, and are absent when you didn't.

When it isn't applied, tell them which handle they actually got and that they can change it themselves at affiliateo.com — the first change is free, with no cooldown, and it rewrites their ref_code everywhere at once. Their links.short URL is unaffected by any of this, which is exactly why it's the one to print on a QR code.

account_exists is the case people forget. A username applies only when this call creates the account. Someone who already has an Affiliateo account may be an affiliate for several other businesses with links already in circulation, so a merchant they just met doesn't get to rename them. Since your form has no way of knowing which case it's in before it posts, expect this one and word it kindly.

A handle with no name also names them. If you send username without name — the natural shape of a form that asks for an email and a handle — the handle seeds the display name too, with dots and underscores read as spaces: jane.doe becomes Jane Doe, janedoe becomes Janedoe. That name is also what their auto-created business is called. Send a real name and it always wins; send neither and they get the random "Swift Panda" pair, as before. The point is that whatever they gave you is what names them, rather than two words they never saw.

A taken handle still names them — display names aren't unique, so someone else holding janedoe has no bearing on whether this person can be called Janedoe. They just get a random handle alongside it. A malformed one doesn't: garbage in the handle box must not become somebody's name.

Names are sanitised, not trusted. A name that impersonates the platform, staff, or a payment brand ("Affiliateo Support", "Stripe", "Admin") is replaced with a safe one, as are names made of emoji or stacked combining marks. It's the same rule the profile settings page enforces, and it never fails the call — you just get a different name than you sent. Nothing here is a reason to skip validating on your own form; it's the backstop, not the first line.

An affiliate who previously left your business is reactivated by this call (their original links and history come back). Someone you banned from your business is rejected with BANNED_FROM_BUSINESS; an account that is closed or banned platform-wide is rejected with a deliberately vague ACCOUNT_INELIGIBLE (so the API can't be used to probe someone's status on Affiliateo). Both are 403, and enrollment never un-bans.

Your own link: enroll your own email (the account that owns the business) and you get your personal tracking link instead — the same owner link the dashboard offers, for sharing your app yourself. It earns no commission and is excluded from List affiliates and App summary, but Get affiliate returns its clicks, stats, and breakdown like any other link, and QR codes render from its links.short the same way.

One affiliate's links, lifetime stats, and payout state, looked up by ?email= or ?ref_code=. Use this to render the affiliate screen in your app (clicks, sales, earnings) with a read-only key. stats.conversions + stats.renewals is the "sales" number the dashboard shows; money fields are cents.

payouts is the earnings ledger, always included: pending_cents (earned, waiting for the monthly payable transition), payable_cents (ready to be paid out, net of refund clawbacks), paid_cents (already credited to the affiliate's wallet), and refunded_cents (reversed by refunds or chargebacks). These are the same numbers as the dashboard's payout table.

payout is the readiness hint for gating your buttons: show the Verify button until payout.identity_verified is true, and the Cash out button once payout.payouts_enabled is true (identity done AND their Stripe payout account has nothing outstanding that the cash-out page can't collect itself; a missing bank never counts, since adding the bank is the cash-out page's own first step). It rides every affiliate response, including lists, with no extra latency; the hosted verify / cash-out pages still re-check Stripe live, so a just-changed status can never pay out incorrectly.

Add &include=breakdown for where the clicks came from: top sources (referrer origins, null = direct) and countries. The breakdown covers the last 90 days of raw clicks; stats.clicks is the durable lifetime counter.

Conversion history, newest first: the API version of the dashboard's Transactions tab. Each row carries the type (subscription, one_time, renewal, trial, refund, chargeback), the gross sale amount, the commission earned, its payout status, and the earning affiliate's ref_code. With ?email= or ?ref_code= it's one affiliate's history — the "your recent sales" feed for your embedded affiliate screen. With neither, it's the app-wide feed: every affiliate-attributed sale across the program (the owner's tracking link and organic sales are excluded, matching App summary).

Refunds and chargebacks appear as separate rows with negative amounts, linked to the original sale via original_conversion_id. No customer data is included: these rows carry money and status only. ?from=&to= narrows either mode to a date window (UTC days, inclusive), and ?type= to particular conversion types.

Both filters run in the query, upstream of the cursor, so a filtered feed pages through matching rows only. That is what makes a Type filter on your own screen work: filtering the page you already hold can only search the rows on screen, so "Refunds" finds nothing for an affiliate whose single refund sits 300 rows down. An unknown ?type= value is a 400 rather than an empty page, so a typo cannot be read as "no refunds".

Every affiliate of the app with links and lifetime stats, newest first: the same roster the dashboard's affiliates table shows (the owner's own tracking link is excluded). Responses don't include emails; correlate rows with your own users via the ref_code you stored at enrollment. Add &include=payouts to attach each row's pending / payable / paid / refunded buckets. Pagination is cursor-based: pass the last row's id as starting_after while has_more is true.

Add a "Verify" button next to your affiliate screen. This mints a short-lived hosted link (valid for expires_in seconds, reusable within that window so a page refresh resumes the flow); open it in the system browser from your site or app and the affiliate finishes everything needed to receive payouts on our domain: creating their Stripe payout account and passing identity verification (ID photo + selfie). The identity step needs camera access, so prefer the system browser over an embedded webview. Whichever steps they have already done are skipped, and an affiliate who is already paid-ready bounces straight back.

The link only works in the affiliate's hands. When it opens, we email a 6-digit code to the affiliate's address and the page stays locked until they enter it, so a minted link is useless to anyone who doesn't own that inbox (links minted self-serve via /api/v1/me/verification-link skip the code, since the affiliate's own key already proves who they are). On top of that, the link can only complete onboarding: it fills in whatever Stripe still needs and can never read or overwrite details an account already has.

When they finish we redirect the browser to your return_url with ?affiliateo_status=complete appended. If something can only be finished on the Affiliateo dashboard (a company-registered account, or an extra document Stripe requests), the page says so and the return link carries ?affiliateo_status=pending instead; complete is only ever sent when nothing is left to do. Use an https:// page for a website, or a mobile deep link (a Universal Link / App Link, or a custom scheme like myapp://verified) so the phone reopens your app. Confirm the result server-side with the affiliate.verified webhook or the verified field on the affiliate endpoints; a redirect alone is not proof.

Privacy: the sensitive data (SSN / tax ID, ID document, selfie) is entered only on our hosted page and goes straight to Stripe and our identity provider. It never passes through your servers, and Affiliateo stores only whether verification passed, never the documents.

The same gates as Create affiliate apply before a link is minted (ACCOUNT_INELIGIBLE / BANNED_FROM_BUSINESS, both 403). The link is short-lived (expires_in seconds); if it expires (even mid-flow), the affiliate is sent back to your return_url with ?affiliateo_status=expired, so mint a fresh link on arrival and reopen it — expiry heals itself without the affiliate retyping anything. v1 is individuals only — company / business affiliates onboard from the Affiliateo dashboard. Affiliates can also mint their own link with their own key via POST /api/v1/me/verification-link.

Add a "Withdraw earnings" button next to your affiliate screen. This mints a short-lived hosted link where the affiliate cashes out their Affiliateo wallet balance to a bank, entirely on our domain: they add or pick a bank account and withdraw, then get redirected back to your return_url with ?affiliateo_status=complete (=pending if they leave without withdrawing, =expired if the link had already expired — mint a fresh one and reopen it).

The link only works in the affiliate's hands. When it opens we email a 6-digit code to the affiliate's address and the page stays locked until they enter it (or they are already signed in as that same affiliate), so a minted link can't be used by anyone else (including you) to move their money. If the account has two-factor authentication enabled, the emailed code is not accepted at all: the page asks them to sign in to Affiliateo instead, which runs their normal 2FA challenge, then returns them to the same page unlocked. Only that person, behind the gate, adds their own bank and confirms the amount.

What they can withdraw is their account-wide wallet balance, not this app's payable. Affiliateo gives each person one wallet; once a commission is paid into it, it is simply their balance. The page shows THIS app's pending / payable / paid as context, but the cashable number is the whole wallet (minus the 7-day settlement hold), with a $20 minimum, exactly like the dashboard. Standard bank transfers always; eligible accounts (a debit-card-style payout method in a supported country) also get an Instant option that arrives within minutes for a higher fee.

This never creates or enrolls anyone (the email must already be an affiliate of this app, or you get NOT_FOUND). The affiliate does not have to be paid-ready first: one who still needs verification is walked through the get-paid-ready flow right on the same page, then continues straight into the withdrawal, so you can offer a single Cash out button and let the page sort out the rest. (Gating your buttons on the payout readiness object is still nicer UX when you want separate Verify and Cash out actions.) Requires a read-write key.

Give an affiliate your paid app for free, and take it back whenever you want. This is the same switch as the Access column in the Affiliates tab: it grants a promotional entitlement in your own RevenueCat project, so they see the paid experience without paying and the receipt stays in your account. RevenueCat apps only — everywhere else this answers not_revenuecat and free_access is null on the affiliate payload.

Two different emails, and mixing them up is the one real trap. email (or ref_code) says who the affiliate is, the same way it does on every other endpoint here. revenuecat_email says which RevenueCat customer receives the grant — the address that person uses inside your app, which is very often not the one they signed up to Affiliateo with. Leave it out and we use their Affiliateo address.

We match on email and nothing else. Never on who referred whom: the people attributed to an affiliate are the customers they referred, so treating one of those as the affiliate would hand a year of paid features to a stranger. That means your app has to tell RevenueCat each person's email (Purchases.setEmail, or the $email attribute) or there is nothing to match, and affiliates who used Sign in with Apple and chose Hide My Email cannot be resolved at all.

When no customer carries that address the call still succeeds with pending: true. That is a waiting state, not a failure — the switch is genuinely on and the grant lands as soon as a matching customer appears. Send revenuecat_email or entitlement_id on their own, with no enabled, to record them without touching RevenueCat; that is how you set the right address first instead of granting to the wrong customer and correcting it. Changing either while a grant is live moves it, revoking the old one first.

enabled: false always works, including on a paused or wound-down app, or one whose RevenueCat connection has broken. Turning it on is refused for your own tracking link, for affiliates who are not active, and for apps that are ending. Owner only: unlike the ads endpoints, a team member's key cannot reach this, because it spends your own revenue. Read the current state from free_access on any affiliate payload (enabled, pending, entitlement_id, revenuecat_email, granted_at, expires_at).

Every storefront affiliate of your business, newest first, each with their referral links (the canonical short and the storefront link with the ref tag), lifetime stats, and commission. stats.visitors is the lifetime click count. Add &include=payouts for each row's pending / payable / paid / refunded buckets. ?ref_code= returns a single affiliate. Cursor-paginated; emails are never included (correlate via ref_code).

Every sale your storefront affiliates drove, newest first: the type, the product (and price option), gross amount, commission, and payout status, each tagged with the earning affiliate's ref_code. ?ref_code= scopes to one affiliate; ?from=&to= to a date window. Refunds and chargebacks are separate rows with negative amounts.

Your storefront-affiliate program in one call: affiliate counts, lifetime totals (visitors, sales, revenue, commission, money net of refunds), and payout buckets across every affiliate. ?from=&to= adds a window with the net sales numbers plus link clicks for that period (click history exists from July 2026 onward). There's no per-day series, because business clicks are counted per day, not logged per event.

Your whole affiliate life in one call: how many apps you're an affiliate of, your lifetime totals (clicks, sales, renewals, revenue, commission), your earnings buckets (pending, payable, paid, refunded), and your account wallet balance, summed across every business you've joined. These are the same numbers your dashboard shows for the app-affiliate program.

Add ?from=&to= for a window object scoped to those dates (UTC days, inclusive), and &include=daily for a per-day series ready to chart. Money in the window is net — a refund shows as a negative in the window it happened. wallet.balance_cents is your account-wide withdrawable balance (every earning source, not just this program); cashing out happens on the dashboard or through the hosted withdrawal link.

Every app you're an affiliate of, across all your businesses, newest first, each with your referral links, lifetime stats, the app's current commission, and which business it belongs to. Add &include=payouts to attach each row's pending / payable / paid / refunded buckets. Pagination is cursor-based: pass the last row's id as starting_after while has_more is true.

Each app carries a rails object saying what it actually sells on — a website, a mobile app, or both — plus the connected provider on each side and that rail's percent ceiling. Read rails, not content_type: the affiliate type is always affiliate_app, and it says nothing about rails. An app can gain or lose either rail at any time without its type ever changing. The single commission.rate covers both rails and is clamped per sale to whichever ceiling applies (70% when Apple or Google take their cut, 90% otherwise).

If you also own a business and made a personal tracking link for your own app, it appears here with is_owner_link set to true (it earns nothing); filter it out client-side if you only want links where you're a third-party affiliate.

Add ?app= (the app UUID or slug) to zoom into a single affiliation. On that view, &include=breakdown adds breakdown — where your clicks came from: top sources (referrer origins, i.e. the platforms, with null = direct) and countries — and &from=&to= adds windowed_clicks (clicks in that date range). The breakdown covers the last 90 days of raw clicks; stats.clicks stays the durable lifetime counter. These scan raw clicks, so they're only available with ?app=, not on the full list. Everything you need for a QR code is already here: render it from links.short, the canonical link (the dashboard makes its QR the same way).

Your sales feed across every business you're an affiliate of: the API version of your dashboard Transactions tab (app-affiliate rows). Each row carries the type (subscription, one_time, renewal, trial, refund, chargeback), gross amount, commission, payout status, and the app + business it came from. Refunds and chargebacks are separate rows with negative amounts.

payable_at is when the commission becomes (or became) available for the business owner to pay out, set by the payment processor that carried the sale: 14 days after the sale on Stripe, Shopify, WooCommerce, Whop and Polar, or the 1st of the next month for Paddle and App Store or Play Store sales. It is null once the commission has been paid, and on rows that never pay out (organic sales, trials, reversals).

?app= narrows to a single app (UUID or slug); ?from=&to= narrows to a date window (UTC days, inclusive). Cursor-paginated like My affiliations. No customer data is included.

Your one account wallet and the buckets behind the balance, all in cents. There is a single wallet per account, so this is the same money whether you're a business owner or an affiliate. balance_cents is the total; withdrawable_cents is what you can cash out right now (the balance minus anything still under the 7-day hold).

The rest explain the difference: held_cents is recent earnings still on hold, pending_deposits_cents is bank deposits still clearing (not yet in the balance), locked_app_cents is unspent ad budget you've committed, disputed_cents is commission tied up in open disputes, and in_transit_cents is withdrawals already on their way to your bank (the outgoing mirror of pending_deposits_cents, already out of the balance). payout_account_connected tells you whether a payout destination is set up, and payout is the same readiness hint the affiliate endpoints carry (identity_verified + payouts_enabled) for gating Verify / Cash out buttons. This endpoint is read-only; moving money happens on the dashboard or through the hosted withdrawal link (see Cash out yourself).

Your account wallet ledger, newest first: every money movement on your wallet, the API version of the dashboard Transactions tab. Each row has a type, a signed amount_cents (direction is credit for money in, debit for money out), gross_amount_cents and fee_cents where a fee applies, and a counterparty — the other side of the movement (the buyer on a sale, the business on a commission, the app on ad funding, the other person on a transfer).

Types you'll see: sale, deposit, payout (a withdrawal), refund, chargeback, transfer_in / transfer_out, affiliate_commission, and campaign_fund / campaign_refund / campaign_payout (ad budget). ?type= filters to a comma-separated set. On payout rows the status is the honest withdrawal state, in_transit (on its way to the bank), paid (arrived), or failed (reversed), and the payout object carries the bank, the estimated_arrival, and the completed_at once it lands. Cursor-paginated: pass the last row's id as starting_after while has_more is true. Pending bank deposits aren't in the ledger yet — they show on /me/wallet as pending_deposits_cents until they settle.

GET /api/v1/me/transactions/{id} returns one transaction by its id or short_id (e.g. pay_…). For your own deposits it also returns the Stripe receipt_url and the card or bank used; for commission rows it adds product_name and the paying business. A buyer's receipt or card on a sale is never exposed.

The storefront side of your summary: your business-affiliate life in one call, across every business you promote, affiliation counts, lifetime totals (visitors, sales, revenue, commission, money net of refunds), and payout buckets. ?from=&to= adds a window with the net revenue, commission, and link clicks for that period (click history exists from July 2026 onward), the direct answer to "what did I earn from storefront sales this month". This is the storefront counterpart to /me/summary; your wallet balance lives there (it's one account-wide wallet). No per-day series here, since business clicks are counted per day, not logged per event.

The storefront (business/product) side of your affiliate life: every business you're promoting as a storefront affiliate, with your referral links, commission, and lifetime stats. This is separate from /me/affiliations (which is the app program). ?business= (UUID or slug) narrows to one; &include=payouts adds each row's earnings buckets. Cursor-paginated. Render QR codes from links.short.

Your storefront-affiliate sales across every business you promote: date, type, the product, amount, commission, and payout status, each tagged with the business it came from. ?business= narrows to one; ?from=&to= to a date window. Refunds and chargebacks are separate negative rows. No customer data is included.

The self-serve twin of the app-affiliate Get an affiliate paid-ready endpoint: mint a link for yourself with your own key. It opens the same hosted flow (Stripe payout account + identity verification, whichever you still need) and redirects to your return_url when done. No emailed code here: your own key already proves who you are, so the page opens directly. Requires a read-write key.

The self-serve twin of Let an affiliate cash out: mint a withdrawal link for yourself with your own key. It opens the same hosted flow (add or pick a bank, then withdraw your account wallet balance, $20 minimum) and redirects to your return_url when done. No emailed code and no sign-in here: your own key already proves who you are, so the page opens directly. withdrawable_cents in the response is your own available balance right now, so you can decide whether to even show the button. Requires a read-write key.

POST registers a receiver. The secret (afwh_…) appears exactly once in the 201 response: store it server-side and use it to verify every delivery's signature. GET lists your endpoints (never with secrets), PATCH /api/v1/webhooks/{webhookId} updates the url or events or flips status, and DELETE removes one. Up to 10 endpoints per account.

By default an endpoint receives events for every business you own; pass business_slug to pin it to one. An endpoint that fails continuously for days is auto-disabled (you'll see status: "disabled" and a disabled_reason); fix your receiver and PATCH it back to "active", which resets the failure counter.

Every delivery is a POST with a JSON envelope: a deterministic id (the same event never has two ids, so you can deduplicate on it), a type, the event time, and the data object.

Verify the signature before trusting a delivery. The Affiliateo-Signature header carries a unix timestamp and an HMAC-SHA256 of "{t}.{body}" keyed with your afwh_ secret. Recompute it over the raw request body, compare with a constant-time comparison, and reject stale timestamps (older than ~5 minutes) to block replays. Respond with any 2xx quickly; do slow work after acknowledging.

Aggregated spend, impressions, clicks, installs, attributed revenue, and ROAS, grouped by level. roas is revenue ÷ spend and is null until revenue attribution is ready. Money fields are micros (1,000,000 = 1 currency unit).

Two revenue numbers come back side by side. revenueMicros / roas are verified: computed from sales Affiliateo itself recorded and tied to an ad click. reportedConversions / reportedRevenueMicros / reported_roas are what the network claims from its own pixel or conversion tracking (self-reported, usually generous; null or 0 when the network reported nothing). Apple Ads reports no revenue, so its reported fields stay empty.

auctionShare answers how much of the auction you won and why you missed the rest, on totals and on every row. limitedBy is the field to act on: "rank" means your bid or ad quality was too low to enter the auction (raise the bid), "budget" means you ran out of money that day (raise the budget). The two have opposite fixes, so guessing between them is how a campaign gets changed in the wrong direction. All ratios are 0–1. eligibleImpressions is the estimated number you could have had.

Google only. Meta, TikTok and Snapchat publish no equivalent and never will: an auction-share number needs a fixed slate of competitors bidding on the same query, which is a search-results idea, not a feed one. Apple Search Ads has one, but as a separate asynchronous report at /api/v1/businesses/{slug}/ads/impression-share. On every other network auctionShare is null, and null never means zero.

Two honesty flags worth reading before you trust a number. approximate: true means at least one day was censored by Google, which reports anything under 10% as exactly 0.0999 and anything over 90% as 0.9001, in the API and in its own dashboard alike, with no way to get the real figure. When the floor is involved your true share is lower and your true loss higher than shown. And auctionShare is null for the most recent day or two even on Google, because impression share is estimated on a 1–2 day lag; that is a pending estimate, not a campaign that reached nobody.

The live campaign → ad set → ad tree straight from Meta, as a flat list. Each entity carries kind, status (ACTIVE/PAUSED), effectiveStatus (includes review states), dailyBudgetCents, parentId, and campaignId. Rebuild the tree from the parent links if you need it nested.

Always check tree_error before trusting the list. The tree is built top-down: campaigns first, then a second pass for everything underneath them. If that second pass fails, the response is still a 200 carrying the campaigns it already had, with tree_error: true. Treating that as a complete list is how an agent concludes an ad set was deleted when it was only unread, and then recreates it. tree_error_reason carries the network’s own message when it gave one, so the failure can be logged or retried on rather than guessed at.

Applies to meta, apple_search_ads, tiktok and snapchat. Google is the exception: its tree arrives in a single call, so it either returns in full or fails with a 502 carrying Google’s message, and it has no tree_error field to check.

Creates the full stack (campaign, ad set, creative, ad) in one call, with the same validation as the in-app wizard. Requires a read & write key. The campaign is created PAUSED on every network, so nothing spends until you activate it via the entity endpoint — that one switch is the gate. Below it the launchers differ: Google's Search stack creates its ad group, ad and keywords ENABLED on purpose, because a keyword that arrives paused inside its own ad group is a silent no-op you would have to undo by hand before the campaign could do anything. Upload media first. The sales objective requires the conversion pixel — and it is the only one that does: an app campaign optimises against an app id rather than a pixel, so it launches fine on a connection that has never had one. If any step fails, the freshly created campaign is rolled back, so a failed launch never leaves a half-built stack.

Campaigns created through this endpoint (any network) carry the 1% ads platform fee on their spend, metered from the business wallet as spend syncs. So does any campaign you manage through Affiliateo: a successful write on it or anything under it — through this API, the dashboard or an MCP agent, a pause included — starts metering that campaign from that day forward. Creating a child object counts the same way: adding an ad set, ad group, ad, keyword or criterion inside a campaign you built in the network's own manager meters that campaign, from that day. The child is never metered separately, because its spend already rolls up into the campaign's. It is never retroactive, and connecting an account to read stats costs nothing. Unpaid fees (including estimates on the last days of spend the wallet can't cover) pause the ads endpoints with PAYMENT_REQUIRED (402) past a grace allowance; past the account's campaign-pause limit (starts at $50 and rises to $1,000 with clean payment history), the metered campaigns are paused on the networks themselves and can only be resumed once the balance is back to zero (top-ups collect automatically and unlock instantly). A campaign you have never created or written to through Affiliateo is never metered and never touched.

Accounts that signed up through a partner link pay no platform fee for their first 7 days, and ad spend is included. The trial is priced per spend DAY, not by when the meter runs: a day inside the window is written free and stays free even though fees settle a couple of days behind, so a sync or a cron catching up after the trial ended never bills it. See Partner program.

Two writes are refused while any billed fee is outstanding, however small and well below that grace allowance: switching a metered campaign back to ACTIVE, and creating a campaign that starts ACTIVE. Creating one paused is never blocked — it spends nothing, so it owes nothing — and it can be switched on the moment the balance reaches zero. This endpoint is unaffected: it creates every campaign paused on all five networks, so it could not have started spend anyway. The refusal is there for field writes, which can set a status at create.

The same endpoint also creates campaigns on the other four networks: ?network=apple_search_ads (see Create campaigns), ?network=google (see Create campaigns, pending Google approval), ?network=tiktok (see Launch campaigns), and ?network=snapchat (see Launch campaigns). The objective field is not the same on any two of them, and three read an unrecognised value as traffic rather than refusing it, so follow the link for the network you are launching on rather than reusing this body's vocabulary.

Meta is the only network whose placement choice this endpoint collects and puts on the wire, which is a narrower claim than the one that used to be made here and is the only one that survives reading the other four. adset.publisherPlatforms is carried end to end. It is not that the others have no placement field: Snapchat declares placement_v2 on the ad squad and Google declares network_settings on the campaign, both of them mutable through field writes. The launch body simply does not ask for either, so a placement decision on those two is made after the campaign exists rather than inside it.

Three of this body's fields moved from API-only to also-in-the-dashboard this phase. specialAdCategoryCountry is a row of country chips that appears once a regulated category is declared, contextualMultiAds is a control on the creative step (default UNSET, which is not OPT_OUT), and the fanOut.extraAds half of the creative fan-out is the launcher's creative test. fanOut.extraAdGroups did not move and is still API-only.

Updates one entity at any level. This is the endpoint that starts real spend (flipping PAUSED → ACTIVE), so it requires a read & write key.

ARCHIVED is Meta's "delete": the entity stops delivering, disappears from the campaign tree, and keeps all its reporting and revenue history. It is one-way: Meta never allows archived objects back to ACTIVE or PAUSED. Pause instead unless you're sure.

Campaigns also take a lifetime spend cap: { "spendCapCents": 15000 } caps the campaign's total spend (minimum 10000 = 100.00), { "spendCapCents": null } removes the cap.

The Facebook Pages the connected Meta login manages. A launch needs one of these ids as ad.pageId, the identity the ad publishes as.

GET returns the current pixel; POST enables conversion tracking by adopting the ad account's existing pixel or creating one (Meta allows exactly one per account). Idempotent; requires a read & write key. Enabling it unlocks the sales objective, and recorded sales start flowing to Meta server-side via the Conversions API automatically.

Pulls the freshest insights from Meta into Affiliateo right now (stats otherwise refresh nightly). Read keys may call it: it refreshes data, it doesn't spend.

The ad account's money state: balance, lifetime spend, spend cap, prepay flag, and the payment method label. Read-only by design: no ads API (Meta's included, any vendor's) can add funds or manage payment methods. That always happens in Meta Ads Manager. spendCapCents is null when no cap is set.

PATCH manages the one money control that does exist, the account spend cap. Requires a read & write key; responds with ok plus the fresh billing fields.

Standing automation that runs on Meta's side, on Meta's schedule: rules keep working long after the agent session that created them is gone. The example pauses any ad set whose cost per purchase blows past 40.00 over the last 3 days (money values in filters are cents).

GET lists the account's rules (id, name, status, evaluationSpec, executionSpec, scheduleSpec, createdTime). PATCH …/rules/{ruleId} renames, re-specs, or flips status between ENABLED and DISABLED and returns { ok, ruleId }; DELETE …/rules/{ruleId} removes the rule and returns { ok }. Writes require a read & write key.

GET lists the account's audiences with size bands (approximateLowerBound / approximateUpperBound), subtype, operationStatus, retentionDays, and timeUpdated. POST creates one of four kinds: website (pixel visitors; needs the pixel enabled; no filter = all visitors), engagement (everyone who engaged with a Facebook Page), app_activity (everyone a mobile app's SDK saw — the appId is a Meta app id, not an App Store or Play id, and those two namespaces are not interchangeable), or lookalike (people similar to a seed audience).

Customer-list uploads (hashed emails/phones) are deliberately not offered: rule-based audiences cover the same jobs without customer PII flowing through us. One-time gate: the ad account owner must accept Meta's Custom Audience terms once; the error message links straight to the accept page.

Three other networks answer this same path — TikTok with its own vocabulary, Google and Snapchat with a shared one. See Audiences, across the networks for the cross-network view, the machine-readable capability catalogue, and — the part worth reading before you build one — how to point a campaign at it at create.

DELETE …/audiences/{audienceId} returns { ok }. Meta refuses the delete while live ad sets still target the audience.

URL-rule conversions on top of the pixel: "a pageview of /thank-you counts as a registration worth 49". GET lists them (id, name, customEventType, rule, defaultConversionValue, creationTime); DELETE …/custom-conversions/{conversionId} removes one and returns { ok }. Needs the conversion pixel enabled; Meta caps an account at 100 custom conversions. Writes require a read & write key.

The same path serves ?network=tiktok, but the words mean different things there: a Meta custom conversion is an object on the ad account, a TikTok one is an event rule living on a specific pixel, so every TikTok call needs a pixelId and the two create bodies share nothing. See TikTok custom conversions before reusing a body across networks.

Raise a campaign's or ad set's budget for a window — Meta's high demand periods. This is not the campaign field budget_schedule_specs, and the difference is the whole reason the endpoint exists: that field is create-only, so a boost could be declared in the same breath as the campaign and never afterwards. This works on campaigns that already exist.

Three facts from Meta's own reference make every schedule a one-way write. A schedule cannot be deleted, cannot be updated, and does not recur — so "every Friday" is twelve permanent objects, not one recurring one. That is why there is no polite PATCH or DELETE here answering 501: the API should not suggest a repair that does not exist, so those verbs return 405 with an Allow header. It is also why a window that has already ended is refused rather than posted. To undo one, lower the budget or pause during that window.

Meta only. The other four answer 501 with the reason: Google models scheduled budgets on campaign budget resources, TikTok and Snapchat publish no equivalent, and Apple has no budget schedule of any kind.

How many people a targeting spec reaches, before spending anything: the sanity check an agent runs between picking targeting and launching. Takes the same simple targeting fields the launch takes and echoes back the Meta targeting spec it built.

One lookup endpoint for every id that targeting specs are built from, dispatched by network + type.

Prefer id lookups for anything new. This endpoint answers in a different shape per network — id here, adamId there, locationId somewhere else — so a caller wanting one picker has to write four readers. It covers eight lookups on four of them; …/ads/lookups covers those same eight in one shape plus everything the other registries declare, Snapchat included. This one stays because the campaign launcher calls it and its responses are what existing integrations parse; nothing about it has changed.

Meta (default): type=interest returns interest ids with audience-size bands; type=location returns location keys ({ key, name, type, countryCode, countryName, region }), and it's the key that goes into targeting specs. Apple Search Ads: type=app (min 3 characters) returns the adamId campaign creation needs; type=geo with country + entity returns pipe-format geo ids ({ id: "US|CA|Cupertino", entity, displayName }) for ad group targeting. TikTok: type=region returns { locationId, name, level } for the launch endpoint. Google Ads: type=geo and type=language, documented under Google Ads targeting search.

Same parameters and response shape as Meta's Ad stats & ROAS, with network=tiktok.

On-demand refresh of TikTok reporting.

As on every network here, everything is created PAUSED: an agent can build a full stack, but starting spend is an explicit PATCH on the entity.

Creates the full campaign → ad group → ad stack in one call. Media rides POST …/ads/media?network=tiktok (returns { image_id } or { video_id, cover_url }); pixels ride GET …/ads/pixel?network=tiktok (returns { pixels: [{ pixel_id, pixel_name }] } and works today, the pixel scopes are already live). Manage what you launched via PATCH …/ads/entities/{id}?network=tiktok with { kind, status, dailyBudgetCents } (status ACTIVE or PAUSED); TikTok applies ad-group daily budget changes at 00:00 account time (their rule).

Two launch paths, one endpoint, and smart_plus is the one that runs first. This paragraph described the reverse order until 6 August 2026 and was wrong from the day the order flipped: the launch tries the Upgraded Smart+ stack first and keeps the classic manual stack as the STANDBY. Manual is attempted only when Smart+'s CREATE endpoint refuses, which is deliberately narrow — a bad budget or a rejected identity surfaces immediately from the path you meant to use rather than being retried and reported twice. After 31 December 2026 manual creation stops answering at all, so the standby removes itself without anyone editing anything. The response says which family answered in path (smart_plus or manual), and that matters: the two families are hard-partitioned, so a later edit has to send the matching kind — which is why the note quotes it back at you. A fallback that happened is reported in fell_back_from. Smart+ is gated on no approval — its campaigns and ad groups create on an ordinary account — and it now finishes: the call-to-action refusal that used to stop it two thirds of the way is answered by a dynamic CTA portfolio id sent inside ad_configuration, which the launch builds for you, and the whole campaign → ad group → ad stack is verified live as of 4 August 2026.

Two body fields make a launch fall back to manual, and after the sunset they are a refusal. TikTok publishes no Smart+ field for adgroup.subplacements or ad.showcaseProducts, so a request naming either is refused on the Smart+ path before the first create and built by the manual family instead — which does carry both. Refusing rather than dropping them is the whole point on the sub-placement one: naming no sub-placements runs on every TikTok surface, so silently discarding the list does not lose a preference, it buys the surfaces you just excluded. Once manual creation stops on 31 December 2026 that message is the whole answer, and it is a true one: drop the two fields to launch on Smart+. Inventing a Smart+ field would be worse than saying no, because TikTok answers a field it does not recognise with silence rather than an error — the same way it discarded call_to_action_id and music_id before both were nested correctly.

One goal has no Smart+ form at all, and it is engagement. Smart+ publishes three campaign objectives — app promotion, web conversions and lead generation — so a Spark Ads campaign is the single TikTok goal with nothing to fall back to when manual creation stops on 31 December 2026. The other five all have a Smart+ shape, catalogue selling included.

kind takes campaign, adgroup or ad, and also smart_plus_campaign, smart_plus_adgroup and smart_plus_ad. Smart+ is a separate endpoint family, and nothing in an id says which family owns it — so with a bare name we ask TikTok, which costs one extra call. Send the smart_plus_ name when you already know and we skip the lookup. Everything else about the request is identical.

Who a TikTok ad publishes as. GET lists the identities the launch endpoint's identityId accepts. POST creates a Custom User identity and returns 201 { identityId, identityType: "CUSTOMIZED_USER", note }: since Jan 2026 a custom identity works only on Pangle and the global app bundle, so an ad that can reach TikTok placement needs a Spark identity (TT_USER / AUTH_CODE / BC_AUTH_TT) from the list instead. The launch endpoint enforces that rule against the placements you chose rather than blanket-refusing custom identities — a Pangle-only ad group takes one, and that is what it is for.

Ad-account balances (cash, grants, frozen funds, in cents) grouped by Business Center. Read-only: funds enter TikTok only through their UI or an invoicing credit line. No ads API anywhere (TikTok's, Meta's, anyone's) can charge a payment method.

Needs TikTok's Audience Management permission, which TikTok has granted (verified live 2026-08-02). Same path as Meta's Custom audiences, with ?network=tiktok.

GET lists the advertiser's custom and lookalike audiences under audiences (audienceId, name, audienceType, coverNum, isValid, isExpiring, expiredTime, plus raw with TikTok's untouched row); &ids=900,901 narrows to specific ones (TikTok caps that list at 100). POST creates kind=rule (everyone one of your own signal sources saw) or kind=lookalike (people similar to a seed audience). PATCH …/audiences/{audienceId}?network=tiktok takes { name } to rename or { refresh: true } to recalculate a lookalike, one or the other per call, never both. DELETE …/audiences/{audienceId}?network=tiktok removes one. Writes require a read & write key.

Saved audiences are a different object, not another kind of audience. A saved audience is a whole reusable targeting set (locations, ages, languages, interests, plus which custom audiences to include and exclude) and it is what an ad group's saved_audience_id points at. Add ?type=saved on any verb: the list answers under savedAudiences rather than audiences, so the two id spaces never arrive mixed together, and the discriminator is required on the delete because the ids look identical. TikTok publishes no saved-audience update at all, so PATCH ?type=saved is refused rather than pretending: create a new one and delete the old.

The two numbers both named after retention are not the same number. lookbackDays decides who is IN the audience (how far back TikTok looks for the action); expireInDays decides when the AUDIENCE ITSELF dies. Swap them and TikTok accepts the call and builds a different audience, with no error anywhere.

Customer-list uploads (hashed emails and phone numbers) are deliberately not offered on TikTok either, the same decision as Meta: rule-based audiences cover the same jobs without buyer PII flowing through us, and a purchaser audience plus a lookalike seeded from it needs no upload at all.

Needs TikTok's DPA Catalog Management permission, which TikTok has granted. Catalogs are what dynamic product ads serve from, and they are where the four id fields the write surface declares actually come from: catalog_id, product_set_id, sku_ids and item_group_ids.

A catalog is Business Center scoped, not ad-account scoped. TikTok requires bc_id on every catalog endpoint and advertiser_id appears exactly once in that whole surface, as an optional filter on the upload log. So this is the one ads route where ?account= is the wrong axis, and it is refused with a 400 rather than ignored: pass ?bcId= instead. Omit it entirely and we use the only Business Center the TikTok login can see; if it can see several we refuse and list them, never "the first one".

GET …/ads/catalogs lists them (catalogId, bcId, name, catalogType, regionCode, currency, productCount); ?catalogId= narrows to one, ?resource=countries lists the region codes this Business Center may create for, and ?resource=currencies lists location/currency pairs (the one catalog read that needs no Business Center at all). POST creates a catalog. currency and regionCode can never be changed afterwards: TikTok's update takes a name and nothing else, so a typo means delete and rebuild, which is why both are shape-checked before the call.

One catalog and everything inside it lives at …/ads/catalogs/{catalogId}, on a ?resource= discriminator because a catalog's parts are not independently addressable on TikTok's side either: sets (where a real product_set_id comes from), products with &productSetId= (where sku_ids and item_group_ids come from), upload-log with &feedLogId=, the feed upload (POST ?resource=products), the rename (PATCH), a set rename or re-rule (PATCH ?resource=sets) and three deletes (the catalog, ?resource=sets&productSetIds=, ?resource=products&skuIds=). A product delete with no ids at all is refused here rather than sent.

Two asymmetries worth knowing before you plan around them. A product feed is a URL TikTok fetches, not a file we send, so the upload answers 202 with a feedLogId and means "queued": the per-row verdicts only appear in the upload log. And TikTok has no create for product sets at all (their API has get, update and delete only), so a set is made once in Business Center and read back here. Writes require a read & write key.

The same path serves two other networks, on two other scopes — which is the thing to know before reaching for ?bcId=, because scope is what differs here and not the operations. ?network=snapchat lists and creates catalogs on the organization, which comes from the connection, so there is no scope parameter to pass at all; its create is { name, vertical? } with vertical defaulting to COMMERCE, and currency / regionCode are refused by name rather than dropped, because a Snapchat catalog has neither — currency belongs to each product feed — and silence would teach you your catalog is scoped to a market it is not. Rename and delete work; product feeds do not. ?network=google is not a catalog at all but the Merchant Center link, which hangs off the ad account, so ?account= is the right selector there: GET lists linked accounts (where shopping.merchantId comes from), POST { merchantCenterId } links one when you are admin on both, &resource=invitations is where a link started from the Merchant Center side waits to be accepted, and DELETE with &productLink= unlinks without touching the catalog itself. Meta answers 501: catalog_management was not granted by App Review. Product sets exist on TikTok only — Snapchat publishes no endpoint that lists one anywhere in its Marketing API, which is precisely why it can list catalogs and still not launch a product-sales campaign.

Needs TikTok's App Management permission, which TikTok has granted. This is the read that makes the app_id field usable: it is declared at campaign, smart_plus_campaign and smart_plus_adgroup level and there was previously no way anywhere to obtain a value for it, so app-promotion campaigns could not be built at all.

These are not Affiliateo apps. /api/v1/businesses/{slug}/apps is your affiliate programs; this path is the mobile apps a TikTok advertiser has registered for promotion. Different namespace, different ids, one unfortunate word. Responses call the id tiktokAppId for that reason, and ?appId= is accepted as an alias so a guess still gets an answer.

GET lists them; ?tiktokAppId= alone returns one app's detail; &resource=optimization-events&optimizationGoal=… returns the events THIS app may legally bid on for THAT goal, which is what an ad group's optimization_event takes. optimizationGoal is required precisely because the legal set depends on it, and availableOnly=false and isSkan=false are meaningful requests that survive as false rather than being coerced away. &resource=retargeting-events answers the same question for an APP_RETARGETING campaign, which TikTok serves from a different endpoint with a different answer.

Read-only on purpose. TikTok's app API has six operations and none of them is a delete, so a mistaken registration is permanent on the advertiser; and the tracking_url fields on a registration are third-party measurement postbacks carrying device identifiers on every click and impression, which is a product decision rather than an API convenience. Register apps in TikTok Ads Manager; this route then makes them discoverable.

Needs TikTok's Automated Rules permission, which TikTok has granted. Like Meta's, a TikTok rule runs on TikTok's side on TikTok's schedule, so it keeps working long after the agent that created it is gone. Unlike Meta's, it is a genuinely different object rather than a dialect: conditions, actions, applyObjects, notification and ruleExecInfo, all required. The vocabularies inside them (metric names, action types, dimensions, schedules) are typed as plain strings by TikTok with no published enum, so we validate the STRUCTURE and let TikTok validate the words: an invented allowlist here would refuse values TikTok accepts while looking like verified validation.

Money comes in two spellings and you pick one. Our boundary is minor units, TikTok reads rule thresholds in major units, so valuesCents / valueCents / limitCents are cents and we convert, while values / value / limit are dollars and pass through untouched. Sending both spellings of the same number is refused rather than guessed: guessing is how a rule meant to fire at $40 fires at $4000, or never.

PATCH is a FULL REPLACE on TikTok and a partial on Meta, on the same verb and the same path. TikTok requires every create field on an update, so a Meta-shaped { "name": "x" } aimed at TikTok would return 200 having stripped the rule of its conditions, actions and schedule. We refuse a body missing any required part, name the missing parts, and echo replaced: true on success. Read the rule with GET …/ads/rules/{ruleId}?network=tiktok, merge, then send the whole thing.

TikTok has no rule delete and no on/off switch. Their automated rules API is seven endpoints and none of them removes or disables a rule, so DELETE …/rules/{ruleId}?network=tiktok answers 400 saying so and names the two things that do work: PATCH a narrower applyObjects list (a full replace, so the new list becomes the whole coverage), or remove it in TikTok Ads Manager. Meta's delete is unaffected.

Two more TikTok-only pieces. POST …/ads/rules/{ruleId} binds an EXISTING rule to more campaigns, ad groups or ads: it is its own operation rather than a create-time convenience, because folding it into the create turns one call into two writes whose half-failure looks to the caller like nothing happened, and there is no delete to undo the orphan with. And GET …/ads/rules?view=results is the audit trail of what the rules actually did, which unattended automation needs; &detail=1 chains the per-result detail for the first 20 rows and reports details_truncated rather than truncating silently. ?view=results&network=meta is refused instead of answering [], because an empty audit trail reads as "your rule never fired". Writes require a read & write key.

Works today. These endpoints ride Pixel Management, granted 2026-07-15, not the similarly named Custom Conversion Managementpermission in TikTok's portal, which guards none of them.

"Custom conversion" names a different object on each network, which is the single thing most likely to be got wrong here. On Meta it is a first-class object on the AD ACCOUNT that watches pixel traffic and fires when a URL matches, independent of any one pixel, capped at 100 per account. What this endpoint manages on TikTok is an event rule living ON a pixel, which is why every TikTok call here takes a pixelId (from GET …/ads/pixel?network=tiktok) and why deleting one changes that pixel. Every TikTok endpoint here sits under /pixel/ and TikTok guards them withCreate and Update Pixels. The two create bodies therefore share nothing: reusing Meta's body here is a 400, not a partial success.

This page used to say TikTok has no custom conversion object at all. It does. Corrected 5 August 2026 after a live call: TikTok publishes a separate first-class family at /custom_conversion/ — list, get, create, update and delete — keyed by custom_conversion_id and scoped by an event SOURCE that can be an app as well as a pixel. This endpoint does not wrap it; a pixel event rule is a real and useful object, but it is a different object, and the two were conflated. That family is READABLE at GET …/ads/resources?resource=custom_conversion&network=tiktok with eventSourceId and eventSourceType=PIXEL|APP — and the same ids answer as an id LOOKUP at GET …/ads/lookups?network=tiktok&type=custom_conversion&eventSourceId=…, which is what fills the Smart+ ad group's custom_conversion_id. Its writes are deliberately not wrapped anywhere: all three endpoints exist, no request body for them has ever been observed, and TikTok answers an unrecognised field with silence rather than an error — so a create typed from a doc read can succeed while dropping the rule that makes the conversion mean anything.

The event vocabulary is the other trap. TikTok runs two of them: the Events API speaks Purchase, AddToCart, Lead, while pixel event rules and the ad-group optimisation goal speak SHOPPING, FORM. eventType here is the second one, because the only reason to make a custom conversion is for an ad group to bid on it. An Events API name is refused up front with a 400 naming the right one: TikTok's own response to an unrecognised name is to file it quietly as a custom event, return success, and leave a conversion no ad group can ever optimise toward.

GET …?network=tiktok&pixelId= lists one pixel's events (one pixel per call). &view=stats with pixelIds plus a startDate/endDate window answers the debugging question, since a conversion that was created successfully and never fires looks exactly like one that works until the campaign underdelivers. PATCH …/custom-conversions/{id} is a true partial (name, currency, value only; the event type and its rules are delete-and-recreate) and is TikTok-only, because Meta publishes no update we wrap. DELETE returns { ok, note } and the note is the warning: TikTok is not documented to refuse deleting an event a live ad group still optimises toward, so the call that reads as safe on Meta can strip a running ad group of its signal and still answer 200. valueCents is minor units at our boundary on both networks; TikTok takes major units on the wire and we convert both ways.

The same five operations are also reachable under the pixel path as ?resource=events. Neither is a wrapper around the other: this path groups the feature with Meta's equivalent, that one groups it with the pixel it physically belongs to. Use whichever reads better in your code. Writes require a read & write key.

GET …/ads/pixel?network=tiktok lists the advertiser's pixels, which is what the conversions objective and the custom-conversion calls take as pixelId. This read has worked since TikTok granted Pixel Management, and so does the new PATCH …/ads/pixel?network=tiktok with { pixelId, pixelName }, which renames a pixel: it rides that same granted permission, so it is the one thing in this batch that is live now.

POST …/ads/pixel?network=tiktok with { pixelName } creates the pixel itself, and returns its pixel_code. pixelName is required rather than defaulted from the business, because TikTok offers no way to DELETE a pixel — only to rename one — so an accidental empty POST would leave a permanent object on the advertiser. The response carries action_required: "install_pixel_code" for the same reason Google's WEBPAGE conversion carries install_tag: a fresh pixel tracks nothing until its code is on the site AND an event exists for a campaign to bid on, which are two more steps this call did not take.

?resource=events is TikTok's custom conversions on the path they physically belong to (there is no separate object, and every TikTok endpoint for them lives under /pixel/): GET with &pixelId= lists them, POST creates one, PATCH edits one, DELETE with &eventId= removes one, and ?resource=stats with &pixelIds=&startDate=&endDate= reports whether they are firing. Those five ride Pixel Management and work today, and they are the same operations documented at TikTok custom conversions (including the SHOPPING-not-Purchase trap and the minor-units rule). Writes require a read & write key.

The other half of a lead campaign. Everything else in this API can create a lead campaign; this is what reads the leads back out, so an owner who ran one here does not have to open TikTok Ads Manager to see what it caught.

Three reads behind one endpoint. With no pageId it lists the Instant Forms on the ad account, which is where ad.pageId on a TikTok launch comes from. resource=leads returns the leads themselves, and &resource=fields returns the form's questions as plain strings, plus the form's own name and public URL.

Both lead reads need leadSource, and it has exactly two values. INSTANT_FORM reads one form and also needs a pageId; DIRECT_MESSAGE reads leads collected in TikTok DMs and takes no pageId at all. That second source is easy to miss and it means an account with zero Instant Forms can still have leads. TikTok requires the parameter and refuses either read without it.

There is no paging, because TikTok implements none. This endpoint used to publish page, pageSize and hasMore. TikTok ignores page and page size on the lead read and publishes no list endpoint to walk, so those knobs described a pagination that does not exist and have been withdrawn. One call is the whole answer; startTime and endTime still filter.

Read the fields for the questions, not for the labels. This page used to say leads render as custom_question_1: yes without them. They do not: every answer already arrives keyed by the same field name the questions list returns. What the fields read genuinely adds is the form's name and URL, and the full roster of questions including the ones a given lead left blank.

The Lead Management scope is granted — verified against the live API on 5 August 2026, where this page previously said our app did not hold it and that both reads answered 403. The DIRECT_MESSAGE response shapes were verified with it. INSTANT_FORM was not, because the connected account has no Instant Form to read, so that branch is still unproven.

Why an ad is not delivering, in words rather than a status code. Every other surface in this API reports secondary_status — a string like AD_STATUS_AUDIT_DENY that says an ad was refused and nothing about why. This returns TikTok's policy reasons, and the frames of the video it points at, which is the only place in the API that says which part of a creative was the problem.

TikTok-only, and for one of its two endpoint families. TikTok publishes review and appeal endpoints under /smart_plus/ and none at all for manual ads. That is now the better-covered half rather than the worse one: the launch tries Smart+ first and keeps manual as the standby, so a campaign built here normally has reasons to read. A manual ad still reports a status with no reason attached. &family=manual answers with that status plus the reason it is thin, rather than refusing: “TikTok publishes nothing to build” is not the same as “nobody built it”, and a manual ad is appealed in Ads Manager.

The reasons and the violation frames are requested by default. TikTok defaults both to off, which returns a review status and nothing else — the same answer you already had. Pass includeRejectInfo=false to opt out.

&materialIds= reads the review of the individual creatives inside a Smart+ ad. Worth knowing about: one Smart+ ad can hold up to fifty creatives and TikTok reviews each one, so an ad can be delivering perfectly well on four of them while the fifth is refused and invisible in the ad-level answer.

Also in the dashboard. Ads tab → TikTok. This is the one of the six that is not a card, and the endpoint is the reason: both reads need an ad id and there is no list behind them, so a standalone panel would have to open by asking for an id from memory. Switch the campaign table to its ad level (TikTok labels it Video) and the shield on a row opens that ad's review — status, policy reasons, violation frames and the appeal — already knowing the id.

Read, hide, reply to and delete the comments on your TikTok ads. Before this the only comment control available was the ad group's comment_disabled switch — which turns comments off entirely, and costs the engagement TikTok's ranking rewards. Turning comments off to avoid moderating them was the only workable policy; it no longer has to be.

The vocabularies are validated here, and only one is still yours to supply. This block used to say the opposite — that searchField, commentType, commentStatus and the status-update operation were bare strings with no published enum, so they had to be passed through untouched. A live call disproved it: handed a bad value, TikTok's own error 40002 lists the legal set for each of them, and both values that paragraph offered as examples were the wrong ones. searchField takes ADGROUP_ID and nothing else, so it is filled in for you rather than demanded, and operation takes the STATE (HIDDEN / PUBLIC) rather than the verb HIDE. The survivor is commentType on the replies read, which TikTok has still not enumerated.

Also in the dashboard. Ads tab → TikTok, below the campaign table. A triage screen rather than a table, and it owns its own date window because this endpoint requires one: TikTok caps the span at 30 days and refuses anything older than 365. It lists one ad group at a time for the same reason the endpoint does — TikTok publishes no account-wide comment list — and hides, replies and deletes from the same rows.

&commentId=&commentType= reads the replies under one comment, which is a separate endpoint at TikTok rather than a filter. Replying and deleting both need five ids — the ad, the comment, the identity (two fields) and the organic post the comment sits on — because a comment on a Spark ad lives on the creator's post rather than on an ad object.

Words that keep a comment from appearing at all. Account level, which is the point: the comment switch is per ad group, so keeping one word out of your comments previously meant turning comments off on every ad group you run. A blocked word is set once and applies to everything the ad account serves, before a moderator ever sees it.

?check=word,word asks TikTok whether words are already blocked rather than filtering the list here — TikTok normalises words its own way, so it is the only thing that can answer correctly.

Renaming is one call rather than a delete plus an add, and deliberately so: doing it as two calls leaves a window in which neither word is blocked, and a comment that arrives in that window is published and stays published.

Same parameters and response shape as Meta's Ad stats & ROAS, with network=apple_search_ads. Apple additionally reports keyword and search-term levels in by_level, with revenue attribution drilled down to ad group and keyword.

The live campaign → ad group → keyword tree straight from Apple, flat like the Meta tree. Ad groups carry their default bid, keywords their own bid and matchType.

ads and creatives close the two levels that were write-only. Both could be created through POST …/ads/objects and neither could be read back anywhere, which on this network matters more than it sounds: a creative is minted once per product page per organisation and Apple publishes no update endpoint for one, so a lost id was a slot permanently occupied by something nobody could name. An ad carries servingStateReasons, which is usually the only place that says why an ACTIVE ad is spending nothing; a creative carries the productPageId it was built on and the state that decides whether an ad on it can ever deliver. Creatives are organisation-wide, so the list does not change with ?account=beyond which organisation is being read.

They sit beside entities rather than inside it because the entity PATCH handles campaigns, ad groups and keywords — an ad in that list would render a control that throws. Trim with ?include=ads,creatives, or ?include=none for the tree alone and the payload this endpoint returned before. null means "not asked for"; an empty array means Apple was asked and had none, and reads_error appears only when it could not be asked.

A big Apple account is now paged rather than cut off. Ad-group and keyword detail is loaded for a window of 50 campaigns — it used to stop at the first fifty with nothing behind them, so an advertiser with 51 campaigns could not see the 51st at all. The window moves: truncation reports detail_offset, detail_loaded, campaigns_before_window and next_detail_offset, and you pass that last one back as ?detailOffset=. The window size is deliberately unchanged, because this tree loads on every dashboard render and raising the default would have made every page slower for everyone to help the few with big accounts.

Two of the four narrowing parameters are applied by Apple rather than by us, so a 500-campaign organisation costs what a small one costs: ?campaignIds= becomes an id IN condition and reads exactly those, and ?servingStatus= becomes a servingStatus condition — worth knowing that this is Apple's delivery state and not the same question as ENABLED or PAUSED, since a campaign can be enabled and not serving.

Creates an Apple Search Ads campaign, PAUSED like everything else the API creates. Requires a read & write key. Find the app's adamId via targeting search type=app.

Apple has no objective field. A campaign is an app, a placement (supplySource) and a bidding strategy (biddingStrategy), and those two are the whole of what there is to choose. All four placements are creatable: search results (the default), the Search tab, the Today tab, and the “You Might Also Like” strip on other apps' product pages. Search results is the only placement with keywords, negative keywords or Search Match — there is no query to match anywhere else — and it is also the only one MAX_CONVERSIONS runs in.

Awareness, engagement, video views, leads and catalogue sales are not features we have yet to build on Apple: none of them exists anywhere in the Apple Search Ads API. The ad is assembled from your App Store listing, and the only actions it can measure are a tap and an install.

Send adGroup and the ad group, its targeting and both keyword lists are all created inside the new campaign in this one call — a campaign without an ad group can never serve, so that is what the in-app launcher always sends. Targeting keywords are created ACTIVE: the paused campaign and paused ad group are what gate delivery, and a keyword that arrives paused inside them is a silent no-op you would have to undo by hand. If the campaign and ad group are created and the keywords are not, the answer is still 201 — the campaign is complete and correct — carrying keywordsError plus the ids to retry against.

The ad is built here too, on the placements that owe one, and the sentence saying this endpoint builds no Apple creative at launch is no longer true. Apple assembles the ad from your App Store listing on APPSTORE_SEARCH_RESULTS and APPSTORE_PRODUCT_PAGES_BROWSE, so those two owe no ad object and come back with adId and creativeId of null — which is correct rather than an omission. The other two do owe one: the Search tab gets a default product page ad, and the Today tab gets a Custom Product Page ad, because a custom page is the Today tab's tap destination and Apple publishes no default for it. Naming ad.productPageId promotes that page on any of the four, which makes it a choice rather than a placement rule. Every campaign this endpoint built on those two placements before this landed was structurally unable to serve, under a 201 telling the owner to switch it on.

Two new refusals, both before anything exists or with the campaign rolled back. A APPSTORE_TODAY_TAB launch carrying an adGroup and no ad.productPageId is a 400 VALIDATION_ERROR raised before the campaign is created, naming the lookup that lists your pages. It used to answer 201 and leave behind a campaign that could never serve, squatting the name you wanted. And a failed AD create now rolls the campaign back and answers 502 when Apple refused, or 400 when our own check did — the split matters, because calling our refusal an upstream error would send you to look at Apple. The rollback cannot undo the creative: Apple publishes no creative delete, which is harmless and slightly useful, since the creative is org-scoped and the retry finds it instead of colliding with it. A body with no adGroup at all is untouched; that is the documented two-step contract and it already says the campaign cannot serve yet.

Also in the dashboard. Ads tab → Apple → Launch. ad.productPageId stopped being API-only this phase: the launcher REQUIRES it on the Today tab and OFFERS it on the other three placements, picked from the product_page lookup rather than typed, since the ids are UUIDs and Apple publishes no search over them.

Creates an ad group inside an existing campaign, PAUSED. automated: true creates the automated ad group a MAX_CONVERSIONS campaign requires (Apple owns keywords and bids there, so defaultBidCents is ignored). Requires a read & write key.

Geo ids for adminAreas / localities come from targeting search type=geo, and geo targeting only works on single-country campaigns. daypartHours are hours-of-week, 0-167 counted from Sunday 00:00.

Updates one entity: campaign status/budget, ad group status/default bid, or keyword status/bid. Requires a read & write key.

Bulk keyword management for an ad group, up to 1,000 keywords per call. Omit bidCents on a keyword to inherit the ad group's default bid. The live keyword list (with bids and statuses) rides the campaign tree. Writes require a read & write key.

Keywords are created PAUSED, like every other create on this API, so adding a hundred keywords never starts a hundred auctions on its own. Each returned keyword carries the status it actually has; PATCH them ACTIVE when the ad group is ready to bid on them.

text and matchType are immutable on Apple's side: to change them, delete the keyword and recreate it. PATCH and DELETE return { ok }.

GET lists, POST adds, PATCH pauses or reactivates, DELETE removes. adGroupId picks the scope: omit it for campaign-wide (blocks the term in every ad group), pass it to target one ad group. Writes require a read & write key. Up to 1,000 keywords per call. status is the only field Apple allows updating on an existing negative keyword (text/matchType = delete + recreate); PATCH returns { ok }.

Apple's suggested bid per targeting keyword, derived from 30-day keyword reports. suggestedBidCents is null in MAX_CONVERSIONS campaigns (Apple bids automatically there). Works on read-only Apple connections.

This is a bid for a keyword you already have, not a new keyword. Apple publishes no keyword-suggestion endpoint of any kind, so keyword discovery on Apple is its search-term report: GET …/ads/lookups?network=apple_search_ads&type=keyword_idea&campaignId=… returns the phrases people actually typed, with meta.source saying whether Search Match found one and nothing targets it yet (AUTO — a keyword to add, or a negative to block) or one of your own keywords already bought it (TARGETED). Apple only reports terms with at least ten impressions.

Also in the dashboard. Ads tab → Apple, below the campaign table, as Keyword ideas — one panel carrying both halves of this endpoint. Apple's half is an inventory, so there is nothing to type: pick a campaign (and an ad group, to reach the narrower report) and the answer is the campaign. Google's half of the same panel is the seeded search below.

Apple's whole creative surface is one format. Nothing is uploaded — Apple renders the ad from an App Store product page — but it is still two objects in a fixed order: an organisation-scoped creative at /creatives, then an ad under a campaign and an ad group pointing at it.

The creative is found before it is created, and that is the trap this closes. Apple allows one creative per product page per organisation, so the second campaign promoting the same page gets a duplicate refusal that does not carry the id it needs. This looks first and reuses, reporting creative_reused so a caller is never surprised by an id it did not create. It is also what makes a failed ad create cheap to retry: Apple publishes no creative update and no creative delete, so an object that landed is found rather than orphaned, and a refusal after the creative exists names its id either way.

creative_state comes back on every answer because it is the failure that costs nothing and looks like success: an ad on a creative that has not cleared review is accepted and then never delivers. Send creativeId instead of creative to point at one that already exists — the creative lookup (…/ads/lookups?network=apple_search_ads&type=creative) lists them, and its meta.state is what separates a usable creative from one that is accepted and silent.

Also in the dashboard. Ads tab → Apple, below the campaign table, in the creative builder it shares with Snapchat's four formats. A builder rather than a table, because this endpoint's POST is the whole capability — there is no creative list on it. It never opens by itself and it warns before it is used, for the reason above: neither network publishes a delete, so anything it makes is permanent. The campaign and ad group are picked from the tree rather than typed when the tree is there.

How much of the search results you got, and who was ahead of you. The metrics are lowImpressionShare, highImpressionShare, rank (ONE through GREATER_THAN_FIVE) and searchPopularity, dimensioned by app, country and search term. It is the only Apple report that is not about your own campaigns, which is why it takes an app and a country rather than a campaign id.

Apple-only and asynchronous, which is why it is not a dimension on Breakdowns: every other report this product pulls is a synchronous call that answers with rows, and this one answers with an id and a state (QUEUED → PENDING → COMPLETED | FAILED). Apple allows ten of these per organisation per 24 hours.

Known Apple-side fault, and it is theirs rather than ours. Since 2026-03-16 Apple's gateway has answered these GETs with a 403 HTML page for accounts whose token and role work everywhere else (their own developer forum thread 820073, unanswered), so a report can be queued and never read. This endpoint says so in plain words instead of surfacing a bare 403 and sending somebody off to re-check their role, their org id and their token, none of which is the problem. The POST is unaffected.

Also in the dashboard. Ads tab → Apple, below the campaign table. On screen although Apple is refusing half of it, which is the deliberate part rather than an oversight: the queue half works, and where Apple answers its 403 the panel prints Apple's own refusal as a statement rather than showing a blank card or a red error. An owner who can read “Apple is refusing this report” stops debugging their own account; one looking at an empty box does not.

Google's impression share is four metrics on an ordinary search query — ask Breakdowns — and Meta, TikTok and Snapchat publish none.

On-demand refresh of Apple Search Ads reporting.

Same parameters and response shape as Meta's Ad stats & ROAS, with network=google. Google reports campaign, ad group, keyword, and ad levels in by_level.

The live campaign → ad group → ad/keyword tree straight from Google, nested (unlike the flat Meta and Apple lists): each campaign carries its adGroups, each ad group its ads and keywords. Campaigns carry advertisingChannelType, biddingStrategyType, dailyBudgetCents, and budgetResourceName; ad groups their default cpcBidCents; keywords their own bid and matchType.

dailyBudgetCents on a Google campaign is not necessarily that campaign's own number, which is the one thing about this tree that has no equivalent on the other four networks. A campaign_budget is its own resource and an advertiser can point any number of campaigns at one, so two fields say whether the number is shared. budgetCampaignCount is Google's reference_count: 1 is this campaign alone and anything above 1 is how many campaigns spend from that budget. budgetExplicitlyShared is the budget's type, which Google documents as flippable false to true and never back, so it can be true while exactly one campaign uses it — which is why it is not the answer on its own. Both are null when Google returned no budget row, and null is "unknown" rather than "private". Everything this product creates sends explicitly_shared: false; an account connected from Google Ads may hold shared budgets we did not build. See the entity endpoint for what happens when you try to edit one.

The tree also carries what used to be write-only. assetGroups is Performance Max's replacement for the ad group — a PMax campaign has no ad groups, ads or keywords at all, so before this it came back as a campaign with no contents, indistinguishable from a launch that half failed. Each asset group carries its assets (with the text or image label, not just an id), its signals (search themes and audiences), Google's adStrength grade, and — when you pass from and to — its metrics. assets and criteria at campaign and ad-group level are the sitelinks, callouts, locations, languages, schedules and exclusions that could be written and never read. advertisingChannelType is what tells an empty PMax campaign (that is how PMax is shaped) from an empty Search campaign (that is a problem).

Everything is patched via the composite id Google composes, and it is what these responses return: adGroupId~childId for an ad or keyword, parentId~criterionId for a criterion, and parentId~assetId~FIELD_TYPE for an asset link — the field type is part of a link's identity, which is what lets one image serve as both MARKETING_IMAGE and SQUARE_MARKETING_IMAGE. Pass ?customerId= to pin one of the connection's ad accounts; it defaults to the first.

Creates budget → campaign (PAUSED) → geo/language criteria → ad group → responsive search ad → keywords in one atomic operation: it either all succeeds or nothing is created. Requires a read & write key. Append &validate=1 for a full server-side dry run that creates nothing and returns { validated: true }.

Geo ids come from targeting search type=geo, language ids from type=language (1000 = English; omit languageIds to target all languages).

Google has no objective field. The campaign type is what Google has instead, so &type= is where an objective goes — and every one of the six types its API can create is creatable here, each as its own atomic mutate with its own body. Omitting type (or sending anything unrecognised) builds the Search stack the table below describes, which is what every caller who has never sent the parameter has always got.

Updates one entity at any level. This is the endpoint that starts real spend (flipping PAUSED → ENABLED, Google's word for active), so it requires a read & write key.

Campaign and ad group ids are numeric. Ad and keyword ids are the composite adGroupId~childId form, and you build it — the campaign tree does not hand it to you. Its ads and keywords carry the plain id / criterionId, nested inside the ad group they belong to, so join the ad group's id to the child's with a ~. An ad group holding ad 50000000001 under id 30000000001 is patched as 30000000001~50000000001. The plain id on its own is rejected: Google addresses an ad or a criterion by its parent, so half the id is not an id.

A shared campaign budget answers 409 CONFLICT, and nothing is sent to Google. A campaign_budget is its own resource and several campaigns can spend from one, so editing dailyBudgetCents through a campaign that shares its budget would rewrite the number every one of them spends against, with no symptom anywhere. The refusal names how many campaigns are on that budget and what to do instead: change the shared budget in Google Ads, or give this campaign a budget of its own first. It also refuses when Google does not report the sharing state at all, because "we could not read it" is not "it is private" and a write there is a coin flip on somebody's money. This used to answer 502 UPSTREAM_ERROR, which is the code an agent retries and this is the one refusal retrying will never get past — 409 CONFLICT says the refusal is ours and the account's state is what has to change. Read budgetCampaignCount off the campaign tree to know before you write. Ad group and keyword bids are unaffected: they are not budgets.

Also in the dashboard. Ads tab → Google. The daily-budget cell on a campaign whose budget is shared renders READ ONLY, showing that same sentence verbatim rather than a disabled box with no explanation. So the claim that the dashboard lets an owner edit any campaign's daily budget is false for Google, in exactly the same case and for exactly the same reason as the 409 here.

Campaign-level negative keywords: the term is blocked in every ad group of the campaign. GET lists them, POST adds, DELETE removes by composite campaignId~criterionId ids. There is no PATCH for Google (add and remove only; Apple keeps PATCH). Writes require a read & write key.

Keyword research from Google's Keyword Planner: search volume, competition, and the top-of-page bid range for keywords related to your seeds. Seed it with q (comma-separated keywords), pageUrl (a landing page to mine), or both. The bid range is what feeding these into keywords[].cpcBidCents should orient on.

Google throttles keyword planning to about 1 request per second per account, so space out repeated calls.

Also in the dashboard. Ads tab → Google, below the campaign table, in the same Keyword ideas panel that carries Apple's bid recommendations. Google's half is a seeded search rather than an inventory, so the panel shows nothing until a seed is typed — which is a question waiting to be asked, not an empty state, and it says so. It needs no campaign, so it still works on a page whose campaign tree failed to load.

The Google flavor of the shared targeting-search endpoint. type=geo returns geo target constants (countries, states, cities) whose id goes into geoTargetIds; type=language returns language constants whose id goes into languageIds.

Google's own optimizer suggestions: budget raises, bidding upgrades, new keywords, responsive-search-ad improvements, 70+ types in all. This is the Google counterpart to Meta's automated rules (Google has no rules API): instead of writing your own automation, you review what Google's optimizer already computed and apply or dismiss it.

GET lists the account's open recommendations. POST with action: "apply" applies one with Google's default parameters; action: "dismiss" dismisses it. Writes require a read & write key.

Google's "pixel" is a ConversionAction fed by server-side click uploads: our tracking snippet already captures the gclid on the advertiser's site, and Affiliateo reports each sale to Google automatically, live at sale time plus a nightly sweep, deduped by order id. Google refuses uploads for clicks younger than 6 hours; the nightly sweep absorbs those.

Two kinds of conversion, and the difference decides everything. type: "UPLOAD_CLICKS" (the default) is the one described above: we upload each sale from our server, keyed to the gclid our snippet captured. type: "WEBPAGE" is fed by a gtag on your own site instead, which is what you want for a signup, a lead or a booking — events that have no sale to upload. Pass { name?, type?, category? } to POST to choose; an empty body still creates the historical "Affiliateo purchases" action, so nothing built against this endpoint changes.

A WEBPAGE response carries action_required: "install_tag" and an install block with the finished code — a baseTag for every page and an eventSnippet for the moment the conversion happens. They are separate on purpose: put the event on every page and every visit counts as a conversion. Nothing is tracked until that tag is live, which is why the flag exists rather than only a sentence.

GET returns conversions, every conversion action with its own id, type, enabled and tag values. A connection can hold several, so there is no single "is tracking on". Read it before acting: "never set up" and "deliberately switched off" need different fixes and POSTing again only solves the first. POST is idempotent — the same name and type adopts the existing action rather than making a second one — and resolves cross-account conversion tracking through a manager account automatically. New actions warm up for about 6 hours before accepting uploads. Requires a read & write key.

PATCH { "conversionActionId": "…", "enabled": false } switches one conversion, by flipping its status to HIDDEN on Google. That is the only lever that works for a tag-reported conversion: our own flags gate our uploader, and a gtag on your site is not something we can reach. HIDDEN rather than removed, because removal is permanent and takes the conversion history Smart Bidding trained on with it.

Counted and chased are two different things. Beside enabled there is primaryForGoal: enabled decides whether Google records the conversion, primaryForGoal decides whether Google bids toward it. Send either on its own — only what you send is written, so changing one never overwrites the other.

Primary is account-wide, and that is the part worth pausing on. It governs every campaign on the account, not just this conversion. Create a second primary and your existing sales campaigns start optimising for it too. So create the ones you want to watch with { "primaryForGoal": false }, and keep one primary for the thing you actually want more of. The create response returns bidding_toward and warns when an account ends up chasing several at once. Google has exactly these two states; there is no third.

PATCH { "enabled": … } with no id keeps its old meaning: the connection-wide switch for the server-side sales uploader. Off stops new uploads (sales already reported stay reported); on turns them back on and the nightly sweep re-sends the last 7 days, so a pause loses nothing. Turning on mirrors to Google first and answers 502 if Google refuses, so the switch never reads as on while nothing is uploading. Google only: a Meta pixel belongs to the ad account and other tools use it, and TikTok pixels are created and retired in the dashboard.

Refunds are retracted. When a sale reverses, we send Google a conversion adjustment of type RETRACTION keyed on the same order id, so it stops counting that sale and Smart Bidding stops training on it. Google refuses to adjust a conversion less than about 24 hours old, so a same-day refund is picked up by the nightly sweep rather than immediately — the sweep re-reads reversed sales every night for exactly this reason.

This is Google only, and that is not an oversight on our side. Meta's Conversions API and TikTok's Events API are append-only event streams: there is no call that withdraws a purchase they have already counted, so there is nothing for us to send. On those two networks a refund moves our own verified revenue and ROAS, while the network's self-reported conversions and claimed ROAS keep the sale. That gap is one of the reasons every ad row shows both numbers side by side.

Google's own grade for every ad and every Performance Max asset group on the account, plus the action items it attaches to a low one. This is the answer where a preview is impossible: Google refuses to preview responsive search and responsive display ads, which is most of what an advertiser runs, so on a Search campaign this is the only read that says anything about creative quality. See Ad previews for the two shapes Google will render.

PENDING and NO_ADS are in Google's enum and are not grades — PENDING means Google has not finished assessing and NO_ADS means the ad group is empty — so they come back as themselves. Rendering either as "Poor" would be a false statement about somebody's campaign.

Both lists are read, and that matters rather than being thorough for its own sake: a Performance Max campaign has no ad rows at all, so reading only the first list returns an empty result that a reader takes for "no ads". Google only — no other network publishes an equivalent grade.

Copy a campaign, change it, split the traffic, and either keep the change or throw it away. Google is the only one of the five networks with an experiment API — Meta's split tests need an App Review scope this app has not been granted, TikTok and Snapchat publish nothing comparable, and Apple has none at all.

Nothing spends at create. The experiment and both its arms are built in SETUP, and the split starts only at { action: "schedule" } — the same nothing-until-you-flip-it contract every launch path here keeps. Two actions cannot be undone: promote copies the treatment onto the original campaign and stops the treatment serving, and graduate turns the trial campaign into a standalone one (which is why it requires a budget: a trial campaign shares the original's and a standalone one cannot). Every response carries permanent: true on exactly those, so a client can gate them without hard-coding a list.

Read asyncErrors. Scheduling and promoting return long-running operations that report acceptance, not completion, and Google documents the real errors behind a separate list. Both readers run on the detailGET, so a failed promotion cannot look like a successful one.

DELETE is allowed here and refused for campaigns, ad groups and ads, for a reason rather than by inconsistency: an experiment and a draft are copies. Removing one leaves the original campaign serving, loses no stats, and takes no bidding history with it.

Also in the dashboard. Ads tab → Google, below the campaign table. A state machine rather than a table, because that is what this endpoint is: the actions offered on a row are the ones its current status allows, and the two permanent ones are confirmed before they run. asyncErrors is not a column — it exists only on the single-item read — so it is fetched when a row is opened, and the list never claims health it has not checked. It needs nothing from the campaign tree; it fetches the campaigns it needs itself.

Two answers to one question — "which campaigns belong together" — and they are genuinely different objects. A label is many-to-many and goes on campaigns, ad groups and ads (Google keeps three separate label services, one per level). A campaign group is a folder a campaign is in at most one of.

Removing a label is safe in a way removing a campaign is not: a label carries no history, so a delete detaches it everywhere and nothing stops serving. Google only — Meta has no label object, TikTok and Snapchat publish none, and Apple's nearest equivalent is the campaign name.

Who changed what, recently. Every row carries clientType, which is how a change made through this product (GOOGLE_ADS_API) is told apart from one made in Ads Manager, in Google Ads Editor, by a script, or by Google's own recommendation automation.

Thirty days, and it is not an audit log. Google keeps no more, and answers a request for day 31 with an empty list rather than an error — which reads as "nobody touched it". So this endpoint refuses an out-of-range window and names the earliest day that is reachable, rather than passing a silence through as an answer.

On-demand refresh of Google Ads reporting. Synced levels: campaign, ad group, keyword, and ad.

Requires a read & write key. Upload the Snap first with POST …/ads/media?network=snapchat and pass the id back as media.snapchatMediaId.

The field is goal, not objective — and an unrecognised value is read as traffic rather than refused, which is deliberate (callers who predate the goal list never sent one) and is exactly why it is worth getting right: sending Meta's word here launches a traffic campaign and answers 201.

Snapchat's own objective enum has only five values because objective_v2 steers nothing — it is the ad squad's optimisation goal that decides what Snapchat actually buys — so awareness, engagement and video views all sit under one shared AWARENESS_AND_ENGAGEMENT objective with different optimisations. The three are kept apart anyway, because objective_v2 decides which optimisation goals Ads Manager offers the squad afterwards, so a campaign the owner asked for has to BE one when they open it.

The goal also picks the CREATIVE, which is what decides the shape of the rest of the body. The five web goals take destinationUrl; leads takes leadFormId instead; app_promotion takes an app object instead. Those two creatives have no URL field at all, so neither can carry our tracking tags and neither reports ROAS — Snapchat has no url_tags / final_url_suffix to append them to. Spend and Snapchat's own reported conversions still arrive normally, and the 1% platform fee is unaffected: it meters campaign rows and reads no utm tag.

A Public Profile is a precondition, and its refusal is a 403 FORBIDDEN rather than a 502. Every Snapchat creative requires profile_properties.profile_id, including a plain link ad, so a connection with no Public Profile cannot build one. That used to answer 502 UPSTREAM_ERROR, which is a lie about who refused: Snapchat was never asked. The message is unchanged and only the code moved, so anything branching on the 502 needs updating. Send profileId (or profile_id) in the body to supply one yourself — it is used only when the connection has none of its own, and the connection's profile always wins.

The two age bounds have different ceilings, and neither is clamped any more. ageMin is 13 to 35 and ageMax is 13 to 55, which is Snapchat's own asymmetry rather than ours. Both used to run through a min/max against one 13-55 pair, so an owner asking for 18 to 65 was quietly sold 18 to 55 with nothing said anywhere. All three refusals are 400 VALIDATION_ERROR now: a bound outside its range, and an ageMax below ageMin, which targets nobody. Omitting ageMax means NO upper limit rather than 55, and omitting ageMin takes Snapchat's 13.

Also in the dashboard. Ads tab → Snapchat → Launch. ageMin, ageMax, gender and endDate stopped being API-only this phase: the launcher collects all four, on the network best known for a young audience, where it previously could not narrow by age at all.

The four Snapchat formats this product could not build, taken as a format plus the inputs you have rather than as a field bag. Field writes could always POST these — every property object is a writable JSON field — and that is exactly why almost nobody could: using it meant already knowing that a Story ad is four objects and a collection is three, that a collection must send call_to_action null and shows its interaction zone's headline instead, and that fallback_type carries an underscore.

DEEP_LINK is the one an app advertiser actually wants: an app-install ad sends everybody to the store including the people who already have the app, while a deep link opens the app at the thing advertised and falls back to the store or a web page only for people who do not. REMINDER fixes the call to action at REMIND_ME. STORY builds the preview tile shown in the Stories feed (its own 3:5 image and a 55-character headline, not the creative's 34) and then the composite holding 1–20 slides in an order that is frozen after create — there is no reorder, insert or remove, so a repeated slide is refused rather than deduplicated, because deduplicating would silently change the running order and accepting would show the same slide twice, unfixably. COLLECTION creates every tile (a creative element each), then the interaction zone that orders them and carries the button, then the creative.

The collection path is not atomic and nothing here pretends otherwise. Snapchat has no transaction across these objects and documents no delete for elements or zones, so a part-way failure leaves what landed. GET the same path with ?resource=interaction_zones to see what that is: the zones already on the account, each with the ids of its tiles. Reusing one is not done on this endpoint. The collection branch here takes no interactionZoneId — it always builds a fresh zone from the tiles you send — so posting again to "retry" makes a second set of undeletable tiles beside the first. A zone is a reusable object, and the way to point a new creative at one is a field write: POST …/ads/objects at the Snapchat creative level, whose collection_properties carries interaction_zone_id. That is what makes a second collection ad cheap.

Every response carries ad_type beside creative_id, because this network's sharpest edge is that it spells every format twice, in two different enums: a WEB_VIEW creative goes on a REMOTE_WEBPAGE ad and a COMPOSITE goes on a STORY ad, and Snapchat refuses a mismatched pair at ad create, after the creative already exists.