Skip to content
AdCrunch
Esc
↑↓navigate↵open⌘Jpreview

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, and it does not move the revision.

The Line Items keep the state they hold. The revert is local to the Campaign Plan, so a validated line stays validated.

The answer is 409 with error=currency_frozen if a Line Item already has a budget, with error=revision_mismatch if the Campaign Plan changed after you read it, and with error=slug_conflict if the new name gives a slug that already exists.

PATCH/context/campaign-plans/{slug}
Authorization
AuthorizationBearer token · headerrequired

Send Authorization: Bearer <credential>.

Use an API key (acr_…), from the AdCrunch console under Settings → API keys.

The credential names the organization, and no operation takes an organization parameter.

See https://docs.adcrunch.dev/api/authentication.

Path parameters
slugstringrequired
Request body
requiredapplication/json
base_revisionintegerrequired

The revision last read via GET — guards concurrent edits.

min -9007199254740991 · max 9007199254740991
brand_namestring | null

Re-point the Campaign 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.

currencystring

ISO 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.

min length 3 · max length 3
descriptionstring
min length 1 · max length 500
end_datestring | null

null makes the Campaign Plan always-on — which also flips every inheriting line’s amount from a total to a daily rate.

matches ^\d{4}-\d{2}-\d{2}$
measurementstring | null
min length 1
namestring
min length 1 · max length 120
rationalestring | null
min length 1
slugstring

Optional new slug handle (a deliberate rename).

max length 120
start_datestring | null
matches ^\d{4}-\d{2}-\d{2}$
total_budgetnumber | null

null means "no declared constraint", not zero.

min 0
Responses
200

The Campaign Plan as it now stands, with its Line Items. A change takes the approval away and moves the revision; the Line Items keep the state they hold.

allocationobjectrequired

Derived on every read. Never stored.

Show properties
allocatednumber | nullrequired

The sum of the Line Item budgets. null when the lines mix units, because that sum would be meaningless.

comparablebooleanrequired

False when the lines mix totals and daily rates. A surface must then print "not comparable" rather than a plausible-looking wrong total.

unallocatednumber | nullrequired

The envelope less the allocated, where both are known.

unitstring | nullrequired

The shared unit, when the lines agree on one.

Allowed:totaldaily
brandIdstring | nullrequired

Nullable and mutable: a plan may precede its brand, cover a portfolio, or be re-pointed. Deleting a Brand leaves its plans standing.

createdAtnumberrequired

Milliseconds since the Unix epoch, UTC.

createdBystringrequired
currencystringrequired

Editable until the first Line Item budget, and frozen thereafter.

descriptionstringrequired
endDatestring | nullrequired

A calendar date, YYYY-MM-DD.

idstringrequired
lineItemsobject[]required
Show properties
Array of object
advertiserIdstring | nullrequired
ageMaxnumber | nullrequired
ageMinnumber | nullrequired

Each bound is independently optional, so "35+" is expressible.

budgetnumber | nullrequired

Whole units of the plan’s currency.

campaignPlanIdstringrequired
channelstringrequired

The planner’s word for what is being bought, not a provider name. A plan may name a channel we cannot execute.

Allowed:metatiktoksnapchatgoogle_searchgoogle_pmaxgoogle_displayyoutubeprogrammatic_displaylinkedinx
countriesstring[]required
createdAtnumberrequired

Milliseconds since the Unix epoch, UTC.

createdBystringrequired
effectiveEndDatestring | nullrequired

The line’s own bound where it has one, else the plan’s.

effectiveStartDatestring | nullrequired

A calendar date, YYYY-MM-DD.

endDatestring | nullrequired

A calendar date, YYYY-MM-DD.

executablebooleanrequired

Whether this channel could be executed at all today. Derived from our capabilities, never a promise that it will be.

executionsobject[]required

What this line has spawned. Never a claim that it is finished — nobody declared how many objects a line should produce.

Show properties
Array of object
advertiserIdstringrequired
createdAtnumberrequired

Milliseconds since the Unix epoch, UTC.

entityIdstringrequired

The provider’s own id, unprefixed, so it joins to entities.

entityTypestringrequired

The provider’s word for the level — campaign, adset, ad.

idstringrequired
mutationWorkflowIdstring | nullrequired

The durable execution that performed the write, when known.

providerstringrequired
genderstring | nullrequired
Allowed:allmenwomen
idstringrequired
objectivestringrequired
Allowed:awarenessengagementleadssalestrafficapp_promotion
personaIdstring | nullrequired

Explains the targeting; never supplies its values.

providerstring | nullrequired

Who sells this channel, or null when nobody we integrate with does.

revisionnumberrequired

Increments on every write. Send it back as base_revision to edit; a stale one answers 409.

startDatestring | nullrequired

A calendar date, YYYY-MM-DD.

statusstringrequired

validated is the gate on execution.

Allowed:draftvalidated
unitstringrequired

How 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.

Allowed:totaldaily
updatedAtnumber | nullrequired

Milliseconds since the Unix epoch, UTC.

measurementstring | nullrequired
namestringrequired
rationalestring | nullrequired
revisionnumberrequired

Increments on every write. Send it back as base_revision to edit; a stale one answers 409.

slugstringrequired
startDatestring | nullrequired

A calendar date, YYYY-MM-DD.

