Menú

Referencia de la API · Media Planner

Carryover

media_planner · carryover · 4 operaciones

GET/v1/media-planner/plans/{plan_id}/carryover/candidatesList the plans whose balance can be carried over POST/v1/media-planner/plans/{plan_id}/carryover/applyApply a carryover to a plan POST/v1/media-planner/plans/{plan_id}/carryover/revertRevert the carryover of a plan POST/v1/media-planner/plans/{plan_id}/carryover/dismissDismiss a carryover candidate

GET/v1/media-planner/plans/{plan_id}/carryover/candidates

List the plans whose balance can be carried over

media_planner.carryover.candidates

LecturaIdempotenteDesde 2026-11-01

For a plan with carryover enabled, lists the finished plans (active or archived, carryover enabled, balance not used by another plan) whose unspent balance it can receive, most recent first: each with its rows' budget, known spend and balance, the balance by currency, and needs_sync when its costs were not synced after it ended (sync it first with media_planner.costs.sync for an exact balance). Between two campaigns-mode plans only shared platforms count, and the receiving plan's carryover_platforms filter applies. Empty when carryover is off for the plan. Requires view access to the Media Planner. With Google Ads, LinkedIn or TikTok, their terms limit it through the API and the MCP: what they do not allow answers 403 platform_terms_restricted, and their records are left out of the response (the permissions guide lists what each platform allows).

Alcance: media_planner:read
Permiso: Ver el módulo
Tool del MCP: media_planner_carryover_candidatesEn la superficie completa; en la compacta, mb_execute_operation con id: "media_planner.carryover.candidates".

Costo declarado: hasta 2000 lecturas y 0 escrituras por llamada (cuentan en el cupo diario).

Parámetros

plan_idstringrutarequerido

Media plan id (from media_planner.plans.list).

Respuesta

candidatesarray<object>

Most recent first.

current_plan_platformsarray<string>

The receiving plan's platforms.

Errores

media_plan_not_found invalid_input unknown_field authentication_required scope_insufficient module_access_denied operation_not_found rate_limited quota_exceeded

Ejemplo

curl "https://api.mb-suite.com/v1/media-planner/plans/{plan_id}/carryover/candidates" \
  -H "Authorization: Bearer $MB_API_KEY"

Probar con tu API key de prueba

Con una API key de prueba el pedido va siempre a tu organización de práctica: datos de ejemplo que puedes reiniciar.

curl "https://api.mb-suite.com/v1/media-planner/plans/{plan_id}/carryover/candidates" \
  -H "Authorization: Bearer $MB_TEST_KEY"

POST/v1/media-planner/plans/{plan_id}/carryover/apply

Apply a carryover to a plan

media_planner.carryover.apply

EscrituraDesde 2026-11-01

Adds a balance to the budget of rows of a plan with carryover enabled and not applied yet. source: { mode: from_plan, source_plan_id } takes the balance of a candidate (media_planner.carryover.candidates) and marks that plan as used, or { mode: manual, note, total_amounts: [{ currency, amount }] } records a balance from elsewhere. allocations: [{ campaign_id, amount }] says how much goes to each row (negative subtracts; rows with 0 are skipped). What is allocated cannot exceed the available balance in any currency (the row's currency, or the plan's): the source plan's balance by currency (balance_by_currency in media_planner.carryover.candidates) or the manual total_amounts, with a 0.5 margin for rounding; more is 400 carryover_over_allocated with details.currencies (currency, allocated, available) and nothing is written. Each row keeps the carryover it received and the change history shows the budget before and after; the plan's totals are recomputed and media_planner.carryover.applied fires. Revert it with media_planner.carryover.revert. Errors: carryover_over_allocated, carryover_allocations_empty, carryover_same_plan (400), media_plan_row_not_found (404), carryover_disabled, carryover_already_applied, carryover_source_consumed (409). Requires full access to the Media Planner.

Alcance: media_planner:write
Permiso: Editar en el módulo
Tool del MCP: media_planner_carryover_applyEn la superficie completa; en la compacta, mb_execute_operation con id: "media_planner.carryover.apply".
Eventos que puede emitir: media_planner.carryover.applied media_planner.campaign.changed

Costo declarado: hasta 1100 lecturas y 503 escrituras por llamada (cuentan en el cupo diario).

Parámetros

plan_idstringrutarequerido

The plan that receives the balance (carryover enabled, not applied yet).

sourceobjectcuerporequerido

Where the balance comes from: { mode: from_plan, source_plan_id } or { mode: manual, note, total_amounts }.

allocationsarray<object>cuerporequerido

How much goes to each row of the plan; per currency, at most the available balance.

Respuesta

