Skip to main content

Bulk Set Product Goals

POST 

/api/advertising/goals/bulk

Sets one goal on up to 1000 products at once. Each product is processed on its own with the same rules as setting a single product's goal, so a product blocked by a guardrail does not stop the others; the response reports each product's outcome.

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:

  • product_ids (required, array of 1 to 1000 distinct existing product IDs).
  • goal (required): one of profit, growth, launch, liquidate, defend, hold.
  • ad_account_id (optional, integer): scope to one ad account; omit for all accounts.
  • reason (optional, string, max 1000). 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.

Response data has one row per product: product_id, ok, goal_id (the goal now in force, null when blocked) and error (the block reason). meta.updated and meta.blocked count the outcomes.

Request​

Responses​

OK

Response Headers
    Content-Type