Sign in
OpenAPI 3.1.02026-08-175661822.2 MB

3c7cf84cec44

Ad Campaigns

Update an ad set

Ad-set-level writes. Use this for ABO budget updates, ad-set-scoped pause/resume, bid-strategy edits, Meta value-rule-set attach/detach, and Meta-only post-launch delivery settings via platformSpecificData. At least one updatable field is required.

Value rule sets (Meta only, see /v1/ads/value-rule-sets):

  • ATTACH or REPLACE: send valueRuleSetId. Attachment is driven by the id's presence, so valueRulesApplied: true is optional. Sending a different id replaces the previous association; there is no separate replace call.
  • DETACH: send valueRulesApplied: false and OMIT valueRuleSetId.
  • Sending valueRulesApplied: false TOGETHER with valueRuleSetId returns 400 mutually_exclusive_fields. This is deliberate: Meta attaches the rule set whenever value_rule_set_id is present, even with value_rules_applied false, so echoing stored state while asking to detach would silently keep the bid adjustments live.
  • Eligibility: only ad sets on LOWEST_COST_WITHOUT_CAP or COST_CAP. Meta rejects the rest server-side.
  • Read back with GET /v1/ads/ad-sets/{adSetId}?fields=value_rule_set_id. Meta does not document value_rules_applied as a readable ad-set field, so the boolean cannot be read back.

Bid strategy compatibility (per Meta's spec):

  • LOWEST_COST_WITHOUT_CAP: no bidAmount, no roasAverageFloor.
  • LOWEST_COST_WITH_BID_CAP / COST_CAP: bidAmount REQUIRED (whole currency units).
  • LOWEST_COST_WITH_MIN_ROAS: roasAverageFloor REQUIRED (decimal multiplier, e.g. 2.0 = 2.0x ROAS).
  • Meta only: send bidAmount WITHOUT bidStrategy to change the cap amount on an ad set under a COST_CAP / LOWEST_COST_WITH_BID_CAP parent campaign, leaving the strategy itself (inherited from the campaign) untouched. roasAverageFloor without bidStrategy is rejected (it has no meaning outside LOWEST_COST_WITH_MIN_ROAS).

Delivery settings are validated by Meta against the campaign objective; incompatible combinations (e.g. a billingEvent the optimization goal doesn't allow) surface as 400s from Meta.

When updating budget on an ABO campaign: if the parent campaign is CBO, the response is 409 with code BUDGET_LEVEL_MISMATCH — route to PUT /v1/ads/campaigns/{campaignId} instead.

put/v1/ads/ad-sets/{adSetId}

Path parameters

adSetIdstring required

Platform ad set ID

Request body

platform'facebook' | 'instagram' | 'tiktok' | 'linkedin' | 'pinterest' | 'google' | 'twitter' | 'openai' required
status'active' | 'paused'

Writes the ad set's own on/off switch (Meta: configured_status) on Meta and LinkedIn, whatever delivery status its ads report. Omit if not toggling delivery state.

namestring

Rename the ad set (Meta only; other platforms return 501). At least one of budget/status/bidStrategy/name is required.

bidStrategy'LOWEST_COST_WITHOUT_CAP' | 'LOWEST_COST_WITH_BID_CAP' | 'COST_CAP' | 'LOWEST_COST_WITH_MIN_ROAS'

Meta bid strategy. Same enum applies at campaign and ad-set level; ad-set value (when set) overrides campaign-level. Cross-field rules:

  • LOWEST_COST_WITHOUT_CAP (default): auto-bid, forbids bidAmount and roasAverageFloor.
  • LOWEST_COST_WITH_BID_CAP / COST_CAP: require bidAmount (whole currency units).
  • LOWEST_COST_WITH_MIN_ROAS: requires roasAverageFloor (decimal multiplier, 2.0 = 2.0x). Source: facebook-business-sdk-codegen api_specs/specs/enum_types.json (AdSet_bid_strategy, Campaign_bid_strategy).
bidAmountnumber

Bid cap in WHOLE currency units (USD: 5 = $5.00; JPY: 100 = ¥100). Required when bidStrategy is LOWEST_COST_WITH_BID_CAP or COST_CAP. Internally converted to Meta's smallest-denomination integer, or (on OpenAI) to micros (× 1,000,000). Meta only: may be sent alone, WITHOUT bidStrategy, to update the cap amount on an ad set whose parent campaign is COST_CAP or LOWEST_COST_WITH_BID_CAP (the strategy is inherited from the campaign and is left untouched).

roasAverageFloornumber

Minimum ROAS as a decimal multiplier (2.0 = 2.0x). Required when bidStrategy is LOWEST_COST_WITH_MIN_ROAS. Sent to Meta as bid_constraints.roas_average_floor × 10000. Not supported on OpenAI (422).

valueRuleSetIdstring

Meta only (other platforms return 501). Value rule set to attach to this ad set, from /v1/ads/value-rule-sets. Sending a different id replaces the current association. To DETACH, send valueRulesApplied: false and omit this field.

valueRulesAppliedboolean

Meta only (other platforms return 501). false DETACHES the ad set's value rule set and must be sent WITHOUT valueRuleSetId; the combination returns 400. true is optional when attaching, since attachment is driven by valueRuleSetId, and requires it to be present.

Response

Ad set updated

budgetLevel'adset'
status'active' | 'paused'

The status written to the ad set. Absent when nothing was written (see statusMessage).

statusUpdatedinteger

Number of ads whose own stored status changed alongside the ad set switch

statusSkippedinteger

Number of ads whose own status was left as it was

statusSkippedReasonsstring[]

Why each group of ads was skipped

statusMessagestring

Present only where the platform has no ad-set switch and no child ad was actionable; status is then absent because nothing was written

bidStrategy'LOWEST_COST_WITHOUT_CAP' | 'LOWEST_COST_WITH_BID_CAP' | 'COST_CAP' | 'LOWEST_COST_WITH_MIN_ROAS'

Meta bid strategy. Same enum applies at campaign and ad-set level; ad-set value (when set) overrides campaign-level. Cross-field rules:

  • LOWEST_COST_WITHOUT_CAP (default): auto-bid, forbids bidAmount and roasAverageFloor.
  • LOWEST_COST_WITH_BID_CAP / COST_CAP: require bidAmount (whole currency units).
  • LOWEST_COST_WITH_MIN_ROAS: requires roasAverageFloor (decimal multiplier, 2.0 = 2.0x). Source: facebook-business-sdk-codegen api_specs/specs/enum_types.json (AdSet_bid_strategy, Campaign_bid_strategy).
bidAmountnumber nullable
roasAverageFloornumber nullable
platformSpecificDataobject