Update a Line Item

Updates a Line Item. Send the base_revision you read. Omit a field to keep it. Send null to clear it.

Any change puts a validated line back into draft. Only that line changes. The Campaign Plan keeps its approval, because that approval speaks about the whole allocation. To open the gate again, validate the line again.

A write that changes nothing keeps the validation, and it does not move the revision.

The provider objects that the line already created do not change. This call never alters a live campaign.

PATCH/context/campaign-plans/{slug}/line-items/{lineItemId}

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

lineItemIdstringrequired

matches ^lni_[\s\S]{0,}$

slugstringrequired

Request body

requiredapplication/json

advertiser_idstring | null

null unlinks the ad account.

matches ^acc_[\s\S]{0,}$

age_maxinteger | null

min 0 · max 120

age_mininteger | null

min 0 · max 120

base_revisionintegerrequired

The revision last read via GET — guards concurrent edits.

min -9007199254740991 · max 9007199254740991

budgetnumber | null

Whole units of the plan’s currency: 40.5 is €40.50. No more decimals than the currency has.

min 0

channelstring

What is being bought, in a planner’s vocabulary — not a provider. Curated and deliberately incomplete.

Allowed:metatiktoksnapchatgoogle_searchgoogle_pmaxgoogle_displayyoutubeprogrammatic_displaylinkedinx

countriesstring[]

The array is the value — sending [] clears the geography.

end_datestring | null

null makes the line inherit the Campaign Plan’s end — which can flip the budget between a total and a daily rate. That is allowed, and it reverts the line to draft.

matches ^\d{4}-\d{2}-\d{2}$

genderstring | null

Omit for undecided, which executes the same as "all".

Allowed:allmenwomen

objectivestring

Provider-neutral outcome, translated at execution. There is deliberately no optimization goal here.

Allowed:awarenessengagementleadssalestrafficapp_promotion

persona_idstring | null

matches ^psn_[\s\S]{0,}$

start_datestring | null

matches ^\d{4}-\d{2}-\d{2}$

Responses

200

The Line Item, bare rather than wrapped — unlike the create, which also reports the Campaign Plan status. Any change returns a validated line to draft. executions lists what the line created, the same as a read of its Campaign Plan.

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.

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 such plan, or no Line Item with that id on it. error is not_found.

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

The Line Item moved since you read it. error is revision_mismatch.

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.

422

Six codes share this status. invalid_countries, invalid_age_range, invalid_amount, invalid_window, persona_not_in_brand or advertiser_not_owned. Each one is checked against the row as it would stand after the change, not against what you sent.

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/line-items/string" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "base_revision": 2,
  "budget": 3000,
  "countries": [
    "FR",
    "BE",
    "NL"
  ]
}'

const response = await fetch("https://api.pr-701.adcrunch.dev/context/campaign-plans/string/line-items/string", {
  method: "PATCH",
  headers: {
    "Authorization": "Bearer YOUR_TOKEN",
    "Content-Type": "application/json"
  },
  body: "{\n  \"base_revision\": 2,\n  \"budget\": 3000,\n  \"countries\": [\n    \"FR\",\n    \"BE\",\n    \"NL\"\n  ]\n}"
});

import requests

response = requests.patch(
    "https://api.pr-701.adcrunch.dev/context/campaign-plans/string/line-items/string",
    headers={
        "Authorization": "Bearer YOUR_TOKEN",
        "Content-Type": "application/json"
    },
    data="{\n  \"base_revision\": 2,\n  \"budget\": 3000,\n  \"countries\": [\n    \"FR\",\n    \"BE\",\n    \"NL\"\n  ]\n}",
)

Response

{
  "advertiserId": "acc_1203456789012345",
  "ageMax": 44,
  "ageMin": 25,
  "budget": 3000,
  "campaignPlanId": "cpl_4e1a08",
  "channel": "meta",
  "countries": [
    "FR",
    "BE",
    "NL"
  ],
  "createdAt": 1768435200000,
  "createdBy": "usr_5d2b71",
  "effectiveEndDate": "2026-05-31",
  "effectiveStartDate": "2026-03-01",
  "endDate": null,
  "executable": true,
  "executions": [],
  "gender": "all",
  "id": "lni_2d9e77",
  "objective": "sales",
  "personaId": "psn_8c4a20",
  "provider": "meta",
  "revision": 3,
  "startDate": null,
  "status": "draft",
  "unit": "total",
  "updatedAt": 1769644800000
}

{
  "issues": [
    {
      "in": "body",
      "message": "string",
      "path": "string"
    }
  ],
  "error": "invalid_request",
  "message": "string"
}

{
  "error": "unauthorized",
  "message": "string"
}

{
  "error": "forbidden",
  "message": "string"
}

{
  "error": "string",
  "message": "string"
}

{
  "currentRevision": 0,
  "error": "revision_mismatch",
  "message": "string"
}

{
  "error": "string",
  "message": "string"
}