statusstringrequired

The only two stored states. active, closed and "executed" are derived, never stored.

Allowed:draftapproved
totalBudgetnumber | nullrequired
updatedAtnumber | nullrequired

Milliseconds since the Unix epoch, UTC.

400

The request does not match the schema of this operation: a field is missing or has the wrong type, or the body is not valid JSON. error is invalid_request, and issues names each field. Nothing was changed.

issuesobject[]required

One entry for each field that does not match.

Show properties
Array of object
instringrequired

The part of the request that holds the field.

Allowed:bodycookieheadersparamsquery
messagestringrequired

A sentence to show a person. Written to say what to do next. Reworded whenever it can be said better, so never branch on it.

pathstringrequired

A JSON Pointer into that part of the request, such as /filename. An empty string is the whole part.

errorstringrequired

A stable code for the failure. This is the field to branch on. It does not change for a given failure.

Allowed:invalid_request
messagestringrequired

A sentence to show a person. Written to say what to do next. Reworded whenever it can be said better, so never branch on it.

401

No API key, or one that does not resolve. See the security scheme. error is unauthorized.

errorstringrequired

A stable code for the failure. This is the field to branch on. It does not change for a given failure.

Allowed:unauthorized
messagestringrequired

A sentence to show a person. Written to say what to do next. Reworded whenever it can be said better, so never branch on it.

403

The caller does not hold campaign_plan:write. error is forbidden.

errorstringrequired

A stable code for the failure. This is the field to branch on. It does not change for a given failure.

Allowed:forbidden
messagestringrequired

A sentence to show a person. Written to say what to do next. Reworded whenever it can be said better, so never branch on it.

404

No Campaign Plan with that slug, or brand_name names no Brand. error is not_found for both.

errorstringrequired

A stable code for the failure. This is the field to branch on. It does not change for a given failure.

messagestringrequired

A sentence to show a person. Written to say what to do next. Reworded whenever it can be said better, so never branch on it.

409

Four codes share this status. revision_mismatch: somebody wrote first. slug_conflict: the rename collides. persona_not_in_brand: re-pointing the Campaign 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.

Any of:
object
currentRevisionnumberrequired

The revision the row holds now. Re-read, re-apply your edit on top, and send this back as base_revision.

errorstringrequired

A stable code for the failure. This is the field to branch on. It does not change for a given failure.

Allowed:revision_mismatch
messagestringrequired

A sentence to show a person. Written to say what to do next. Reworded whenever it can be said better, so never branch on it.

object
slugstringrequired

The slug that is already taken.

errorstringrequired

A stable code for the failure. This is the field to branch on. It does not change for a given failure.

Allowed:slug_conflict
messagestringrequired

A sentence to show a person. Written to say what to do next. Reworded whenever it can be said better, so never branch on it.

422

invalid_slug, invalid_currency, invalid_amount or invalid_window.

errorstringrequired

A stable code for the failure. This is the field to branch on. It does not change for a given failure.

messagestringrequired

A sentence to show a person. Written to say what to do next. Reworded whenever it can be said better, so never branch on it.

Request
curl -X PATCH "https://api.pr-701.adcrunch.dev/context/campaign-plans/string" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "base_revision": 3,
  "end_date": "2026-06-30",
  "total_budget": 7500
}'
Response
{
  "allocation": {
    "allocated": 2500,
    "comparable": true,
    "unallocated": 5000,
    "unit": "total"
  },
  "brandId": "brd_6a9c33",
  "createdAt": 1768435200000,
  "createdBy": "usr_5d2b71",
  "currency": "EUR",
  "description": "The spring sale of Acme, on Meta, in France and Belgium.",
  "endDate": "2026-06-30",
  "id": "cpl_4e1a08",
  "lineItems": [
    {
      "advertiserId": "acc_1203456789012345",
      "ageMax": 44,
      "ageMin": 25,
      "budget": 2500,
      "campaignPlanId": "cpl_4e1a08",
      "channel": "meta",
      "countries": [
        "FR",
        "BE"
      ],
      "createdAt": 1768435200000,
      "createdBy": "usr_5d2b71",
      "effectiveEndDate": "2026-05-31",
      "effectiveStartDate": "2026-03-01",
      "endDate": null,
      "executable": true,
      "executions": [
        {
          "advertiserId": "acc_1203456789012345",
          "createdAt": 1772409600000,
          "entityId": "120210000000000",
          "entityType": "campaign",
          "id": "exe_7a4c12",
          "mutationWorkflowId": "b3d1f0c4-6a2e-4a1f-9f77-2c0d1e5a8b94",
          "provider": "meta"
        }
      ],
      "gender": "all",
      "id": "lni_2d9e77",
      "objective": "sales",
      "personaId": "psn_8c4a20",
      "provider": "meta",
      "revision": 2,
      "startDate": null,
      "status": "validated",
      "unit": "total",
      "updatedAt": 1769040000000
    }
  ],
  "measurement": "Revenue in the window, against the spring of 2025.",
  "name": "Spring Sale 2026",
  "rationale": "Meta carries the reach. One line keeps the budget in one place.",
  "revision": 4,
  "slug": "spring-sale",
  "startDate": "2026-03-01",
  "status": "draft",
  "totalBudget": 7500,
  "updatedAt": 1769644800000
}