Referência da API · Partners

Transições de faturamento

partners · billing_transitions · 5 operações

GET/v1/partners/billing-transitionsList billing transition requests GET/v1/partners/billing-transitions/{request_id}Get one billing transition request POST/v1/partners/billing-transitionsAsk an account to move its billing to the agency POST/v1/partners/billing-transitions/{request_id}/rejectReject a billing transition request (the account)POST/v1/partners/billing-transitions/{request_id}/cancelCancel a pending billing transition request

GET/v1/partners/billing-transitions

List billing transition requests

partners.billing_transitions.list

LeituraIdempotenteDesde 2026-11-01

Lists the requests to move an account's billing to the agency (direction to_parent_pays: from paying its own subscription, self_pays, to being paid by the workspace, parent_pays), newest first, paginated by cursor (limit up to 200). From a workspace, the requests it sent to its accounts; from an account, the ones it received. status: active (default: pending and scheduled, what the app shows), all, or one of pending, scheduled, completed, cancelled, rejected. Each request: the workspace and the account (id and name), who requested it and when, status, scheduled_for (when a scheduled one takes effect: the end of the account's paid period), and who accepted, rejected or cancelled it and when. Owners and admins only.

Escopo: partners:read
Permissão: Ver o módulo · Só owner, admin
Tool do MCP: partners_billing_transitions_listNa superfície completa; na compacta, mb_execute_operation com id: "partners.billing_transitions.list".

Custo declarado: até 202 leituras e 0 escritas por chamada (contam na cota diária).

Parâmetros

limitintegerqueryopcional

How many items this page brings at most (see the maximum and the default in the schema).

Padrão: 50

cursorstringqueryopcional

The next_cursor of the previous page, exactly as it came (only for the same list and filters); without it, the first page.

statusenumqueryopcional

active (pending and scheduled, the default: what the app shows), all, or one status.

Valores: active, all, pending, scheduled, completed, cancelled, rejected · Padrão: "active"

Resposta

dataarray<object>

has_moreboolean

next_cursorstring

Erros

role_required invalid_input unknown_field authentication_required scope_insufficient module_access_denied operation_not_found rate_limited quota_exceeded

Exemplo

curl "https://api.mb-suite.com/v1/partners/billing-transitions" \
  -H "Authorization: Bearer $MB_API_KEY"

Testar com a sua API key de teste

Com uma API key de teste o pedido vai sempre para a sua organização de prática: dados de exemplo que você pode reiniciar.

curl "https://api.mb-suite.com/v1/partners/billing-transitions" \
  -H "Authorization: Bearer $MB_TEST_KEY"

GET/v1/partners/billing-transitions/{request_id}

Get one billing transition request

partners.billing_transitions.get

LeituraIdempotenteDesde 2026-11-01

Returns one billing transition request that involves this organization (as the requesting workspace or as the account), with the same fields as partners.billing_transitions.list. Any other organization gets billing_transition_not_found. Owners and admins only.

Escopo: partners:read
Permissão: Ver o módulo · Só owner, admin
Tool do MCP: partners_billing_transitions_getNa superfície completa; na compacta, mb_execute_operation com id: "partners.billing_transitions.get".

Custo declarado: até 1 leituras e 0 escritas por chamada (contam na cota diária).

Parâmetros

request_idstringrotaobrigatório

The billing change request id (partners.billing_transitions.list).

Resposta

idstring

statusenum

Valores: pending, accepted, scheduled, completed, cancelled, rejected

direction"to_parent_pays"

parent_org_idstring

parent_org_namestring

child_org_idstring

child_org_namestring

requested_bystring

requested_by_namestring

created_atnumber

scheduled_fornumber | null

accepted_atnumber | null

accepted_bystring | null

completed_atnumber | null

rejected_atnumber | null

rejected_bystring | null

rejected_by_namestring | null

cancelled_atnumber | null

cancelled_bystring | null

cancelled_by_namestring | null

Erros

billing_transition_not_found role_required invalid_input unknown_field authentication_required scope_insufficient module_access_denied operation_not_found rate_limited quota_exceeded

Exemplo

curl "https://api.mb-suite.com/v1/partners/billing-transitions/{request_id}" \
  -H "Authorization: Bearer $MB_API_KEY"

Testar com a sua API key de teste

Com uma API key de teste o pedido vai sempre para a sua organização de prática: dados de exemplo que você pode reiniciar.

curl "https://api.mb-suite.com/v1/partners/billing-transitions/{request_id}" \
  -H "Authorization: Bearer $MB_TEST_KEY"

POST/v1/partners/billing-transitions

Ask an account to move its billing to the agency

partners.billing_transitions.request

EscritaDesde 2026-11-01

From a workspace, asks one of its accounts that pays its own subscription (billing mode self_pays; account_id, or child_org_id) to let the agency pay for it (parent_pays). It changes nothing yet: the account's owners and admins get an email (Amazon SES) and accept or reject it in MB Suite. If they accept, an account on a trial (or without a subscription) moves at once; one with an active subscription moves when its paid period ends (partners.billing_transition.scheduled, then .completed). Errors: partners_workspace_only, partner_account_not_found (not an account of this workspace), billing_transition_requires_self_pays (409), billing_transition_exists (409, one pending or scheduled already; details.request_id), billing_transition_account_past_due (409: the account must settle its debt first). A direct owner or admin of the workspace. It emails the account: confirm with the person first. Returns the request.

