Cost guards and budget optimization

Give the agent a bounded optimization policy

Cost guards apply to one purchase campaign at a time. The owner approves a maximum acceptable cost per paying customer, a maximum lifetime media spend, and a smaller initial test allocation. Customer cost includes known advertising service/payment fees. The media ceiling excludes fees and cannot exceed the campaign's original spending ceiling. This target is separate from the campaign's advisory target_cac_cents.

A guard is an optional, explicit grant of automatic pause and budget controls. It never launches a new campaign, changes creative, moves money between campaigns, raises the original spending authority, or automatically resumes a paused campaign. Customer cost is a decision target, not a guaranteed financial ceiling: reporting and stopping delivery can lag.

Agent proposes; owner approves

Read GET /api/v1/campaigns/{id}/cost-guard with campaigns:read. Live campaign guards require a live key. A missing guard returns status:not_configured and revision:0.

Use a campaigns:write key to PUT the proposal to the same endpoint:

{
  "expected_revision": 0,
  "policy": {
    "max_customer_cost_cents": 2500,
    "max_media_spend_cents": 50000,
    "test_budget_cents": 10000
  }
}

All amounts are integer USD cents. The example approves a $25 all-in customer-cost target, an initial $100 media test, and a $500 maximum lifetime media allocation. It is not a prediction of performance or a pricing quote. The test allocation must fit within the maximum media spend. An agent's new proposal never overwrites the currently approved guard.

Give the returned approval_url to the owner. In the campaign's Cost guard section, they review the exact pending policy and explicitly authorize its automatic controls. The owner-only API is POST /api/v1/campaigns/{id}/cost-guard/approve:

{
  "expected_revision": 1,
  "policy_hash": "REPLACE_WITH_PENDING_POLICY_HASH",
  "acknowledge_automatic_controls": true
}

For a new campaign, approve the guard before preparing the Meta draft. Approval sets its effective lifetime budget to the initial test allocation, while the original ceiling and funding reservation remain intact. Then prepare the draft, validate checkout/pixel tracking, and obtain the separate campaign launch approval.

For an existing approved campaign, pause it first. If its effective budget exceeds the proposed initial test allocation, lower that budget through the existing controls before approving the guard. The new test allocation must exceed reported spend. Already-prepared, unapproved drafts with a larger budget need a new campaign plan with the guard configured before preparation. A running or unresolved control blocks changes to the policy.

Sandbox policies support proposal and approval, but do not run scheduled/provider optimization. They never invent live purchase evidence.

Tell tracking failure apart from zero purchases

Install checkout receipts and complete the owner-reviewed test purchase. The verified merchant backend also sends a health signal every five minutes, even when no purchases occurred:

POST /api/v1/checkout/health
Authorization: Bearer $MR_CHECKOUT_LIVE_KEY
Content-Type: application/json

{
  "status": "healthy",
  "checked_at": "REPLACE_WITH_CURRENT_ISO_TIMESTAMP",
  "payments_synced_through": "REPLACE_WITH_SUCCESSFUL_SYNC_WATERMARK"
}

Only the dedicated live receipt credential can report health. Agent keys, owner sessions and test receipt keys cannot. Report healthy only after the merchant backend has successfully checked the processor and delivered its payment/refund/dispute updates through the stated watermark. Report broken on a failed synchronization. Do not create a timer that sends healthy without checking the underlying integration.

checked_at must be within the last five minutes, with at most one minute future tolerance. payments_synced_through cannot be later than that check. A changed report needs a strictly newer check timestamp; an identical timestamp/payload is a safe retry. Stale successes cannot overwrite a newer failure. Key rotation invalidates existing health until the new live credential reports again.

Both timestamps must remain within fifteen minutes for the guard to consider checkout healthy. This is a merchant-backend attestation, not independent processor verification. MarketingRouter also checks destination pixel/conversion health and the exact campaign's reviewed test receipt. No recent purchase by itself is not treated as broken tracking.

Daily decisions

The service checks guarded campaigns on a five-minute schedule. Cost-based decisions are recorded at most once per UTC day, with at least twenty hours between observations. Safety checks can pause at any review. An agent can request POST /api/v1/campaigns/{id}/cost-guard/review, but it obeys the same next-check time and cannot accelerate evidence collection or make repeated daily increases.

