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 innotCompared 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 intotal_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 samecurrencyfor 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.
- 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, underext.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.
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, withfieldPath
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_buywithpaused: trueto 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 withsearch(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:
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
resumeDueistruewhen 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
- Check what changed. Read
agreedandreportedfor each difference, money first. Your ad server’s change history shows who made it. - If the change was not intended, put the line back in your ad server. The next read of your ad server closes the difference.
- 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.
- 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.
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.
differencesTotal and notComparedTotal give the
full counts, so a leg with more than that tells you how many were left out.
Related
- 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.