Pricing over the REST API and MCP

Everything the Pricing card does has a REST counterpart. This page collects how those calls behave — what they check before storing, what they leave alone, and how an AI assistant reaches them. The console behaviour they mirror is on Configure pricing.

Who this is for

• Developers and integrators who price campaigns, banners, sites or placements from code.
• Anyone connecting an AI assistant over MCP.

A call needs the same permissions as the console card it stands in for, including each pricing type’s own permission.

REST API behaviour

Note — setting prices over the REST API. POST /rest-api/sites/{siteId}/pricing.do and POST /rest-api/placements/{placementId}/pricing.do take the fixed price plus minMarginType (NONE, ABSOLUTE, PERCENT) and minMarginValue; the matching GET returns them. The two margin fields belong to the fixed-price model only and are rejected, not ignored, alongside REVENUE_SHARE. The GET needs Manage Site Payment Model at enabled or read-only level and adds the two margin fields only for a caller who also holds Manage Minimum Margin at enabled or read-only level; the POST needs Manage Site Payment Model enabled, and the margin fields additionally need Manage Minimum Margin enabled plus update access to the site. Omit either field to keep what is stored — the range check runs against the merged pair. Two behaviours to plan around: a site FIXED_PRICE call leaves the placements’ pricing rows — and their per-placement margin requirements — alone, and reuses the site’s own row, so the site-level requirement survives too; and a placement pricing row created by the API starts at None, which means inherit the site’s requirement, not no requirement.

Note — a site’s per-advertiser shares over the API. An advertiserPricing entry on a site may name a campaignId; it must be a live campaign of that entry’s advertiser — any other would never match a request, so it is refused with a 400 — and GET /rest-api/sites/{siteId}/pricing.do shows the campaignId of each such entry.

Note — placement pricing over the API. GET /rest-api/placements/{placementId}/pricing.do lists every country price twice: countryPricing in its original {"US": 2.25} form, which does not say which action a CPA price is for, and countryPricingDetails as {"country", "price", "actionId", "actionName"} rows — a row without actionId prices every action. A CPA placement also returns useGlobalActionPricing and globalActionPricing (the per-action prices for every country). The checkbox is POST /rest-api/placements/{placementId}/pricing/use-global-action-pricing.do?useGlobalActionPricing=false, and Upload CSV is POST /rest-api/placements/{placementId}/pricing/batch.do with the file in countryPrices or its text in countryPricesCsv; the answer lists the prices it stored in applied and the rows it could not apply, with the reason, in rejected (plus the legacy csvErrors / csvWarnings). The campaign and banner CSV batch endpoints (…/campaign/{id}/pricing/batch.do, …/banner/{id}/pricing/batch.do) accept the same countryPrices / countryPricesCsv choice and answer the same way, so a client that cannot upload a file — such as an AI assistant — can price any of the three entity types from plain text. POST …/pricing.do on a site or placement replaces the country prices or per-advertiser shares only when you send that list — a call that changes only the base price or the revenue share keeps them. See the pricing corner cases in the API reference.

Note — every pricing write checks before it stores. A REST pricing call validates its input first: a price outside 0–1,000,000, a malformed countryPricing entry, an unknown country or advertiser, or a missing required price is a 400 that names the field, and a refused call changes nothing. A write changes only what it names — a field you leave out keeps its stored value — and a field that does not apply to the chosen payment model or pricing type (for example actionName on a campaign that is not CPA) is not applied and comes back in ignoredFields with the reason.

Over MCP

Note — over MCP. An AI assistant has no dedicated pricing tool: it reads pricing through campaign_overview and placement_overview, and finds and calls the operations above through api_search, api_describe and api_write. whoami reports may.pricing (Manage Pricing), may.sitePricing and may.viewSitePricing (Manage Site Payment Model). See Connect an AI assistant (MCP).

Corner cases and gotchas

Two console corner cases apply to API calls unchanged: a region or country group is not expanded into countries, and sending a different pricingType deletes the existing country and action prices. Both are described under Configure pricing — Corner cases and gotchas.

Related

• Configure pricing
• Pricing precedence: which price is charged and paid
• Set a bid floor and a minimum margin
• Campaigns
• Placements