Evidence	Decision
Tracking unavailable/stale, expired checkout test, unavailable spend, expired/revoked authority or funding hold	Request a protective pause.
Current allocation spent, or a guard budget boundary exceeded	Request a protective pause; no automatic refill or restart.
Fewer than 72 hours, fewer than 10 mature paying customers, or incomplete fee reconciliation	Keep the current bounded test allocation. Do not declare a winner.
At least 72 hours and media spend of at least three times the customer-cost target; cost is above target or there are zero paying customers	Pause and recommend reviewing the creative or offer. If fees are unknown, media cost alone may establish a lower bound above target.
Three consecutive daily observations at or below 80% of target, with at least 10 mature customers per observation and three additional mature customers since the first	Increase this campaign's lifetime allocation by up to 10%, capped by the approved guard ceiling.
Already paused manually	Keep it paused; never auto-resume or scale it.

A mature customer has at least one received live payment at least 48 hours old with positive net revenue, after recorded refunds/disputes. Repeat payments count once per campaign. Recent customers count for the conservative over-target stop check, but do not count as mature scaling evidence. New-customer status is unknown.

Each observation uses campaign-lifetime spend and receipts. The three review timestamps must be 20–28 hours apart; missing/bad observations break the sequence. These observations overlap and are a conservative heuristic, not a statistical significance test, a causal claim, or proof of Meta's learning phase. A plan's customer-cost target cannot ensure outcomes in a small sample.

The initial test can be exhausted before enough evidence arrives. That is a bounded test outcome: pause, review and obtain owner approval for another allocation or creative test. Never silently grant a larger test budget because data is sparse.

Fees and data quality

Scaling requires all-in costs from the economics endpoint, with actual fees reconciled for the exact current media spend. A changed spend invalidates an earlier fee checkpoint. Unknown fees stay unknown and cannot justify scaling. This release does not automatically obtain processor-settled fees; the owner must reconcile them. Third-party attributed purchase counts, browser events and ad-balance top-ups are not substituted for paying customers.

Read the decision and verify the action

GET returns the approved policy, separate pending_policy, authorized_budget_cents, current backend health, stopped_reason, last_checked_at, next_check_at, last_error_code and the latest twenty runs. Each run contains the observed evidence, decision, timestamp and status:

• planned: decision stored; its control may be pending or uncertain.
• applied: the action completed, or a hold was recorded without changing delivery.
• blocked: the action could not be completed. Inspect error_code and the campaign's control history.

HTTP 200 means the review state was returned. It does not mean a requested pause succeeded. Read last_error_code, run status and current provider delivery. The original control body and guard:{run_id} identity are retained across uncertain responses. Never recreate a budget change with another identity to bypass an unresolved result.

New direct budget/resume commands through the normal controls are also checked against the current authorized guard allocation and stop state. Funding and original owner-approval checks remain in force. Pauses and budget reductions remain available. During an unresolved resume, a protective pause can run independently; the unresolved command is retained and must be reconciled before further delivery. A provider outage can prevent confirmation, which remains visible rather than being labeled paused.

Recover after a stop

A stop remains latched. Repair checkout/pixel health or funding, inspect the campaign, and keep it paused. Propose a new policy or explicitly propose the same policy for review. The owner reviews and approves the exact pending hash again, clearing the stop. Then the agent can explicitly resume through the existing revision-checked controls after all readiness checks pass. Guard approval itself never resumes delivery.

To disable a guard, pause the approved campaign and resolve pending commands, then the owner sends DELETE with {"expected_revision":CURRENT_REVISION}. An agent cannot disable it. Disabling leaves the current budget and reserved funds unchanged.

Scheduling and operational bounds

Checks use a leased, authenticated scheduled worker. Concurrent/manual invocations cannot claim the same guard or create another daily decision. Ten enabled live guards across the service are admitted during the initial beta; guard_capacity requires operator scheduling review before expanding. Due work is ordered oldest first, processed in bounded pairs, and errors remain visible in guard status.

Five minutes is a schedule, not a real-time stop SLA. Delayed invocations, observation lag and provider outages can delay pauses; costs may settle after pausing. A severe tracking/backend outage may leave evidence unavailable while the provider continues spending until the pause is confirmed. Monitor overdue next_check_at, old last_checked_at and unsuccessful actions. The approved provider lifetime budget remains the underlying media spending boundary.