---
title: "Add a Line Item"
method: POST
path: "/context/campaign-plans/{slug}/line-items"
tags: ["Line Items"]
---

# Add a Line Item

`POST /context/campaign-plans/{slug}/line-items`

## Request

- Base URL: `https://api.adcrunch.dev`
- URL: `https://api.adcrunch.dev/context/campaign-plans/{slug}/line-items`
- Auth: HTTP bearer

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.

## Path parameters

- `slug` string, required

## Request body

- object
  - `advertiser_id` string: The 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_max` integer
  - `age_min` integer
  - `budget` number: Whole 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.
  - `channel` 'meta' | 'tiktok' | 'snapchat' | 'google_search' | 'google_pmax' | 'google_display' | 'youtube' | 'programmatic_display' | 'linkedin' | 'x', required: What is being bought, in a planner’s vocabulary — not a provider. Curated and deliberately incomplete.
  - `countries` string[]: ISO 3166-1 alpha-2. Empty is a drafting state, not an error.
  - `end_date` string: Omit to inherit the Campaign Plan’s. Present (here or inherited) makes the budget a total for the period; absent makes it a daily rate.
  - `gender` 'all' | 'men' | 'women': Omit for undecided, which executes the same as "all".
  - `objective` 'awareness' | 'engagement' | 'leads' | 'sales' | 'traffic' | 'app_promotion', required: Provider-neutral outcome, translated at execution. There is deliberately no optimization goal here.
  - `persona_id` string: Must 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_date` string: Omit to inherit the Campaign Plan’s.

## Response `201`

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.

- object
  - `campaignPlanStatus` 'draft' | 'approved', required: The plan’s status after the insert. Adding a row to an approved plan returns it to draft.
  - `lineItem` object, required
    - `advertiserId` string, nullable, required
    - `ageMax` number, nullable, required
    - `ageMin` number, nullable, required: Each bound is independently optional, so "35+" is expressible.
    - `budget` number, nullable, required: Whole units of the **plan’s** currency.
    - `campaignPlanId` string, required
    - `channel` 'meta' | 'tiktok' | 'snapchat' | 'google_search' | 'google_pmax' | 'google_display' | 'youtube' | 'programmatic_display' | 'linkedin' | 'x', required: The planner’s word for what is being bought, not a provider name. A plan may name a channel we cannot execute.
    - `countries` string[], required
    - `createdAt` number, required: Milliseconds since the Unix epoch, UTC.
    - `createdBy` string, required
    - `effectiveEndDate` string, nullable, required: The line’s own bound where it has one, else the plan’s.
    - `effectiveStartDate` string, nullable, required: A calendar date, `YYYY-MM-DD`.
    - `endDate` string, nullable, required: A calendar date, `YYYY-MM-DD`.
    - `executable` boolean, required: Whether this channel could be executed at all today. Derived from our capabilities, never a promise that it will be.
    - `executions` object[], required: What this line has spawned. Never a claim that it is *finished* — nobody declared how many objects a line should produce.
      - `advertiserId` string, required
      - `createdAt` number, required: Milliseconds since the Unix epoch, UTC.
      - `entityId` string, required: The provider’s own id, unprefixed, so it joins to `entities`.
      - `entityType` string, required: The provider’s word for the level — `campaign`, `adset`, `ad`.
      - `id` string, required
      - `mutationWorkflowId` string, nullable, required: The durable execution that performed the write, when known.
      - `provider` string, required
    - `gender` 'all' | 'men' | 'women', nullable, required
    - `id` string, required
    - `objective` 'awareness' | 'engagement' | 'leads' | 'sales' | 'traffic' | 'app_promotion', required
    - `personaId` string, nullable, required: Explains the targeting; never supplies its values.
    - `provider` string, nullable, required: Who sells this channel, or null when nobody we integrate with does.
    - `revision` number, required: Increments on every write. Send it back as `base_revision` to edit; a stale one answers 409.
    - `startDate` string, nullable, required: A calendar date, `YYYY-MM-DD`.
    - `status` 'draft' | 'validated', required: `validated` is the gate on execution.
    - `unit` 'total' | 'daily', required: 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.
    - `updatedAt` number, nullable, required: Milliseconds since the Unix epoch, UTC.

## Other responses

- `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.
- `401`: No API key, or one that does not resolve. See the security scheme. `error` is `unauthorized`.
- `402`: The organization has no active subscription. An owner subscribes at `paywallUrl`. `error` is `organization_unentitled`.
- `403`: The caller does not hold `campaign_plan:write`. `error` is `forbidden`.
- `404`: No Campaign Plan with that slug. `error` is `not_found`.
- `422`: 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`.

---

[API](https://skmtc.dev/adcrunch/apis/adcrunch-api.md) · [All operations](https://skmtc.dev/adcrunch/apis/adcrunch-api/llms.txt) · [OpenAPI document](https://skmtc.dev/adcrunch/apis/adcrunch-api/revisions/a420ba80914f?raw)