Instruções para agentes

Tell the person the account's owners and admins were emailed and must accept the request in MB Suite; nothing changes in billing until they do.

Pede confirmação: primeiro dry_run: true (prévia e confirm_token, válido por 10 minutos e por uma única execução), depois o mesmo corpo com confirm_token. Em algumas poucas, só com certos dados: a descrição diz quando. Por que e como: Prévia e confirmação.

Escopo: partners:write
Permissão: Editar no módulo · Só owner, admin
Tool do MCP: partners_billing_transitions_requestNa superfície completa; na compacta, mb_execute_operation com id: "partners.billing_transitions.request".
Eventos que pode emitir: partners.billing_transition.requested

Custo declarado: até 2 leituras e 1 escritas por chamada (contam na cota diária). Usa uma plataforma externa (ses): conta na cota de operações externas.

Parâmetros

account_idstringcorpoopcional

The Account (of this workspace, paying for itself) to move to the workspace's billing (platform.orgs.list); child_org_id is accepted too.

child_org_idstringcorpoopcional

Same as account_id.

Resposta

request_idstring

requestobject

Erros

confirmation_required role_required external_rejected external_unavailable external_rate_limited external_outcome_unknown sandbox_external_unavailable invalid_input unknown_field authentication_required scope_insufficient crm_action_denied idempotency_key_reused rate_limited quota_exceeded

Exemplo

curl -X POST "https://api.mb-suite.com/v1/partners/billing-transitions" \
  -H "Authorization: Bearer $MB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "dry_run": true
}'

Testar com a sua API key de teste

Com uma API key de teste o pedido vai sempre para a sua organização de prática: dados de exemplo que você pode reiniciar. Na prática esta operação não é simulada (usa outra plataforma): responde 409 sandbox_external_unavailable.

POST/v1/partners/billing-transitions/{request_id}/reject

Reject a billing transition request (the account)

partners.billing_transitions.reject

EscritaDesde 2026-11-01

From the account, rejects a pending request of its agency to take over its billing: the account keeps paying its own subscription and the workspace's owners and admins get an email (Amazon SES). Only a direct owner or admin of the account answers for it: a workspace (billing_transition_account_only) or an agency user acting on the account (403 role_required, details.scope direct) cannot. Only pending requests (billing_transition_not_pending, 409). Accepting is done in the MB Suite app (it changes the account's subscription in Stripe). Returns the request.

Escopo: partners:write
Permissão: Editar no módulo · Só owner, admin
Tool do MCP: partners_billing_transitions_rejectNa superfície completa; na compacta, mb_execute_operation com id: "partners.billing_transitions.reject".
Eventos que pode emitir: partners.billing_transition.rejected

Custo declarado: até 2 leituras e 1 escritas por chamada (contam na cota diária). Usa uma plataforma externa (ses): conta na cota de operações externas.

Parâmetros

request_idstringrotaobrigatório

The billing change request id (partners.billing_transitions.list).

Resposta

requestobject

Erros

billing_transition_not_found confirmation_required role_required external_rejected external_unavailable external_rate_limited external_outcome_unknown sandbox_external_unavailable invalid_input unknown_field authentication_required scope_insufficient crm_action_denied idempotency_key_reused rate_limited quota_exceeded

Exemplo

curl -X POST "https://api.mb-suite.com/v1/partners/billing-transitions/{request_id}/reject" \
  -H "Authorization: Bearer $MB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "dry_run": true
}'

Testar com a sua API key de teste

POST/v1/partners/billing-transitions/{request_id}/cancel

Cancel a pending billing transition request

partners.billing_transitions.cancel

EscritaDesde 2026-11-01

Cancels a pending billing transition request, from either side (a direct owner or admin of the workspace or of the account; an agency owner or admin acting on the account counts as the workspace): nothing changes in billing and the other side's owners and admins get an email (Amazon SES). A request already scheduled (accepted, waiting for the end of the account's paid period) is cancelled only in the MB Suite app, because it re-enables the renewal of the account's subscription in Stripe (billing_transition_scheduled_app_only, 409). Completed, rejected or cancelled requests: billing_transition_not_cancellable (409). Returns the request.

Escopo: partners:write
Permissão: Editar no módulo · Só owner, admin
Tool do MCP: partners_billing_transitions_cancelNa superfície completa; na compacta, mb_execute_operation com id: "partners.billing_transitions.cancel".
Eventos que pode emitir: partners.billing_transition.cancelled

Custo declarado: até 3 leituras e 2 escritas por chamada (contam na cota diária). Usa uma plataforma externa (ses): conta na cota de operações externas.

Parâmetros

request_idstringrotaobrigatório

The billing change request id (partners.billing_transitions.list).

Resposta

requestobject

Erros

Exemplo

curl -X POST "https://api.mb-suite.com/v1/partners/billing-transitions/{request_id}/cancel" \
  -H "Authorization: Bearer $MB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "dry_run": true
}'