Skip to main content

Set Product Goal

PUT 

/api/advertising/goals/products/:product

Sets the advertising goal for one product, for a single ad account (ad_account_id) or for all accounts (omit it). Setting a goal closes the product's currently open goal for that scope (it stays in the history) and opens a new one with the reason recorded; if the open goal already has the same goal and params, it is returned unchanged.

Required scope: advertising:write

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

Requires the advertising.manage permission; the tenant must have the advertising-manager feature enabled.

Body fields:

  • goal (required): one of profit, growth, launch, liquidate, defend, hold.
  • ad_account_id (optional, integer): ad account to scope the goal to; omit or null for all accounts. Must exist.
  • reason (optional, string, max 1000): why the goal changed; stored as "Switched to <Goal> from <Previous>: <reason>". params (optional object; only these keys are accepted, any other key is rejected with "Unknown goal parameter."):
  • target_poas (number, 1.0 to 20): profit-on-ad-spend target; 1.0 is break-even and is the minimum.
  • margin_share (number, 0 to 0.95): share of unit contribution the bid may spend (Growth/Launch).
  • contribution_floor_pct (number, -100 to 100): how far below break-even a click value may go, in percent (Growth/Launch).
  • liquidation_floor (number, -100000 to 100000): minimum contribution per unit when liquidating; may be negative.
  • bid_ceiling (number > 0): maximum bid (Defend).
  • launch_end_date (date, Y-m-d): when a Launch goal ends and the product returns to Profit.
  • spend_cap_per_day (number > 0): daily spend cap for the product.
  • goal_weight (number > 0, max 1): share of order value a click is worth for value-driven goals.
  • growth_premium (number, 0 to 2): extra bid premium applied for Growth. Null values are dropped.

Guardrails: Growth and Launch are refused with a 422 (under errors.goal) while a low-cover or stockout-spend signal is open for the product, or when the supply check says the stock cannot support the goal. The effective goal resolution is: account goal, then all-accounts goal, then Profit.

Returns the new goal with status 200.

Request​

Responses​

OK

Response Headers
    Content-Type