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 Campaign Plan was approved, this call puts the Campaign Plan back into draft, and the answer tells you so.
/context/campaign-plans/{slug}/line-itemsAuthorizationBearer token · headerrequiredSend 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.
slugstringrequiredapplication/jsonadvertiser_idstringThe ad account this line runs through. On the line rather than the Campaign Plan, because an account belongs to one provider and a Campaign Plan spans several channels.
age_maxintegerage_minintegerbudgetnumberWhole units of the plan’s currency: 40.5 is €40.50. 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 Campaign 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 Campaign 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 Campaign Plan’s.
The Line Item, and the Campaign 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 Campaign Plan to draft, and you have to be told. The line carries the dates it resolves to, the provider that sells its channel, and the unit its amount reads in.
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 | nullrequiredWhole 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.
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[]requiredOne entry for each field that does not match.
Show propertiesHide properties
objectinstringrequiredThe part of the request that holds the field.
bodycookieheadersparamsquerymessagestringrequiredA sentence to show a person. Written to say what to do next. Reworded whenever it can be said better, so never branch on it.
pathstringrequiredA JSON Pointer into that part of the request, such as /filename. An empty string is the whole part.
errorstringrequiredA stable code for the failure. This is the field to branch on. It does not change for a given failure.
invalid_requestmessagestringrequiredA 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 API key, or one that does not resolve. 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 (each entry must be a two-letter ISO 3166-1 alpha-2 code; AdCrunch puts it in upper case for you and removes a duplicate); invalid_age_range (each bound is a whole number from 0 to 120, and the minimum may not exceed the maximum); invalid_amount (whole units of the Campaign Plan’s currency, with no more decimals than the currency has, never negative); invalid_window; persona_not_in_brand (a Persona must belong to the Campaign 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.