Add a Line Item
Adds a Line Item to a Campaign Plan. One Line Item is one thing you buy. It is coarser than an ad set, and it is not one campaign.
A Line Item holds the envelope of an intent, not a script for execution. One line can produce more than one provider object. Therefore it holds only what is the same for all of them. This is why a line has no optimization goal.
Only the channel and the objective are necessary. The new line starts in draft. If the plan was approved, this call puts the plan back into draft, and the answer tells you so.
/context/campaign-plans/{slug}/line-items/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/jsonadvertiser_idstringThe ad account this line runs through. On the line rather than the plan, because an account belongs to one provider and a plan spans several channels.
age_maxintegerage_minintegerbudgetintegerInteger minor units of the plan’s currency. Whether it reads as a total or a daily rate is derived from the effective end date, never stored.
channelstringrequiredWhat is being bought, in a planner’s vocabulary — not a provider. Curated and deliberately incomplete.
metatiktoksnapchatgoogle_searchgoogle_pmaxgoogle_displayyoutubeprogrammatic_displaylinkedinxcountriesstring[]ISO 3166-1 alpha-2. Empty is a drafting state, not an error.
end_datestringOmit to inherit the plan’s. Present (here or inherited) makes the budget a total for the period; absent makes it a daily rate.
genderstringOmit for undecided, which executes the same as "all".
allmenwomenobjectivestringrequiredProvider-neutral outcome, translated at execution. There is deliberately no optimization goal here.
awarenessengagementleadssalestrafficapp_promotionpersona_idstringMust belong to the plan’s Brand. It explains the targeting and never supplies its values — the countries and age range above are what execute.
start_datestringOmit to inherit the plan’s.
The Line Item, and the plan’s status after the insert. This is the one create here that wraps its row: adding a line to an approved plan returns that plan to draft, and you have to be told.
campaignPlanStatusstringrequiredThe plan’s status after the insert. Adding a row to an approved plan returns it to draft.
draftapprovedlineItemobjectrequiredShow propertiesHide properties
advertiserIdstring | 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.
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. error is not_found.
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.
Six codes share this status. invalid_countries (ISO 3166-1 alpha-2, uppercase); invalid_age_range; invalid_amount (whole minor units of the plan’s currency, never negative); invalid_window; persona_not_in_brand (a Persona must belong to the plan’s Brand, so a brandless plan can name none); advertiser_not_owned.
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.