Skip to main content
After each read of your ad server, Apostra compares what it holds for a media buy with the terms you and the buyer agreed. The result is on the buy, per source, so you can see when your ad server has gone outside what was sold: a budget raised in your ad server, a flight that runs past the agreed dates, targeting that reaches more than was booked, or a rate edited. Apostra only reports the difference. It never changes your ad server to match the agreed terms, because the change may be intentional. You decide whether to put the line back or to agree the change with the buyer.
This check is in beta. It shows on the Media Buys page, and agents and the API read it through search and get with kind: "media_buy". If your buys carry no contractConformance field and the page shows no Out of line badge, your storefront is not on the beta.

What “in line with the agreed terms” means

The agreed terms are what Apostra last sent your source for the buy and your source accepted. An accepted update to the buy replaces them. The ad server’s own state is what your source reports from it. A buy is in line when every agreed field was compared and every one is within the booking. Within the booking is not the same as equal to it, field by field: A lower budget, a shorter flight or narrower targeting is therefore in line. A higher budget, a flight that runs past the agreed dates, targeting that reaches more, or a different rate is out of line. Apostra records a field that is within the booking but narrower than agreed as a note on the buy’s source, not as a difference. It does not make the buy out of line, does not raise an alert and does not rank the buy higher on the Media Buys page. The note is recorded now, and the Media Buys page and the search and get reads do not show it yet.

The three statuses

Each routed source on a buy has one of these, and the buy shows the combined result. Not comparable is never shown as in line. A source that reports less never looks more in line than one that reports everything. A buy is out of line as soon as one source is. It is in line only when every source is. The buyer reads this same recorded result as the buy’s booking answer: within the booking, outside the booking or not comparable, with the paths that are outside and none of the values. A buy you booked directly in your own ad server, without Apostra, has no agreed terms on Apostra’s side. It reads not comparable and is never flagged.

What each difference tells you

Every open difference on an out-of-line source carries: Values keep the shape AdCP gives them: amounts as numbers in the buy’s currency, times as ISO 8601, and targeting as an AdCP targeting overlay. A difference closes when a later read of your ad server no longer shows it. That happens when you put the line back, and also when you agree the change with the buyer and the update is accepted.

Which fields are compared

Your seller-side fulfilment is yours to change, so it is not compared: the ad units and placements that serve a product, exclusions, line-item priority and creative rotation. A buy’s lifecycle status follows your ad server.

Why some fields are not compared

A field that cannot be compared is listed in notCompared with a fieldPath and a reason. It keeps the buy from reading in line. Creative assignments are not listed as compared fields yet. A creative the buyer assigned that your ad server no longer holds is narrower than the booking, which is within it, so it never makes a buy out of line. Apostra records a difference only when it can show the value falls outside the booking. Where it could only fail to prove the value inside, the field is listed in notCompared instead, and the buy is not flagged out of line for it. Values that are equal, or within the booking, are always counted as compared, except that an amount below the agreed amount is within only when the amounts are on the same basis, as below. In practice that means:
  • Amounts are compared in one currency. A budget or rate is compared when the agreed terms and your source state the same currency. If either states none, an amount that differs is not compared (currency_not_confirmed). If both state a currency and the two differ, the currency is flagged and no amount is compared across it (currency_differs). The agreed terms of a buy state their currency in total_budget.currency, the currency the buy is priced in. Buys booked before Apostra began stating it have none, so a differing amount on those is not compared. Report the same currency for the buy from your source and its amounts are compared.
  • A total is compared with a total on the same basis. An agreed total that includes more than its packages (fees, for example) is not compared (total_basis_differs); the packages are. A source total below it is not a narrower budget, because the fees are not part of it.
  • A package budget is compared with the same split. A budget the agreed terms spread evenly across packages is compared per package only when your source split it the same way. Otherwise the total is compared.
  • Geography is flagged only when the areas provably reach beyond the booking. Your source holding no geography at all, a country or area the booking did not name, or a missing exclusion inside the targeted countries is flagged. Shapes that cannot be placed inside the booking, such as a whole country where the booking named only some of its regions, are geography_not_comparable.
