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, because the approval of a plan speaks about the whole allocation. To open the gate again, validate the line again.

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

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

budgetinteger | null

Integer minor units (cents), never major units.

min 0 · max 9007199254740991

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 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 plan status. Any change returns a validated line to draft.

advertiserIdstring | nullrequired

ageMaxnumber | nullrequired

ageMinnumber | nullrequired

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

budgetnumber | nullrequired

Integer minor 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.

401

No credential, or one that does not resolve. Send an API key or a session. 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

invalid_countries, invalid_age_range, invalid_amount, invalid_window, persona_not_in_brand or advertiser_not_owned.

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.adcrunch.dev/context/campaign-plans/string/line-items/string" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "advertiser_id": "string",
  "age_max": 0,
  "age_min": 0,
  "base_revision": -9007199254740991,
  "budget": 0,
  "channel": "meta",
  "countries": [
    "st"
  ],
  "end_date": "string",
  "gender": "all",
  "objective": "awareness",
  "persona_id": "string",
  "start_date": "string"
}'

const response = await fetch("https://api.adcrunch.dev/context/campaign-plans/string/line-items/string", {
  method: "PATCH",
  headers: {
    "Authorization": "Bearer YOUR_TOKEN",
    "Content-Type": "application/json"
  },
  body: "{\n  \"advertiser_id\": \"string\",\n  \"age_max\": 0,\n  \"age_min\": 0,\n  \"base_revision\": -9007199254740991,\n  \"budget\": 0,\n  \"channel\": \"meta\",\n  \"countries\": [\n    \"st\"\n  ],\n  \"end_date\": \"string\",\n  \"gender\": \"all\",\n  \"objective\": \"awareness\",\n  \"persona_id\": \"string\",\n  \"start_date\": \"string\"\n}"
});

import requests

response = requests.patch(
    "https://api.adcrunch.dev/context/campaign-plans/string/line-items/string",
    headers={
        "Authorization": "Bearer YOUR_TOKEN",
        "Content-Type": "application/json"
    },
    data="{\n  \"advertiser_id\": \"string\",\n  \"age_max\": 0,\n  \"age_min\": 0,\n  \"base_revision\": -9007199254740991,\n  \"budget\": 0,\n  \"channel\": \"meta\",\n  \"countries\": [\n    \"st\"\n  ],\n  \"end_date\": \"string\",\n  \"gender\": \"all\",\n  \"objective\": \"awareness\",\n  \"persona_id\": \"string\",\n  \"start_date\": \"string\"\n}",
)

Response

{
  "advertiserId": "string",
  "ageMax": 0,
  "ageMin": 0,
  "budget": 0,
  "campaignPlanId": "string",
  "channel": "meta",
  "countries": [
    "string"
  ],
  "createdAt": 0,
  "createdBy": "string",
  "effectiveEndDate": "string",
  "effectiveStartDate": "string",
  "endDate": "string",
  "executable": true,
  "executions": [
    {
      "advertiserId": "string",
      "createdAt": 0,
      "entityId": "string",
      "entityType": "string",
      "id": "string",
      "mutationWorkflowId": "string",
      "provider": "string"
    }
  ],
  "gender": "all",
  "id": "string",
  "objective": "awareness",
  "personaId": "string",
  "provider": "string",
  "revision": 0,
  "startDate": "string",
  "status": "draft",
  "unit": "total",
  "updatedAt": 0
}

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

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

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

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

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