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.
Rules Summary
Section titled “Rules Summary”| 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 |
1. Campaign & Line Item Cardinality
Section titled “1. Campaign & Line Item Cardinality”- Creation: When creating a campaign, the
line_itemsarray must contain at least 1 line item payload. An empty array is rejected like a missing one, withREQUIRED. - Update: Line items are managed independently of the campaign via
PUT /line-itemsandDELETE /line-items, each capped at 3,000 items per request.
2. Budget Rules
Section titled “2. Budget Rules”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.
Minimum budget
Section titled “Minimum budget”- Every line item’s
budget.amountmust 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
GTEon the line item,params.mingiving 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" } } ] }}Expenditure floor on updates
Section titled “Expenditure floor on updates”- Once a line item is delivering, money is spent from its budget.
- When updating an existing line item (
idprovided), 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_SPENDon the line item,params.spent_in_usdgiving 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" } } ] }}All or nothing
Section titled “All or nothing”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.
3. Flight Dates & Duration Window
Section titled “3. Flight Dates & Duration Window”Flight dates determine when line item creatives are eligible to participate in ad auctions:
start_date: The date and time (RFC 3339, UTC) at which ad delivery may begin. Required.end_date: The date and time (RFC 3339, UTC) at which ad delivery stops. Required and must be in the future.- Chronological validity:
end_datemust be strictly later thanstart_date(start_date < end_date). - Maximum duration: The serving window of a single line item cannot exceed 90 calendar days:
end_date - start_date <= 90 daysCampaigns requiring longer flights must be renewed or extended incrementally.
4. Resource Identifiers
Section titled “4. Resource Identifiers”- Campaign ID: Required on
PUT /line-items; thecampaign_idmust be a valid 24-character hexadecimal string identifying a campaign.
5. Campaign Level Aggregation
Section titled “5. Campaign Level Aggregation”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_dateamong all line items in the campaign. - Aggregated end date: The latest
end_dateamong all line items in the campaign. - Aggregated status:
STATUS_PLAYINGif any line item is playing; otherwiseSTATUS_PAUSEDif any is paused; otherwiseSTATUS_UNSPECIFIED. - New line items default to
STATUS_UNSPECIFIEDif thestatusfield is omitted on creation.