SautiDesk API
Plan

Book a SautiDesk plan downgrade

PUT
/v1/desk/billing/plan

Books a move to a cheaper plan for the 1st of next month. The current plan runs to the end of the month, nothing is refunded and nothing is charged for the move. Send the active plan to undo a move that is booked. It is refused while the workspace is over the cheaper plan's limits, and with 409 plan.change_disabled while the server has plan changes switched off.

Requires: desk.admin scope, workspace owner or admin.

Authorization

bearerAuth
AuthorizationBearer <token>

A SautiDesk API key. An owner or admin makes it under Settings in SautiDesk for a named person and picks the scopes. The key is shown once. Send it as Authorization: Bearer <key>. It acts as that person and as nobody else.

In: header

Request Body

application/json

Response

OK

Example

{}
curl -X PUT "https://api.sautidesk.com/v1/desk/billing/plan" \  -H "Content-Type: application/json" \  -d '{    "plan": "basic"  }'

The plan: read it, preview a change, upgrade, move down

Read the plan first. Get the plan lists every plan with its price per person a month (net, in the wallet's currency), what it includes and its limits. It says which plan the workspace is on (current_plan), how many people are billed, the monthly charge, the next charge date and the wallet balance. These calls need the desk.admin scope, so only the key of an owner or an admin can use them.

Preview before you change anything. Preview a plan change takes a plan code and changes nothing. For an upgrade it returns the monthly total and what is charged for the rest of this month. For a move down it returns the day the move starts and whether the workspace fits the cheaper plan's limits. Preview an upgrade does the same for an upgrade, in whole currency units.

Upgrade the plan switches the plan at once, and the wallet is then charged by the seat billing run: the rest of this month pro-rated, then every month. A person who already paid for a seat this month pays only the difference to the new plan for the days that are left, and everyone else pays the new price pro-rated from today. Where a plan bills the owner's own seat, the owner is counted too: the preview's owner_free says whether it does.

Book a plan change moves the workspace to a cheaper plan on the 1st. The plan it is on keeps running to the end of the month, nothing is refunded and nothing is charged for the move. Send an Idempotency-Key so a retry books it once. Send the active plan's code to undo a move that is booked, until the day it starts. The workspace has to fit the cheaper plan's limits first, otherwise the answer is a 409 that names what to reduce. While plan changes are switched off on the server the answer is 409 plan.change_disabled, and changes_enabled in Get the plan says so.

Top-ups, saved cards and the statement are not part of the API: they stay in the SautiDesk console. The MCP server has the same four plan tools: desk_get_plan, desk_preview_plan_change, desk_upgrade_plan and desk_book_plan_change. They need desk.admin, and an assistant should confirm the plan and the amount with you before it upgrades.

Read the plan and see what is on offer
const res = await fetch("https://api.sautidesk.com/v1/desk/billing/plan", {
  headers: { Authorization: `Bearer ${process.env.SAUTIDESK_KEY}` },
});
const plan = await res.json();
console.log(plan.current_plan_name, plan.seats, plan.monthly_net_minor);
for (const p of plan.plans) console.log(p.id, p.name, p.net_minor, p.action);
Preview an upgrade, then upgrade
const headers = {
  Authorization: `Bearer ${process.env.SAUTIDESK_KEY}`,
  "Content-Type": "application/json",
};
const preview = await fetch("https://api.sautidesk.com/v1/desk/billing/plan/preview", {
  method: "POST",
  headers,
  body: JSON.stringify({ plan: "pro" }),
}).then((r) => r.json());
console.log(preview.monthly_net_minor, preview.first_charge_net_minor);

// Only after the person has seen the amount:
const res = await fetch("https://api.sautidesk.com/v1/desk/billing/plan", {
  method: "POST",
  headers,
  body: JSON.stringify({ plan: "pro" }),
});
console.log(await res.json());
Book a move to Basic for the 1st
const res = await fetch("https://api.sautidesk.com/v1/desk/billing/plan", {
  method: "PUT",
  headers: {
    Authorization: `Bearer ${process.env.SAUTIDESK_KEY}`,
    "Content-Type": "application/json",
    "Idempotency-Key": crypto.randomUUID(),
  },
  body: JSON.stringify({ plan: "basic" }),
});
const out = await res.json();
console.log(out.scheduled_plan, out.scheduled_at);