Two rules make the comparison fair rather than strict:
  • Geography is compared by the area it reaches. Google Ad Manager can store a booking of “United States plus these metro areas” as the metro areas alone. That reaches the same people, so it is in line. It is not a missing country.
  • The comparison reads your sales agent’s answer only. Apostra does not read your ad server itself. It reads the AdCP answer and, where your sales agent reports them, the spend caps under ext.scope3.spend_caps, so it never rounds a budget to a goal unit for you. A package behind more than one ad-server object reports the combined budget, so two line items that can each spend the whole budget report twice the budget and read as a budget difference.

Spend caps

The budget the buyer accepted for a package is the most they agreed to pay. Your ad server holds that as a cap on every object that can spend for the package: for Google Ad Manager, a lifetime goal or a daily goal on each line item, counted in the unit the price is paid in. Where your sales agent reports those caps, under ext.scope3.spend_caps on each package, Apostra checks that together they stop the package’s spend at the accepted budget. A sales agent that reports none has no spend cap check, and it is not listed as not compared.

Daily caps

A daily cap is a spend cap when it cannot spend past the accepted budget. Your ad server stops the line item at its end date, so the most it can spend is what it has delivered plus its daily cap for every day left. Apostra counts those days:
  • from the first day your reported delivery does not cover, not from today. Delivery is reported late, so counting from today would leave out days that have already spent;
  • through the end date, end day included, with a part of a day counted as a whole day;
  • in your ad server’s time zone;
  • at the line item’s rate: each unit costs the line’s rate per 1,000 for CPM and vCPM, or per unit for CPC.
Your ad server can deliver a little past a daily goal on some days, so where a daily cap is among a package’s caps, Apostra allows 1% of the accepted budget above it, besides the cost of one unit per line item and half a cent. Apostra judges it again on every read. A daily cap on a line item with no end date can spend without limit, so it is out of line. Your sales agent reports a daily cap on an object whose cap is not_a_total, with amount_step set to the cost of one unit, as daily_cap:
A daily goal reported with no daily_cap, or with any of these missing or malformed, is a limit Apostra cannot evaluate: it never guesses the days.

When a spend cap is out of line

A package’s spend cap is out of line, with fieldPath packages[<id>].spend_cap, when the first of these holds: An object that costs nothing or is priced per day needs no cap. A cap in another currency than the accepted budget’s is not compared with it (currency_differs). agreed is the package’s accepted budget, and reported lists every object with its cap, as your sales agent read it. A daily cap is listed with its units, end_time and time_zone and without its delivery, so a read that shows only more delivery is the same difference. The note says the same in words. Your ad-server change is yours to make, and Apostra does not undo it. A spend cap difference alerts Apostra operations like any other money difference.

A spend conflict holds the buy

A spend cap difference is a spend conflict: the buyer’s money is at risk, because the buy can spend past what the buyer agreed to pay. Unlike any other difference, it holds the buy. While a spend conflict on a buy has no acceptance from you, Apostra refuses to resume the buy (update_media_buy with paused: false, from anyone) and refuses your approval of it, naming the conflicts. A difference in targeting, flight, pacing or rate alerts but never holds the buy. A resume or an approval is checked against the spend conflicts Apostra has recorded when the call is made. A conflict that appears in your ad server at the same moment is recorded on the buy’s next read, and the buy is paused then. Today spend conflicts come only from the Apostra embedded sales agent, which pauses such a buy itself, or Apostra does (see Apostra pauses the buy). A conflict ends when your ad server stops the spend at the accepted budget again: put the cap back, and the next read closes it.

Apostra pauses the buy

