Managed account pricing and payer change

A managed account is a normal account with its own plan, and your account pays for it until its client takes over the payment. There is no separate price list for managed accounts: your subscription uses the same prices as the plans and add-ons of any account, and what changes is who pays. This guide covers what you pay, how you choose and change the plan, when we charge you, what happens when the payment passes to the client, and what you can and cannot do while your account is in trial or has a payment problem.

The operations of this guide that you run as the provider of managed accounts need the privileged scope accounts:read or accounts:write, which * does not cover: managed accounts explains how they are granted and checked. {account} is the id of the managed account, the one that GET /v1/accounts lists, except in provisioning-usage, where it is your own account.

What you pay

For every live managed account whose management is in force and whose client has not taken over the payment, your account pays three things, always monthly. All of them go on one subscription of your account, managed-accounts, which has one item per price and the quantity of all your managed accounts added up, never one item per account.

What decides the amount:

• Your access level does not matter. An account at none, view or operate costs the same: the level changes what your credentials reach, not what you pay.
• The plan is the account's own. It is stored on the managed account and its tax IDs follow it. Your own plan never changes it, as your account in trial or with a payment problem explains.
• The quantities come from the real state of each account. We recompute them and always send them to the payment provider as absolute numbers, so repeating a call never charges twice.
• Amounts are taxable base. The plan preview returns the base, without VAT.

What does not cost you anything:

• A test managed account, created with a fact_test_ key. It never reaches the payment provider: see test managed accounts.
• An account on enterprise. It is billed by contract, outside your subscription.
• An account that is not operable, because its titular tax ID is not active, for example when your billing is blocked.
• An account whose management ended, or whose client took over the payment.

Choose the plan

You choose the plan when you provision the account: plan is required in POST /v1/accounts, and there is no interval to choose.

An account on enterprise is agreed with us by contract, and it is billed by contract, outside your subscription. You cannot ask for it when you provision, and once an account is under contract you cannot change its plan with the plan operations either: they answer the same 422 managed_account_plan_not_self_serve.

When you are charged

We charge your account when something you pay for changes, always on the same subscription. There is no checkout: if your account has no payment method, the operation that would charge you is rejected first.

A daily reconciliation keeps the quantities aligned with the real accounts, without proration.

Change the plan

You can change the plan of a managed account you pay at any time, also after the client claimed it, as long as you keep paying. Besides the scope, both operations need your access level on the account to be operate. Preview the change first, then make it.

The MCP tools need an API key: the OAuth channel does not reach accounts:*. The change is irreversible, so it needs an Idempotency-Key (idempotency_key in the tool), and a call without it answers 422 idempotency_key_required.

Both operations ask for the same things:

• The account is yours and you pay it. It must be a managed account provisioned by your account, with its management in force and in the environment of the key. Your own account, another one, one whose management ended and one whose client took over the payment all answer the same 404 account_not_found.
• Your level is operate. With view or none the answer is 403 forbidden_action and nothing changes.
• The plan is emprendedor, empresario or integral. enterprise answers 422 managed_account_plan_not_self_serve.

Preview the change

curl -G https://api.factuarea.com/v1/accounts/$MANAGED_ACCOUNT_ID/plan/preview \
  -H "Authorization: Bearer $FACTUAREA_API_KEY" \
  --data-urlencode "plan=empresario"

{
  "data": {
    "object": "managed_account_plan_change_preview",
    "from_plan": "emprendedor",
    "to_plan": "empresario",
    "effective": "immediate",
    "effective_at": null,
    "prorated_amount_cents": 1250,
    "next_invoice_amount_cents": 3500,
    "currency": "EUR"
  }
}

The amounts are integer cents of taxable base, without VAT. Unlike the euros as strings of GET …/billing, the plan preview keeps cents, as the field names say. The amounts in the examples are only illustrative: ask the preview for the real ones instead of hard-coding them.

Make the change

curl -X PATCH https://api.factuarea.com/v1/accounts/$MANAGED_ACCOUNT_ID/plan \
  -H "Authorization: Bearer $FACTUAREA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{ "plan": "emprendedor" }'

The answer is 200 with the managed account. A lowering shows the target in pending_plan and keeps the current plan in plan:

{
  "data": {
    "id": "0199a1f0-1c22-7a10-b111-6a6b6c6d6e6f",
    "object": "managed_account",
    "external_ref": "cliente-0042",
    "status": "claimed",
    "environment": "live",
    "plan": "empresario",
    "pending_plan": "emprendedor",
    "billing_interval": "monthly",
    "access_level": "operate",
    "display_name": "Talleres García",
    "language": "es",
    "companies": [
      {
        "id": "0199a1f0-1c22-7a10-b111-7a7b7c7d7e7f",
        "tax_id": "B12345674",
        "name": "Talleres García SL"
      }
    ],
    "claimed": true,
    "claimed_at": "2026-09-29T08:00:00+00:00",
    "management": {
      "status": "active",
      "ended_at": null
    },
    "paid_by_provider": true,
    "created_at": "2026-09-27T09:00:00+00:00"
  }
}

• Raising (emprendedor to empresario). It takes effect and is charged at once, prorated, in one update of your subscription, with one invoice for the credit and the charge. The answer already shows the new plan.
• Lowering (empresario to emprendedor). It stays pending until the end of the period of your managed-accounts subscription. Nothing of the current period is credited, but the renewal invoice already carries the new plan and no additional tax IDs, because emprendedor does not allow them. When the change takes effect, the account's additional tax IDs are deactivated, never its titular company.
• Changing your mind. A new request replaces a pending one, and asking for the plan the account already has withdraws it. If the client takes over the payment first, the pending lowering is discarded and the client continues on the current plan.
• A failed charge. If the payment provider rejects a raise, the plan is not written and nothing stays charged. The answer still shows the previous plan, so read plan and pending_plan in it and, if they did not change, repeat the change with a new Idempotency-Key.
• Nothing to charge. A test account, or one that is not charged to you because its payer is blocked, changes at once with no charge, and its preview shows both amounts at 0.

