Skip to content

Business Rules & Constraints

The Portal API enforces a set of business rules on campaigns, line items, budgets, and flight dates.

This page describes each rule and the error code returned in error.details when it is violated.


Entity & attribute Rule Error code(s)
Campaign name Required; 1 to 255 characters; must not contain only whitespace REQUIRED, MAX_LEN, NOT_BLANK
Campaign line items At least 1 on creation, an empty array is reported as missing; up to 3,000 per request REQUIRED, MAX_ITEMS
Line item name (POST /line-items/campaigns) Optional; defaults to Line item N when omitted or empty; otherwise 1 to 255 characters and not only whitespace MAX_LEN, NOT_BLANK
Line item name (PUT /line-items) Required; 1 to 255 characters; must not contain only whitespace REQUIRED, MAX_LEN, NOT_BLANK
Creative and area names Required; 1 to 255 characters; must not contain only whitespace REQUIRED, MAX_LEN, NOT_BLANK
Tags on line item, creative and area writes Each tag must be 3 to 255 characters and not only whitespace MIN_LEN, MAX_LEN, NOT_BLANK
Line item budget Required REQUIRED
Line item budget amount Required, greater than 0 and at most 1,000,000,000,000 REQUIRED, GT_LTE
Line item budget amount At least the equivalent of 10 USD in the selected currency GTE
Line item budget amount (PUT /line-items) Cannot be set below the amount already spent LINE_ITEM_BUDGET_BELOW_SPEND
Line item budget currency Required, a known currency with a published exchange rate REQUIRED, DEFINED_ONLY, CURRENCY_CONVERTIBLE
Line item start date Required (RFC 3339, UTC) REQUIRED
Line item end date Required (RFC 3339, UTC) REQUIRED
Line item end date Must be in the future GT_NOW
Line item end date Must be after start_date AFTER_START_DATE
Line item end date Within 90 days of start_date MAX_DURATION
Line item status Defaults to STATUS_UNSPECIFIED on creation; kept on update when omitted —
Line item campaign (PUT /line-items) On creation or when its campaign changes, must be an existing campaign of your account LINE_ITEM_CAMPAIGN_NOT_FOUND
Line item pricing policy (PUT /line-items) When set, must be an existing pricing policy of your account LINE_ITEM_PRICING_POLICY_NOT_FOUND
Line item creatives (PUT /line-items) Each creative must be an existing creative of your account LINE_ITEM_CREATIVE_NOT_FOUND
Targeting deletion Refused while a line item that has not ended uses the targeting TARGETING_IN_USE
DCO deletion Refused while a line item that has not ended uses the DCO DYNAMIC_CONTENT_OPTIMIZATION_IN_USE

  • Creation: When creating a campaign, the line_items array must contain at least 1 line item payload. An empty array is rejected like a missing one, with REQUIRED.
  • Update: Line items are managed independently of the campaign via PUT /line-items and DELETE /line-items, each capped at 3,000 items per request.

Every line item carries its own budget, an amount in a currency. Budgets are validated in real time against current platform exchange rates and the amount already spent, and are drawn from your account’s wallet.

  • Every line item’s budget.amount must be at least the equivalent of 10.00 USD at current exchange rates.
  • For example, if EUR/USD is 1.08, a budget in EUR must be at least €9.26; a budget in JPY must be at least approximately ¥1,550.
  • The minimum only applies to a new budget or to one whose amount or currency changes: a budget sent unchanged on an update is accepted even if a rate move has since taken it under 10 USD.
  • A budget under the minimum fails with GTE on the line item, params.min giving the minimum in USD:
{
"error": {
"code": "BAD_REQUEST",
"message": "Bad Request",
"details": [
{
"field": "line_items[0]",
"code": "GTE",
"message": "The converted amount must be greater than or equal to 10 USD",
"params": {
"min": "10"
}
}
]
}
}
  • Once a line item is delivering, money is spent from its budget.
  • When updating an existing line item (id provided), the new budget cannot be set below the amount already spent.
  • Attempting to reduce a budget below accrued spend fails with LINE_ITEM_BUDGET_BELOW_SPEND on the line item, params.spent_in_usd giving the amount already spent in USD:
{
"error": {
"code": "BAD_REQUEST",
"message": "Bad Request",
"details": [
{
"field": "line_items[0]",
"code": "LINE_ITEM_BUDGET_BELOW_SPEND",
"message": "Line item budget must be greater than or equal to what has already been spent",
"params": {
"spent_in_usd": "250.5"
}
}
]
}
}

A budget error rejects the whole request: none of its line items is written, so the request can be fixed and sent again as is.


Flight dates determine when line item creatives are eligible to participate in ad auctions:

  1. start_date: The date and time (RFC 3339, UTC) at which ad delivery may begin. Required.
  2. end_date: The date and time (RFC 3339, UTC) at which ad delivery stops. Required and must be in the future.
  3. Chronological validity: end_date must be strictly later than start_date (start_date < end_date).
  4. Maximum duration: The serving window of a single line item cannot exceed 90 calendar days:
end_date - start_date <= 90 days

Campaigns requiring longer flights must be renewed or extended incrementally.


  • Campaign ID: Required on PUT /line-items; the campaign_id must be a valid 24-character hexadecimal string identifying a campaign.

A campaign returned by GET or PATCH does not store its own flight dates or status; these values are derived from its line items:

  • Aggregated start date: The earliest start_date among all line items in the campaign.
  • Aggregated end date: The latest end_date among all line items in the campaign.
  • Aggregated status: STATUS_PLAYING if any line item is playing; otherwise STATUS_PAUSED if any is paused; otherwise STATUS_UNSPECIFIED.
  • New line items default to STATUS_UNSPECIFIED if the status field is omitted on creation.