Apostra is taking this pause over from the Apostra embedded sales agent, one seller at a time. Until it moves you, the embedded sales agent pauses such a buy itself, and overruling a conflict does not resume it. Once Apostra has moved you:
  • When a spend conflict on a serving buy has no acceptance from you, Apostra pauses the buy: it sends update_media_buy with paused: true to your sales agent, once per conflict, and tells you and the buyer. A buy that is already paused is left as it is.
  • If your sales agent accepts that pause for review rather than applying it (for example, manual moderation), the buy keeps serving until you apply the pause there. Apostra counts the pause, and tells you and the buyer, only once it is applied, and sends nothing more for the buy while the review is open. The same holds for a resume. A review still open after a day is reported to Apostra’s team.
  • Apostra checks about once a minute, so a conflict that appears just after a resume went through is still paused on the next check.
  • When no spend conflict on the buy is left without your acceptance (you overruled each one, or you put the cap back and the conflict closed), Apostra resumes the buy and tells you and the buyer. It does not resume a buy that the buyer paused since Apostra paused it. If the buyer pauses it while the resume is on its way, Apostra sends the pause again at once, so your sales agent may briefly see a resume followed by a pause. If your sales agent refuses a resume, or that repeated pause, Apostra tries again about once a minute, up to ten times. After ten refused resumes the buy stays paused, and the buyer can still resume it; after ten refused pauses, Apostra stops and alerts its team.
  • Apostra cannot tell its own pause from one you set in your ad server. If you also paused the buy there for your own reasons, pause it there again after Apostra resumes it; the notice that Apostra resumed the buy says so.

Overrule a spend conflict

You can overrule a spend conflict without the buyer’s agreement. By overruling it you accept that one conflict and carry any spend above the budget the buyer accepted; the buyer is never billed above it. Apostra records your reason with the overrule. It is not shown to the buyer yet. Spend conflicts are work items waiting on you. Find them with search(kind: "work_item", filter: {workItemKind: "contract_conflict"}), which lists the ones you have not overruled (pending, the default status for every work item); add status: "approved" for the ones you have. Read one with get(kind: "work_item", workItemKind: "contract_conflict", id), and overrule it with:
on save_work_item. reviewerNotes is required. A conflict cannot be rejected: to end it, fix the cap in your ad server. Overruling one twice returns unchanged with your first reason.
  • The overrule records who accepted the conflict, when and why, and lifts the hold for that conflict only. It must come from a signed-in person, whose user is recorded. The response’s resumeDue is true when no spend conflict on the buy is left without an acceptance.
  • The conflict stays open and visible until your ad server stops the spend at the accepted budget.
  • If your ad server changes the conflict again, so that the agreed or reported value differs from what you accepted, it is a new conflict with no acceptance, and it holds the buy again.
  • Overruling does not itself resume the buy. Where Apostra paused it, Apostra resumes it once no spend conflict on it is left without your acceptance (see Apostra pauses the buy). Otherwise, once nothing holds it, the buy can be resumed as usual.

What to do about an out-of-line buy

  1. Check what changed. Read agreed and reported for each difference, money first. Your ad server’s change history shows who made it.
  2. If the change was not intended, put the line back in your ad server. The next read of your ad server closes the difference.
  3. If the change was intended, agree it with the buyer. When the buyer’s update is accepted, it becomes the agreed terms and the difference closes.
  4. If a field is only not comparable, nothing is wrong. Ask your source to report it from your ad server if you want it checked.
Billing follows the agreed terms, not your ad server. A rate raised in your ad server does not raise what the buyer pays. A budget raised there can deliver more than the buyer agreed to pay for, so settle it with the buyer.

What the Media Buys page shows

An out-of-line buy carries an Out of line badge on its row, with a flag that names the fields that differ and a next action. It ranks, within the page of buys returned, above buys that are only waiting on you, and a buy with a budget, rate or flight difference ranks first. The flag is a warning, not a failure: it asks you to look and does not say the buy has failed. A buy that is in line, or not comparable, has no badge on its row. Open the row to see the Agreed terms panel at the top of its detail, above pace and the buyer’s goal. It states whether the buy is in line, out of line or not comparable. For an out-of-line buy it lists each difference as Agreed beside Your ad server reports, with budget, rate and flight differences marked Financial and listed first, and when each was first seen. Fields that could not be compared are listed under Not comparable with the reason. The panel shows the result the list returned when it loaded. Use Refresh to load the latest result.

Read it from an agent

For a seller on the beta, search and get with kind: "media_buy" return contractConformance on each buy. search returns the buy-level status and each source’s status, differences and not-compared fields. get returns the same, beside each leg of the buy’s timeline.
A leg returns its first 25 open differences, money first, and its first 50 fields that could not be compared. differencesTotal and notComparedTotal give the full counts, so a leg with more than that tells you how many were left out.
  • Manage ads covers the seller workflows around the Media Buys page.
  • Media buy lifecycle explains the statuses a buy moves through, which are separate from whether it is in line with the agreed terms.