applied_amountnumber

What was added to the rows' budgets (the sum of allocations; never more than the balance available).

total_amountnumber

The balance that was available to distribute.

campaign_countnumber

Rows that received an amount.

Errores

media_plan_not_found invalid_input unknown_field authentication_required scope_insufficient crm_action_denied idempotency_key_reused rate_limited quota_exceeded

Ejemplo

curl -X POST "https://api.mb-suite.com/v1/media-planner/plans/{plan_id}/carryover/apply" \
  -H "Authorization: Bearer $MB_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "source": "SOURCE",
  "allocations": []
}'

Probar con tu API key de prueba

Con una API key de prueba el pedido va siempre a tu organización de práctica: datos de ejemplo que puedes reiniciar.

curl -X POST "https://api.mb-suite.com/v1/media-planner/plans/{plan_id}/carryover/apply" \
  -H "Authorization: Bearer $MB_TEST_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "source": "SOURCE",
  "allocations": []
}'

POST/v1/media-planner/plans/{plan_id}/carryover/revert

Revert the carryover of a plan

media_planner.carryover.revert

EscrituraDesde 2026-11-01

Undoes an applied (or dismissed) carryover: each row's budget loses the amount it received (later manual edits are kept), the plan's carryover goes back to pending, and the source plan's balance becomes available again. Recomputes the plan's totals and keeps each change in the history. 409 carryover_nothing_to_revert if there is none. Requires full access to the Media Planner.

Alcance: media_planner:write
Permiso: Editar en el módulo
Tool del MCP: media_planner_carryover_revertEn la superficie completa; en la compacta, mb_execute_operation con id: "media_planner.carryover.revert".
Eventos que puede emitir: media_planner.campaign.changed

Costo declarado: hasta 503 lecturas y 502 escrituras por llamada (cuentan en el cupo diario).

Parámetros

plan_idstringrutarequerido

Media plan id (from media_planner.plans.list).

Respuesta

reverted_countnumber

Rows whose carried-over amount was taken back off their budget.

Errores

media_plan_not_found invalid_input unknown_field authentication_required scope_insufficient crm_action_denied idempotency_key_reused rate_limited quota_exceeded

Ejemplo

curl -X POST "https://api.mb-suite.com/v1/media-planner/plans/{plan_id}/carryover/revert" \
  -H "Authorization: Bearer $MB_API_KEY"

Probar con tu API key de prueba

Con una API key de prueba el pedido va siempre a tu organización de práctica: datos de ejemplo que puedes reiniciar.

curl -X POST "https://api.mb-suite.com/v1/media-planner/plans/{plan_id}/carryover/revert" \
  -H "Authorization: Bearer $MB_TEST_KEY"

POST/v1/media-planner/plans/{plan_id}/carryover/dismiss

Dismiss a carryover candidate

media_planner.carryover.dismiss

EscrituraIdempotenteDesde 2026-11-01

Dismisses the balance of a candidate plan (source_plan_id) for this plan: no budget changes, the plan stops offering it and records the balance that was available (computed now). The source's balance stays free for other plans. media_planner.carryover.revert undoes the dismissal. 409 carryover_already_applied if a carryover is applied (revert it instead). Requires full access to the Media Planner.

Alcance: media_planner:write
Permiso: Editar en el módulo
Tool del MCP: media_planner_carryover_dismissEn la superficie completa; en la compacta, mb_execute_operation con id: "media_planner.carryover.dismiss".

Costo declarado: hasta 503 lecturas y 1 escrituras por llamada (cuentan en el cupo diario).

Parámetros

plan_idstringrutarequerido

Media plan id (from media_planner.plans.list).

source_plan_idstringcuerporequerido

The candidate plan whose balance is dismissed.

Respuesta

oktrue

Always true.

dismissed_balancenumber

The source plan's balance this plan chose not to receive (the sum of its rows' balances), recorded on the plan.

Errores

media_plan_not_found invalid_input unknown_field authentication_required scope_insufficient crm_action_denied idempotency_key_reused rate_limited quota_exceeded

Ejemplo

curl -X POST "https://api.mb-suite.com/v1/media-planner/plans/{plan_id}/carryover/dismiss" \
  -H "Authorization: Bearer $MB_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "source_plan_id": "SOURCE_PLAN_ID"
}'

Probar con tu API key de prueba

Con una API key de prueba el pedido va siempre a tu organización de práctica: datos de ejemplo que puedes reiniciar.

curl -X POST "https://api.mb-suite.com/v1/media-planner/plans/{plan_id}/carryover/dismiss" \
  -H "Authorization: Bearer $MB_TEST_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "source_plan_id": "SOURCE_PLAN_ID"
}'