Payout terms

After this page you can set what a publisher is paid for a call, decide when that payment is earned, cap what a lane can cost you in a day, and explain any figure on a statement from the record the platform kept.

Payout terms say what you owe a publisher for a call. They are set on the lane — one publisher on one campaign — and the resolved amount is recorded on every call as its payout.

The four modes

Two optional limits sit over whichever mode you pick. Never pay less than is a floor and Never pay more than is a ceiling; both are applied after the mode has produced its figure, and a payout is never negative. A floor under a revenue share is how a partner is guaranteed something on a call that booked little, and a ceiling is how a single outlier bid does not blow up a month.

curl -X PUT "https://api.buy3.io/api/tracking/campaigns/6a2d1f0e-8b7c-4c55-a1d3-0e9f8a7b6c5d/publishers/c4e1a2b3-9d8f-4f6e-b5a4-1c2d3e4f5a6b" \
  -H "Authorization: Bearer $BUY3_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "payoutMode": "revshare",
    "revsharePct": 55,
    "minPayoutCents": 1500,
    "bufferSeconds": 60,
    "dedupeWindowSeconds": 86400,
    "dailyPayoutCapCents": 150000,
    "blockWhenCapped": true
  }'

When a call earns

A payout is not owed the moment a call arrives. Two independent things have to be true, and they are two different deals on the same call.

• A call nobody answered never earns a payout, in any mode.
• A call that reached no buyer converts nothing, however long somebody talked on a fallback line.
• On revshare and auction the figure is a share of revenue, so a call that earned no revenue pays nothing — unless the lane sets a floor, which is paid whenever the publisher's own seconds were met.
• A lane that is switched off owes nothing at all. The caller is still routed, because a caller is real, but the call is not one you agreed to buy.

Frozen at the start of the call

The terms in force when a call starts are copied onto the call, and settlement reads that copy. Changing a lane's payout this afternoon affects calls from this afternoon onwards and leaves this morning's exactly as they were — so a publisher's statement never moves after they have seen it.

{
  "routingSnapshot": {
    "context": {
      "payoutTerms": {
        "mode": "revshare",
        "revsharePct": 55,
        "bufferSeconds": 60,
        "minPayoutCents": 1500,
        "maxPayoutCents": null,
        "linkId": "3f2e1d0c-9b8a-4765-8432-10fedcba9876"
      }
    }
  }
}

• The terms are frozen, not an amount. At the moment a call arrives nobody knows which buyer will take it, so a revenue share cannot be a figure yet.
• A call won through real-time bidding is different: the publisher was quoted a firm price, so that amount is frozen and paid on the buyer's threshold.
• A publisher with no lane at all — their number simply points at your campaign — inherits the campaign's own publisher payout, exactly as an untouched lane does.

How the figure is worked out

Settlement runs the same four steps every time, in this order. Knowing them is how you explain any payout on any call.

1. Did it earn at all? The call must have been answered and lasted the lane's Earns after seconds — the buyer's threshold when the lane sets none. If not, the payout is zero and nothing below runs.
2. The mode produces a figure. fixed uses the lane's amount. revshare takes its percentage of the revenue the call booked. auction takes the revenue less the campaign's margin, never below the campaign's minimum margin. inherit uses the campaign's own publisher payout.
3. The floor and the ceiling clamp it. The floor is applied first, then the ceiling, and the result is never negative.
4. An adjustment overrides it. An explicit figure entered by hand wins over everything above, for good, until it is taken back.

Repeat callers

Duplicate window is seconds in which the same caller from this publisher counts as a repeat rather than a new call. 0, the default, means a repeat is never treated as one. It is a lane setting because the same caller ringing twice means different things from different sources, and it is separate from the campaign's own duplicate handling — see Repeat and blocked callers.

Caps, and the payout cap

A lane carries five caps. Each one is 0 for no limit, and each is shown in the console with what it has used: "37 of 200" rather than a number nobody can act on.

Correcting a call

A past call is corrected with an adjustment, never by editing the lane. An adjustment names the call, the figure and a reason, and is recorded as a correction with who made it.

curl -X POST "https://api.buy3.io/api/tracking/calls/0b9f6c1e-52a4-4a0e-9f0a-3d1c7e8b2a11/adjust" \
  -H "Authorization: Bearer $BUY3_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "payoutCents": 2750,
    "reason": "Agreed by email — their buffer was missed by two seconds on a good call"
  }'

An explicit figure wins over the computed one for good, until it is taken back. Sending null for a field removes the correction and lets the books recompute it. The full behaviour is in Conversions and adjustments.

Payout is a record, not a payment

The platform records what each publisher is owed and never moves money to them. You settle the way you already do, using the report builder — group by publisher for the period and read payoutCents. The payout schedule and method on a publisher's account are a note of what you agreed, not an instruction the platform carries out.

Payout is also kept apart from what the platform charges you. Connected minutes are billed to your wallet at your plan's per-minute rate and appear in reports as usage; see pricing and Billing and usage.

A worked example

Northwind Media are on a revenue share of 55 per cent on your Acme Health inbound campaign, with a floor, Earns after 60 seconds and a daily payout cap. Four calls arrive on a Tuesday.

Late in the afternoon the lane fills its daily payout cap. Because Refuse their calls once a cap is full is on, their next ping is a no-bid with code 1014 and the description "Your cap for this campaign is filled". They move their media elsewhere for the evening, and the window reopens at midnight UTC.

Next steps