Read what you pay

GET /v1/accounts/{account}/provisioning-usage, with your own account.id as {account}, counts what you pay. managed_accounts_by_plan has your live accounts of each plan, where the enterprise ones are not in your subscription, and provider_paid_additional_nifs and provider_paid_employee_seats have the additional tax IDs and employee seats you pay on top of their plan. It needs accounts:read, and managed accounts describes the whole answer.

The API returns no amount per account. The client accounts list of the app shows the monthly amount of each one, and the preview of a bulk import returns the monthly amount and the proration of every row and of the whole file before you confirm it.

Change of payer

Your account pays until the client takes the payment over. The payer changes in the ways below, and in all of them the client continues with the same plan and the same price: nothing is repriced and there is no new plan to choose.

This is how the payment passes from you to the client, so that nothing is charged twice and there is no gap:

• The client starts paying when the period you already paid ends. We create its subscriptions first, verify them, and only then lower yours. The client's first charge falls when that period ends, never before. If that date has already passed, the first charge is immediate.
• You are not credited, and you do not pay twice. Your next invoice goes out without the account's units. Nothing is credited for the rest of the period, because the client starts paying when it ends.
• A failure never leaves the account without a payer. We retry, and if the payment cannot be completed we undo what we created and you keep paying.
• The client needs a payment method on its own account. The app asks for it before the client takes the payment over, and nothing changes until it is added.
• A pending lowering is discarded. The client continues on the plan the account has.

Follow it from your side

paid_by_provider tells you who pays while the management is in force. To notice the take-over, look for these signs:

• GET /v1/accounts/{account} answers 404 account_not_found, and the account is no longer in GET /v1/accounts.
• GET /v1/me lists the account in client_accounts as a granted access, with origin: "granted" and paid_by_provider: false:

{
  "id": "0199a1f0-1c22-7a10-b111-6a6b6c6d6e6f",
  "name": "Talleres García",
  "origin": "granted",
  "access_level": "operate",
  "status": "active",
  "paid_by_provider": false,
  "environment": "live"
}

When the management ends, in contrast, we do publish account.management_ended to your account webhook endpoints.

Enterprise by contract

An account under an enterprise contract has no plan to continue on until we set one. If you end the management, or its client tries to take over the payment, before we have set it, the answer is 422 enterprise_contract_transition_required: nothing changes and the management stays in force. That also holds before the claim, because the client will need the same plan when it claims the account. Contact us, we set the plan the account continues on, and you repeat the operation. If that plan is emprendedor, the account's additional tax IDs are deactivated, because that plan does not allow them.

End the management

DELETE /v1/accounts/{account}/management ends the management, as managed accounts explains. What happens to the payment depends on whether the client had claimed the account: see the table in change of payer. It needs an Idempotency-Key, and the MCP tool is end_account_management. The answer is 200 with the account and management.status: "ended", and from the next request your account loses access to it.

Your account in trial or with a payment problem

Provisioning a live managed account checks three things, in this order, before it creates or charges anything:

1. In trial. A live managed account is charged from the first day, so an account in its trial can only create test managed accounts. A live one answers 422 managed_account_provider_in_trial. Your account is in trial during its trial window with no subscription, or while its plan subscription is in its trial period. When the trial ends and you start paying, the next live provisioning goes on to the next check. A fact_test_ key creates test accounts during the trial, at no charge.
2. The limit. At your cap of live managed accounts, the answer is 422 managed_accounts_limit_reached. Test accounts do not count: limit and remaining in provisioning-usage tell you where you are.
3. The payment method. A live account needs a payment method on your account. Without one, the answer is 402 payment_method_required. Register one in the billing portal of the app and repeat the call.

The same order applies when you reactivate, by external_ref, a management that ended before the claim.

If your account stops paying, the managed accounts you pay stop being operable. Nothing is deleted. It happens when your own plan goes unpaid, when it lapses with no active subscription, or when your managed-accounts subscription ends unpaid or canceled after the payment retries. A failed renewal does not block at once: the usual retries run first. The effect is:

• All the tax IDs of those accounts become inactive, with suspension_reason: "payer_blocked", as the state of a tax ID describes. Calls on them answer 403 company_inactive.
• They resume by themselves when your billing is up to date again, or when the client takes over the payment. Only the tax IDs the block suspended resume: one the account deactivated itself stays as it was.
• Test managed accounts are not affected.

Otherwise your own plan is independent of your managed accounts: raising it, lowering it or scheduling its cancellation changes nothing on them, and their subscription, managed-accounts, is not touched.

What the client cannot buy while you pay

While you pay and the management is in force, the client does not buy anything on its own account, because what it would buy is on your bill. Its credentials, and its people in the app and in MCP, get 403 billing_managed_by_provider on these operations, with no charge and no change. In this table {account} is the client's own account:

Reading the billing is not an error: GET /v1/companies/{company}/billing of a tax ID of such an account answers managed: true with no gestoria_seats and no payment_method, so what you pay never reaches the client's keys.

On your side, you do not buy employee seats for a managed account: the quantity follows its active employees. The additional tax IDs are added by your account, with the {account} of the managed account and operate level, and the charge goes to your subscription: see additional tax IDs. When the client takes over the payment, the account pays for itself and its owner and admins can use those operations again.

Errors

Related