Update a Campaign Plan
Updates a Campaign Plan. Send the base_revision you read. Omit a field to keep it. Send null to clear it.
Any change puts an approved plan back into draft. An approval speaks about content, and it cannot survive a change to that content. A write that changes nothing keeps the approval.
The answer is 409 with error=currency_frozen if a Line Item already has a budget, with error=revision_mismatch if the plan changed after you read it, and with error=slug_conflict if the new name gives a slug that already exists.
/context/campaign-plans/{slug}AuthorizationBearer token · headerrequiredSend Authorization: Bearer <credential>. Two credentials work.
An API key (acr_…) is what a server integration uses. Create one in the AdCrunch console under Settings → API keys — see https://docs.adcrunch.dev/account/api-keys. A key is bound to the organization that was active when you created it, and it keeps acting on that organization whatever you do later. It carries the permissions of the member who created it.
A session issued by the AdCrunch sign-in flow also works, which is how the console calls this service from the browser.
Either way the organization comes from the credential. There is no organization parameter.
slugstringrequiredapplication/jsonbase_revisionintegerrequiredThe revision last read via GET — guards concurrent edits.
brand_namestring | nullRe-point the plan at another Brand by slug; null unlinks it. Refused with 409 error=persona_not_in_brand while any Line Item still names a Persona of the current Brand.
currencystringISO 4217. Refused with 409 error=currency_frozen once any Line Item carries a budget — re-denominating a costed plan would silently reinterpret every number in it.
descriptionstringend_datestring | nullnull makes the plan always-on — which also flips every inheriting line’s amount from a total to a daily rate.
measurementstring | nullnamestringrationalestring | nullslugstringOptional new slug handle (a deliberate rename).
start_datestring | nulltotal_budgetinteger | nullnull means "no declared constraint", not zero.
The Campaign Plan as it now stands.
allocationobjectrequiredDerived on every read. Never stored.
Show propertiesHide properties
allocatednumber | nullrequiredThe sum of the Line Item budgets. null when the lines mix units, because that sum would be meaningless.
comparablebooleanrequiredFalse when the lines mix totals and daily rates. A surface must then print "not comparable" rather than a plausible-looking wrong total.
unallocatednumber | nullrequiredThe envelope less the allocated, where both are known.
unitstring | nullrequiredThe shared unit, when the lines agree on one.
totaldailybrandIdstring | nullrequiredNullable and mutable: a plan may precede its brand, cover a portfolio, or be re-pointed. Deleting a Brand leaves its plans standing.
createdAtnumberrequiredMilliseconds since the Unix epoch, UTC.
createdBystringrequiredcurrencystringrequiredEditable until the first Line Item budget, and frozen thereafter.
descriptionstringrequiredendDatestring | nullrequiredA calendar date, YYYY-MM-DD.
idstringrequiredlineItemsobject[]requiredShow propertiesHide properties
objectadvertiserIdstring | nullrequiredageMaxnumber | nullrequiredageMinnumber | nullrequiredEach bound is independently optional, so "35+" is expressible.
budgetnumber | nullrequiredInteger minor units of the plan’s currency.
campaignPlanIdstringrequiredchannelstringrequiredThe planner’s word for what is being bought, not a provider name. A plan may name a channel we cannot execute.
metatiktoksnapchatgoogle_searchgoogle_pmaxgoogle_displayyoutubeprogrammatic_displaylinkedinxcountriesstring[]requiredcreatedAtnumberrequiredMilliseconds since the Unix epoch, UTC.
createdBystringrequiredeffectiveEndDatestring | nullrequiredThe line’s own bound where it has one, else the plan’s.
effectiveStartDatestring | nullrequiredA calendar date, YYYY-MM-DD.
endDatestring | nullrequiredA calendar date, YYYY-MM-DD.
executablebooleanrequiredWhether this channel could be executed at all today. Derived from our capabilities, never a promise that it will be.
executionsobject[]requiredWhat this line has spawned. Never a claim that it is finished — nobody declared how many objects a line should produce.
Show propertiesHide properties
objectadvertiserIdstringrequiredcreatedAtnumberrequiredMilliseconds since the Unix epoch, UTC.
entityIdstringrequiredThe provider’s own id, unprefixed, so it joins to entities.
entityTypestringrequiredThe provider’s word for the level — campaign, adset, ad.
idstringrequiredmutationWorkflowIdstring | nullrequiredThe durable execution that performed the write, when known.
providerstringrequiredgenderstring | nullrequiredallmenwomenidstringrequiredobjectivestringrequiredawarenessengagementleadssalestrafficapp_promotionpersonaIdstring | nullrequiredExplains the targeting; never supplies its values.
providerstring | nullrequiredWho sells this channel, or null when nobody we integrate with does.
revisionnumberrequiredIncrements on every write. Send it back as base_revision to edit; a stale one answers 409.
startDatestring | nullrequiredA calendar date, YYYY-MM-DD.
statusstringrequiredvalidated is the gate on execution.
draftvalidatedunitstringrequiredHow budget reads, derived from the effective end date. Present → a total for the period; absent → a daily rate. A surface must print this beside the amount.
totaldailyupdatedAtnumber | nullrequiredMilliseconds since the Unix epoch, UTC.
measurementstring | nullrequirednamestringrequiredrationalestring | nullrequiredrevisionnumberrequiredIncrements on every write. Send it back as base_revision to edit; a stale one answers 409.
slugstringrequiredstartDatestring | nullrequiredA calendar date, YYYY-MM-DD.
statusstringrequiredThe only two stored states. active, closed and "executed" are derived, never stored.
draftapprovedtotalBudgetnumber | nullrequiredupdatedAtnumber | nullrequiredMilliseconds since the Unix epoch, UTC.
No credential, or one that does not resolve. Send an API key or a session. See the security scheme. error is unauthorized.
errorstringrequiredA stable code for the failure. This is the field to branch on. It does not change for a given failure.
unauthorizedmessagestringrequiredA sentence to show a person. Written to say what to do next. Reworded whenever it can be said better, so never branch on it.
The caller does not hold campaign_plan:write. error is forbidden.
errorstringrequiredA stable code for the failure. This is the field to branch on. It does not change for a given failure.
forbiddenmessagestringrequiredA sentence to show a person. Written to say what to do next. Reworded whenever it can be said better, so never branch on it.
No Campaign Plan with that slug, or brand_name names no Brand. error is not_found for both.
errorstringrequiredA stable code for the failure. This is the field to branch on. It does not change for a given failure.
messagestringrequiredA sentence to show a person. Written to say what to do next. Reworded whenever it can be said better, so never branch on it.
Four codes share this status. revision_mismatch: somebody wrote first. slug_conflict: the rename collides. persona_not_in_brand: re-pointing the plan would orphan Line Items that name a Persona of the current Brand, and lineItemIds names them — they are not cleared for you. currency_frozen: a Line Item already carries a budget, so the denomination is fixed; nothing is ever converted.
currentRevisionnumberrequiredThe revision the row holds now. Re-read, re-apply your edit on top, and send this back as base_revision.
errorstringrequiredA stable code for the failure. This is the field to branch on. It does not change for a given failure.
revision_mismatchmessagestringrequiredA sentence to show a person. Written to say what to do next. Reworded whenever it can be said better, so never branch on it.
slugstringrequiredThe slug that is already taken.
errorstringrequiredA stable code for the failure. This is the field to branch on. It does not change for a given failure.
slug_conflictmessagestringrequiredA sentence to show a person. Written to say what to do next. Reworded whenever it can be said better, so never branch on it.
invalid_slug, invalid_currency, invalid_amount or invalid_window.
errorstringrequiredA stable code for the failure. This is the field to branch on. It does not change for a given failure.
messagestringrequiredA sentence to show a person. Written to say what to do next. Reworded whenever it can be said better, so never branch on it.