Upsert campaign

PUT 
/ad-publishing/facebook/campaigns

Create or update a Facebook campaign

Request

Version stringrequired

API Version

Available optionsv3

application/json

application/json

Body

Bodyrequired

idstring

Campaign identifier

locationIdstringrequired

Location identifier

namestring

Campaign name

objectivestring
Campaign objective
Available optionsOUTCOME_LEADSOUTCOME_TRAFFICOUTCOME_ENGAGEMENTOUTCOME_SALES
specialAdCategoriesstring[]
Special ad categories
Available optionsEMPLOYMENTCREDITFINANCIAL_PRODUCTS_SERVICESHOUSINGISSUES_ELECTIONS_POLITICSONLINE_GAMBLING_AND_GAMINGNONE
isCampaignBudgetboolean

Advantage campaign budget. When true the campaign carries budget and bidStrategy, and ad sets carry no budget of their own.

budgetobject

Campaign-level budget (Advantage campaign budget). Requires isCampaignBudget.

bidStrategystring
Campaign-level bid strategy. Only with isCampaignBudget.
Available optionsLOWEST_COST_WITHOUT_CAPLOWEST_COST_WITH_BID_CAPCOST_CAP
bidAmountnumber

Default bid cap / cost-per-result goal in account currency for every ad set; an ad set's own bidAmount wins. Only with isCampaignBudget or adsetBudgetSharing.

adsetBudgetSharingboolean

Ad set budget sharing: Meta may move up to 20% of an ad set budget to sibling ad sets. Mutually exclusive with isCampaignBudget.

sourcestring

Campaign data source

customValueMappingsobject

User-provided overrides for custom_values merge tags used in ad copy

Example (auto)

{
  "id": "camp_123",
  "locationId": "loc_abc123",
  "name": "Summer Campaign",
  "objective": "OUTCOME_LEADS",
  "specialAdCategories": [
    "NONE"
  ],
  "isCampaignBudget": false,
  "budget": {
    "budgetType": "DAILY",
    "amount": 1000
  },
  "bidStrategy": "LOWEST_COST_WITHOUT_CAP",
  "bidAmount": 2.5,
  "adsetBudgetSharing": false,
  "source": "facebook",
  "customValueMappings": {
    "{{ custom_values.pet_name }}": "Fluffy"
  }
}

application/json

The saved campaign, without its ad sets

application/json

Schema

Schema

idstringrequired

Campaign identifier

namestringrequired

Campaign name

locationIdstringrequired

Location identifier

fbAdAccountIdstringrequired

Ad account the campaign belongs to

fbCampaignIdstring

Facebook campaign id, set once published

objectivestringrequired

Campaign objective

specialAdCategoriesstring[]required

Special ad categories declared for the campaign

publishingStatusstringrequired
Publishing status of the campaign itself. Independent of its children — pausing one ad set leaves the campaign PUBLISHED.
Available optionsDRAFTSCHEDULEDPUBLISHINGPUBLISHEDPAUSEDIN_REVIEWWITH_ISSUESREJECTEDARCHIVEDFAILED
fbErrorstringnullable

Despite the name this is not always an error. Reads return null when there is nothing to report and the upsert returns "", but pausing an ad set or an ad overwrites it with an informational notice — One or more adsets are paused or One or more ads are paused — which the matching resume clears back to null. Treat it as a status line, not a failure signal.

sourcestringrequired

Where the campaign was created from

metaobject

Ancillary campaign metadata

unpublishedChangesboolean

Whether the campaign has edits not yet published

createdAtstringrequired

Created at

updatedAtstringrequired

Updated at

Example (auto)

{
  "id": "6a323f3e4454921db1498ccf",
  "name": "Spring promotion",
  "locationId": "fRMewNQIxSyZ5R4nQyit",
  "fbAdAccountId": "act_357046700569338",
  "fbCampaignId": "120250378905720122",
  "objective": "OUTCOME_LEADS",
  "specialAdCategories": [
    "NONE"
  ],
  "publishingStatus": "DRAFT",
  "fbError": null,
  "source": "AD_MANAGER",
  "meta": {
    "evaluate": "{\"opportunityScore\":25,\"band\":\"Low\",\"categories\":[],\"fixItems\":[],\"sacCompliance\":{\"applicable\":false}}"
  },
  "unpublishedChanges": false,
  "createdAt": "2026-06-17T06:31:26.599Z",
  "updatedAt": "2026-08-19T11:45:39.340Z"
}