Orders, payments, cancellations and upgrades via AI

An AI assistant connected to your account through MCP (https://api.app.blackbox.md/mcp) can place orders, pay for them from your balance, cancel them and upgrade servers. You give it access with a token created on blackbox.md, under “Contul meu” (My account) → “Token-uri API” (API tokens) (blackbox.md/account/api-tokens). You see the results under “Contul meu” → “Comenzi” (Orders) and “Sold” (Balance).

Available to: the holder of a blackbox.md account, through an API token with the “Plasează și modifică comenzi în numele meu” (Place and change orders on my behalf) permission (orders:write).

The blackbox.md website is available in Romanian and Russian; this article quotes the Romanian labels with their English meaning.

To see your servers, orders and balance, the assistant also needs the “Citește lista și statusul serverelor mele” (Read the list and status of my servers) and “Citește soldul, facturile și comenzile” (Read the balance, invoices and orders) permissions. They are checked by default when you create a token.

How your money is protected

Important If you have allowed tools to run automatically in your AI client, the client no longer asks you anything. The assistant is instructed to ask for your confirmation before it spends money or cancels an order, but BLACKBOX can't enforce this question. Keep manual approval for create_order, pay_order, cancel_order and resize_server.

About permissions: Token permissions (scopes). Creating the token: API tokens: creating, copying and revoking.

How to place an order

1. Ask the assistant for a quote, and tell it explicitly to wait for your confirmation.
2. The assistant reads the catalog with list_vm_plans and calls create_order without confirmation. It shows you the total in MDL. Nothing is created yet.
3. Check the plan, the operating system, the SSH keys and the total.
4. Confirm. The assistant repeats the call with the same details and confirm=true.
5. The order appears in “Comenzi” (Orders) with the status “Nou” (New) and a BBX-… number. You receive the usual email “Am primit solicitarea dumneavoastră — BBX-…” (We have received your request — BBX-…); next to “Mesaj:” (Message:), it reads Created via MCP (AI agent) on behalf of the customer.

No money has been deducted. Pay for the order through the assistant (next section) or on the website, with “Achită comanda” (Pay for the order).

Tip A phrasing that works well: “Prepare a quote for … and wait for my confirmation before paying.” For example:

Prepare a quote for a vm-iops1-m server with Ubuntu 24.04 and wait for my confirmation before placing and paying for the order.

What you can include in the order:

Limit: at most 20 create_order calls per hour, including quotes.

How to pay for the order from your balance

pay_order pays from your balance for an order with the status “Nou” (New), whether the assistant created it or you placed it on the website.

1. Check that your balance covers the total: on the “Sold” (Balance) page, or ask the assistant (the get_balance tool). If it isn't enough, top up your balance on the website: Topping up your balance.
2. Ask the assistant to pay for order BBX-…. It sends the order's current total; if the price has changed, the payment stops with price_changed, and the assistant must show you the new total.
3. After payment:
   • the order moves to “În lucru” (In progress);
   • in “Sold” → “Istoricul operațiunilor” (Transaction history), “Comandă BBX-…” (Order BBX-…) appears with a minus sign;
   • in “Facturi” (Invoices), the invoice BBX-… appears with the status “Achitată” (Paid), and you receive the email “Plată confirmată — BBX-…” (Payment confirmed — BBX-…);
   • VPS plans: the server is created automatically, usually within a few minutes after the payment is confirmed; then you receive “Serverul dvs. este gata — BBX-…” (Your server is ready — BBX-…);
   • dedicated servers: the server is prepared manually by the team; we will contact you.

Limit: 10 pay_order calls per minute. Other details: Paying for an order from your balance.

If the call seems to have timed out

Server creation starts right after payment, so the pay_order call can take a while. If your AI client reports a timeout or a connection error, don't ask for a new payment. Ask the assistant to check the order with list_orders, or open “Comenzi” (Orders): the status “În lucru” means the payment went through. A second payment for the same order is rejected anyway (not_payable).

How to cancel an order

The assistant cancels orders with the status “Nou” (New) or “În lucru” (In progress), under the same rules as the “Anulează comanda” (Cancel the order) button on the website: Order cancellation and refunds.

1. Ask the assistant to check what would happen if you canceled order BBX-…. It calls cancel_order without confirmation and shows you the preview:
   • the amount that goes back to your balance, in MDL;
   • the rule applied: full (full), prorated (prorated) or no refund (none);
   • whether a server will be deleted, and its IP address.
2. Read the preview. If you want to go ahead, confirm explicitly.
3. The assistant repeats the call with confirm=true. The order moves to the status “Anulat” (Canceled), and you receive the email “Comandă anulată — BBX-…” (Order canceled — BBX-…). If an amount is refunded, it goes to your balance (“Rambursare comandă BBX-…” (Order refund BBX-…) in “Istoricul operațiunilor” (Transaction history)).

Irreversible If the order has a server, the server is deleted immediately when you confirm, together with all the data on it. Unlike “Terminate” in the app.blackbox.md panel, there is no 24-hour grace period, and the deletion can't be stopped.

• Refunds go only to your balance. To get the money back on your card, write to support@blackbox.md.
• While the server is being created, the order can't be canceled (provisioning_in_progress). Come back in a few minutes.
• Limit: 5 cancel_order calls in 5 minutes, including previews.

How to upgrade a server

The assistant moves a server to a larger plan in the same family and pays from your balance, just like the “Upgrade” button in the panel: Server upgrade: moving to a larger plan.

1. Ask for the server's upgrade options. The assistant calls get_server_resize_options and shows you the larger plans in the same family, the new monthly price and the amount that would be deducted now (prorated to the days left in the current 30-day cycle).
2. Choose the plan. The assistant calls resize_server without confirmation and shows you the preview: the new plan, the amount to be deducted and your balance. If your balance isn't enough, the insufficient_balance error appears already at this step.
3. Confirm. The assistant repeats the call with confirm=true: the amount is deducted from your balance (“Upgrade server” (Server upgrade) in your balance history), and the server restarts on the new plan. The downtime lasts a few minutes; your IP address and data are kept.
4. The assistant only learns that the upgrade has started. You see the result in the email “Serverul dvs. a fost actualizat — BBX-…” (Your server has been updated — BBX-…) and in the panel, where the “Spec” field on the server card shows the new resources.

• An upgrade works only upward: the server can't be made smaller and can't move to another family.
• It works for servers ordered from your account on the VPS plans from the catalog (vm-…). On the “VPS hosting” plans and on older plans that are no longer sold, you get not_upgradeable_plan, and dedicated servers can't be enlarged through the assistant: in both cases, write to us.
• If the upgrade fails, the amount goes back to your balance automatically (“Anulare upgrade server” (Server upgrade cancellation)).
• Limit: 3 resize_server calls in 10 minutes, including previews.

Common errors

If the assistant says that the infrastructure service is temporarily unavailable, try again later. All codes and limits: MCP limits and error codes.

Frequently asked questions

Can the assistant spend money without my knowledge? Only if the token has the “Plasează și modifică comenzi în numele meu” (Place and change orders on my behalf) permission and your AI client doesn't ask for your approval. Even then, it pays only from your balance and only amounts calculated by BLACKBOX: an order's current total or the difference for an upgrade. For an assistant that only reads data, create a token without this permission.

Can I pay by card for an order the assistant created? Yes. The order appears in “Comenzi” (Orders) with the status “Nou” (New). Click “Achită comanda” (Pay for the order) and pay as usual.

Can the assistant top up my balance or pay invoices issued by the team? No. Top-ups are made only on the website, and the MCP tools don't pay invoices. The full list of tools: List of MCP tools.

I want to delete a server but keep the option to change my mind. What should I do? Use “Terminate” in the app.blackbox.md panel. It has a 24-hour grace period, but it doesn't refund anything: Permanently deleting a server. Through the assistant, canceling the order deletes the server immediately.