Skip to content

API reference

Plan and billing

The company's plan (nothing to pay up to 9 active people, then one price per active person, every module included), the modules and features it switched on or off (AI and API access), emails, storage and AI credits, billing details, invoices and paying them, and promotion codes.

15 actions · base URL https://api.bizisy.com/v1 · generated from the same definitions as the API.

See the plan#

POST/v1/platform/plan.getRead

Returns the company's Bizisy plan: the active people today and the Free limit (free up to 9 active people: limit near at 8, at at 9, over from 10; nothing is ever blocked by it), this month's price so far and next month's estimate, storage (included, extra chosen, the limit and this month's storage line), any promotion, and billing (whether it exists, its status, the first charge date, and whether billing details are needed). Credits (emails, AI credits) are in platform_usage_get; modules (all included) in platform_features_get. Free up to 9 active people, then €1.50 per active person a month, every module included; excluding VAT. Included each month: emails (Free 20, then 10 per active person), storage (Free 1 GB, then 5 GB) and AI credits (1 per document read; Free 20, then 5 per active person). Included amounts reset every month; bought ones carry over and are used after them: 1,000 emails €1; AI credits 100 for €5, 500 for €20, 2,000 for €60; extra storage €1 per GB a month. Owners, admins and HR.

Who can call it
Manage key owner admin hr
MCP tool
platform_plan_get on HR Assistant
Method
POST with a JSON body, or GET with the input as query parameters

Input

No input: send {}.

Returns

11 fields
  • sandboxbooleanrequired

    A developer sandbox: every module on, unlimited credits, never billed.

  • not_billed"demo" | "internal"required

    Set by Bizisy support: the company is never billed (a demo company or one of Bizisy's own); null for every customer company.

  • peopleintegerrequired

    Active people today.

  • free_max_peopleintegerrequired

    Free up to this many active people (9).

  • limit"under" | "near" | "at" | "over"required

    The Free limit: under (≤ 7 active people), near (8), at (9), over (10 or more: €1.50 per active person). Nothing is ever blocked by it.

  • monthstringrequired

    YYYY-MM (UTC): the month billed so far.

  • this_monthobjectrequired

    This month so far (people now), excl. VAT; extra storage is in storage.

    7 fields
    • peopleintegerrequired

      Active people the month is priced on.

    • freebooleanrequired

      Up to 9 active people: nothing is charged.

    • linesobject[]required

      The charged lines: Core for every active person from 10 (none on Free).

      5 fields
      • line"core"required
      • unit_centsintegerrequired

        Per active person per month, excl. VAT.

      • qtyintegerrequired
      • amount_centsintegerrequired

        List amount (unit × qty).

      • discount_centsintegerrequired

        The promotion's discount on this line (0 without one).

    • subtotal_centsintegerrequired

      The charged lines at list price, before the promotion.

    • discount_centsintegerrequired

      The promotion's discount this month (0 without one).

    • total_centsintegerrequired

      Per month, excluding VAT, after the promotion (extra storage is billed on its own line).

    • promotionobject | nullrequired

      The company's promotion as priced this month, or null.

      8 fields
      • codestringrequired
      • labelstringrequired
      • kind"free_months" | "percent"required
      • percentintegerrequired
      • lines"core"[]required
      • appliesbooleanrequired

        It discounts this month.

      • untilstring | nullrequired

        YYYY-MM-DD: the last day it covers; null while it waits for the first paid month.

      • starts"first_paid_month"required

        first_paid_month: it starts with the first month the company is charged.

  • next_monthobjectrequired

    Next month if nothing changes (people now), excl. VAT.

    7 fields
    • peopleintegerrequired

      Active people the month is priced on.

    • freebooleanrequired

      Up to 9 active people: nothing is charged.

    • linesobject[]required

      The charged lines: Core for every active person from 10 (none on Free).

      5 fields
      • line"core"required
      • unit_centsintegerrequired

        Per active person per month, excl. VAT.

      • qtyintegerrequired
      • amount_centsintegerrequired

        List amount (unit × qty).

      • discount_centsintegerrequired

        The promotion's discount on this line (0 without one).

    • subtotal_centsintegerrequired

      The charged lines at list price, before the promotion.

    • discount_centsintegerrequired

      The promotion's discount this month (0 without one).

    • total_centsintegerrequired

      Per month, excluding VAT, after the promotion (extra storage is billed on its own line).

    • promotionobject | nullrequired

      The company's promotion as priced this month, or null.

      8 fields
      • codestringrequired
      • labelstringrequired
      • kind"free_months" | "percent"required
      • percentintegerrequired
      • lines"core"[]required
      • appliesbooleanrequired

        It discounts this month.

      • untilstring | nullrequired

        YYYY-MM-DD: the last day it covers; null while it waits for the first paid month.

      • starts"first_paid_month"required

        first_paid_month: it starts with the first month the company is charged.

  • storageobjectrequired
    6 fields
    • included_gbintegerrequired

      Included: 1 GB on Free, 5 GB from 10 active people.

    • extra_gbintegerrequired

      Extra GB chosen now (€1 per GB a month).

    • limit_gbintegerrequired

      included_gb + extra_gb: uploads past it are refused.

    • month_extra_gbintegerrequired

      The highest extra GB chosen at any point this month: what this month bills.

    • gb_centsintegerrequired
    • month_centsintegerrequired

      This month's storage line: month_extra_gb × €1, excl. VAT.

  • billingobjectrequired
    4 fields
    • existsbooleanrequired

      Billing runs for this company on this server (Settings → Plan & billing shows payment and invoices).

    • statusstring | nullrequired

      platform_billing_get status (free: nothing to set up); null when billing does not exist.

    • first_charge_onstring | nullrequired

      YYYY-MM-DD (a 1st) of the first charge while nothing has been charged yet; null when nothing will be charged or charging has begun.

    • needs_detailsbooleanrequired

      Billing applies (10 or more active people, or extra storage chosen) and there are no billing details yet: the guided billing setup is due.

  • promotionobject | nullrequired

    The company's running promotion (one at a time), or null. this_month and next_month are priced with it.

    11 fields
    • labelstringrequired
    • codestringrequired
    • kind"free_months" | "percent"required
    • percentintegerrequired
    • linesstring[]required
    • monthsinteger | nullrequired

      Months covered from the first paid month (null: until a date).

    • starts"first_paid_month"required

      first_paid_month: not started yet; it starts with the first month the company is charged.

    • ends_onstring | nullrequired

      YYYY-MM-DD, the last day it covers (null while it waits for the first paid month).

    • projected_ends_onstring | nullrequired

      When it would end if this month were the first paid one (for "until about").

    • notestring | nullrequired

      What the company agreed to (Founding Customers: an honest review and a case study).

    • redeemed_onstringrequired

Errors

validation_failed unauthenticated forbidden not_found rate_limited internal

curl
curl https://api.bizisy.com/v1/platform/plan.get \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
Response
{
  "data": {
    "sandbox": false,
    "not_billed": null,
    "people": 23,
    "free_max_people": 9,
    "limit": "over",
    "month": "2026-11",
    "this_month": {
      "people": 23,
      "free": false,
      "lines": [
        {
          "line": "core",
          "unit_cents": 150,
          "qty": 23,
          "amount_cents": 3450,
          "discount_cents": 0
        }
      ],
      "subtotal_cents": 3450,
      "discount_cents": 0,
      "total_cents": 3450,
      "promotion": null
    },
    "next_month": {
      "people": 23,
      "free": false,
      "lines": [
        {
          "line": "core",
          "unit_cents": 150,
          "qty": 23,
          "amount_cents": 3450,
          "discount_cents": 0
        }
      ],
      "subtotal_cents": 3450,
      "discount_cents": 0,
      "total_cents": 3450,
      "promotion": null
    },
    "storage": {
      "included_gb": 5,
      "extra_gb": 2,
      "limit_gb": 7,
      "month_extra_gb": 2,
      "gb_cents": 100,
      "month_cents": 200
    },
    "billing": {
      "exists": true,
      "status": "active",
      "first_charge_on": null,
      "needs_details": false
    },
    "promotion": null
  }
}

See credits and storage#

POST/v1/platform/usage.getRead

What the company has left this month, per resource: emails (optional emails: reminders, approvals, documents, time off, announcements, 1:1s; essential emails never count) and AI credits (1 per document Bizisy reads: a CV, a renewal document, a bank proof), each with the month's included amount (Free 20; from 10 active people: emails 10 and AI credits 5 per active person, pooled), what is left of it (it resets on the 1st, resets_on), the bought balance (carries over, used after the included amount) and this month's use by kind; storage (included 1 GB on Free, 5 GB from 10 active people, the extra GB chosen, the limit); the last 50 ledger rows (kinds and amounts only); and whether packs can be bought now. Check it before reading many documents. Owners, admins and HR.

Who can call it
Manage key owner admin hr
MCP tool
platform_usage_get on HR Assistant
Method
POST with a JSON body, or GET with the input as query parameters

Input

No input: send {}.

Returns

10 fields
  • monthstringrequired

    YYYY-MM (UTC).

  • resets_onstringrequired

    YYYY-MM-DD: when the included amounts reset (the 1st).

  • sandboxbooleanrequired
  • peopleintegerrequired

    Active people the included amounts are computed on.

  • freebooleanrequired

    Up to 9 active people (the Free plan).

  • emailobjectrequired
    6 fields
    • includedintegerrequired

      Included this month (Free 20; from 10 active people: emails 10, AI credits 5 per active person, pooled).

    • included_leftintegerrequired

      Included left this month: it resets on resets_on and never carries over.

    • boughtintegerrequired

      Bought left: carries over, used once the included amount runs out.

    • usedobjectrequired

      This month's use by kind (emails: reminders, approval_request, …; AI: cv, renewal, bank_proof).

    • unlimitedbooleanrequired

      A developer sandbox: not counted.

    • heldintegerrequired

      Optional emails not sent this month because none were left: their notices reached people in the app.

  • aiobjectrequired
    5 fields
    • includedintegerrequired

      Included this month (Free 20; from 10 active people: emails 10, AI credits 5 per active person, pooled).

    • included_leftintegerrequired

      Included left this month: it resets on resets_on and never carries over.

    • boughtintegerrequired

      Bought left: carries over, used once the included amount runs out.

    • usedobjectrequired

      This month's use by kind (emails: reminders, approval_request, …; AI: cv, renewal, bank_proof).

    • unlimitedbooleanrequired

      A developer sandbox: not counted.

  • storageobject | nullrequired

    Null where the server has no file storage.

    7 fields
    • bytesintegerrequired

      Stored now.

    • included_gbintegerrequired
    • extra_gbintegerrequired
    • limit_gbintegerrequired
    • month_extra_gbintegerrequired

      The highest extra GB chosen this month: what this month bills.

    • gb_centsintegerrequired

      €1 per extra GB a month, excluding VAT.

    • max_extra_gbintegerrequired
  • historyobject[]required

    The last 50 rows of the credits ledger (kinds, amounts and dates only: no names, no documents).

    5 fields
    • atstringrequired
    • resource"email" | "ai"required
    • kind"grant" | "purchase" | "use" | "refund" | "operator_grant" | "removed"required

      grant: the month's included amount; purchase: a pack; use; refund: a use given back; operator_grant: from Bizisy support; removed: a refunded pack's unused part.

    • amountintegerrequired
    • usestring | nullrequired

      What used it (a kind) or which pack.

  • buyobjectrequired
    4 fields
    • availablebooleanrequired

      Packs can be bought on this server for this company.

    • reason"billing_off" | "sandbox"required
    • needs_detailsbooleanrequired

      Billing details are needed first (they are printed on the invoice).

    • purchases_left_todayintegerrequired

      At most 5 pack purchases a day.

Errors

validation_failed unauthenticated forbidden not_found rate_limited internal

curl
curl https://api.bizisy.com/v1/platform/usage.get \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
Response
{
  "data": {
    "month": "2026-11",
    "resets_on": "2026-12-01",
    "sandbox": false,
    "people": 23,
    "free": false,
    "email": {
      "included": 230,
      "included_left": 0,
      "bought": 918,
      "used": {
        "reminders": 180,
        "approval_request": 64,
        "timeoff": 68
      },
      "unlimited": false,
      "held": 0
    },
    "ai": {
      "included": 115,
      "included_left": 103,
      "bought": 0,
      "used": {
        "cv": 9,
        "renewal": 3
      },
      "unlimited": false
    },
    "storage": {
      "bytes": 3200000000,
      "included_gb": 5,
      "extra_gb": 0,
      "limit_gb": 5,
      "month_extra_gb": 0,
      "gb_cents": 100,
      "max_extra_gb": 2000
    },
    "history": [
      {
        "at": "2026-11-03T09:12:00.000Z",
        "resource": "email",
        "kind": "purchase",
        "amount": 1000,
        "use": "emails_1000"
      },
      {
        "at": "2026-11-01T00:00:00.000Z",
        "resource": "ai",
        "kind": "grant",
        "amount": 115,
        "use": null
      },
      {
        "at": "2026-11-02T10:00:00.000Z",
        "resource": "ai",
        "kind": "use",
        "amount": -1,
        "use": "cv"
      }
    ],
    "buy": {
      "available": true,
      "reason": null,
      "needs_details": false,
      "purchases_left_today": 5
    }
  }
}

See credit packs#

POST/v1/platform/credits.packsRead

The packs the company can buy, with their price for it: 1,000 emails €1; AI credits 100 for €5, 500 for €20, 2,000 for €60; excluding VAT (23 % Portuguese VAT where it applies; none under EU reverse charge or outside the EU). Paid once, they never expire, and are used after the month's included amount. Owners, admins and HR; only owners and admins buy, in the web app (platform_credits_checkout).

Who can call it
Manage key owner admin hr
MCP tool
platform_credits_packs on HR Assistant
Method
POST with a JSON body, or GET with the input as query parameters

Input

No input: send {}.

Returns

  • currency"EUR"required
  • vatobjectrequired
    2 fields
    • kind"portuguese_vat" | "reverse_charge" | "export" | "unknown"required

      unknown: no billing details yet (estimated with Portuguese VAT).

    • percentintegerrequired
  • packsobject[]required
    6 fields
    • id"emails_1000" | "ai_100" | "ai_500" | "ai_2000"required
    • resource"email" | "ai"required
    • amountintegerrequired
    • centsintegerrequired

      Excluding VAT, paid once.

    • vat_centsintegerrequired

      The VAT on it for this company (23 % Portuguese VAT, or 0 under reverse charge or outside the EU).

    • total_centsintegerrequired
  • availablebooleanrequired
  • reason"billing_off" | "sandbox"required

Errors

validation_failed unauthenticated forbidden not_found rate_limited internal

curl
curl https://api.bizisy.com/v1/platform/credits.packs \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
Response
{
  "data": {
    "currency": "EUR",
    "vat": {
      "kind": "portuguese_vat",
      "percent": 23
    },
    "available": true,
    "reason": null,
    "packs": [
      {
        "id": "emails_1000",
        "resource": "email",
        "amount": 1000,
        "cents": 100,
        "vat_cents": 23,
        "total_cents": 123
      },
      {
        "id": "ai_100",
        "resource": "ai",
        "amount": 100,
        "cents": 500,
        "vat_cents": 115,
        "total_cents": 615
      },
      {
        "id": "ai_500",
        "resource": "ai",
        "amount": 500,
        "cents": 2000,
        "vat_cents": 460,
        "total_cents": 2460
      },
      {
        "id": "ai_2000",
        "resource": "ai",
        "amount": 2000,
        "cents": 6000,
        "vat_cents": 1380,
        "total_cents": 7380
      }
    ]
  }
}

Buy credits#

POST/v1/platform/credits.checkoutWrite

Web app only: starts a Stripe Checkout page to pay for one pack once and returns its short-lived url: emails_1000 (1,000 emails, €1), ai_100 (100 AI credits, €5), ai_500 (500, €20) or ai_2000 (2,000, €60), excluding VAT. Any plan, Free included. The credits are added once the payment succeeds (never before), with an invoice (fatura and receipt) in Plan & billing; they never expire and are used after the month's included amount. Needs billing details first (printed on the invoice). At most 5 purchases a day. Refused for API keys and AI assistants: tell the user to open Settings → Plan & billing. Owners and admins.

Web app only
Refused for API keys and connected apps. Credit packs are bought on Stripe's page in the browser, by owners and admins signed in to Bizisy.
MCP tool
platform_credits_checkout on HR Assistant
Preview
?dry_run=true runs every check and saves nothing
Retries
An Idempotency-Key prevents a second run, but the result is never stored (it holds a secret or personal data): a retry gets a 409 that points to Activity

Input

  • pack"emails_1000" | "ai_100" | "ai_500" | "ai_2000"required
  • back"billing" | "renewals" | "hiring" | "bank"

    Where Bizisy returns after paying (default Plan & billing).

Returns

  • urlstring | nullrequired

    Null on a dry run.

  • pack"emails_1000" | "ai_100" | "ai_500" | "ai_2000"required
  • centsintegerrequired
  • vat_centsintegerrequired
  • total_centsintegerrequired

Errors

validation_failed unauthenticated forbidden not_found conflict rate_limited internal

curl
curl https://api.bizisy.com/v1/platform/credits.checkout \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"pack":"emails_1000","back":"renewals"}'
Response
{
  "data": {
    "url": "https://checkout.stripe.test/c/pay_1",
    "pack": "emails_1000",
    "cents": 500,
    "vat_cents": 115,
    "total_cents": 615
  }
}

Change the storage limit#

POST/v1/platform/storage.limit.setWrite

Sets the extra storage above what the plan includes (1 GB on Free, 5 GB from 10 active people), in whole GB (0–2000), at €1 per extra GB a month excluding VAT: a monthly line on the subscription, billed at the end of the month on the highest limit chosen in it (raising it on Free starts a subscription for that line only, so billing details are needed first). Lowering is allowed down to what is in use. The dry run shows the new monthly price. Web app only (Settings → Plan & billing): API keys and AI assistants are refused. Owners and admins; 20 changes a day.

Web app only
Refused for API keys and connected apps. The storage limit is raised or lowered in the app only (Settings → Plan & billing), by an owner or admin.
MCP tool
platform_storage_limit_set on HR Assistant
Preview
?dry_run=true runs every check and saves nothing
Retries
An Idempotency-Key prevents a second run, but the result is never stored (it holds a secret or personal data): a retry gets a 409 that points to Activity

Input

  • extra_gbintegerrequired

    From 0 to 2000.

Returns

7 fields
  • included_gbintegerrequired
  • extra_gbintegerrequired
  • limit_gbintegerrequired
  • used_bytesintegerrequired
  • monthly_centsintegerrequired

    extra_gb × €1, excluding VAT: what a month at this limit costs.

  • month_extra_gbintegerrequired

    This month bills the highest extra GB chosen in it.

  • changedbooleanrequired

Errors

validation_failed unauthenticated forbidden not_found conflict rate_limited internal

curl
curl https://api.bizisy.com/v1/platform/storage.limit.set \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"extra_gb":5}'
Response
{
  "data": {
    "included_gb": 5,
    "extra_gb": 5,
    "limit_gb": 10,
    "used_bytes": 3200000000,
    "monthly_cents": 500,
    "month_extra_gb": 5,
    "changed": true
  }
}

See which features are on#

POST/v1/platform/features.getRead

What the company uses (Settings → Modules): every module, all included at no extra price and off until switched on (timeoff = Time off, timeclock = Time clock, which needs Time off, documents = Documents, assets = Equipment, checkins = 1:1s and check-ins, renewals = Renewals, hiring = Hiring, payroll = Payroll, which keeps Documents on, finance = Finance, analytics = Reports & analytics, pay_equity = Pay equity, more_integrations = More integrations, bank_verification = Verified bank details) with whether each is on and offered by this server; AI assistants and API keys per side (manage: Bizisy for HR, managers and admins; me: My workspace) with how many connected AI apps and API keys each side has; and the changes left today (20 a day). Owners, admins and HR; only owners and admins change it, in the web app (Settings → Modules): an assistant can explain, not switch.

Who can call it
Manage key owner admin hr
MCP tool
platform_features_get on HR Assistant
Method
POST with a JSON body, or GET with the input as query parameters

Input

No input: send {}.

Returns

7 fields
  • modulesobject[]required
    7 fields
    • idstring (enum)required

      One of: timeoff, timeclock, shifts, documents, assets, checkins, renewals, hiring, training, talent, insights, payroll, finance, analytics, pay_equity, comp_reviews, more_integrations, bank_verification, benefits, surveys.

    • onbooleanrequired

      Usable now: this server has it and the company has it on.

    • availablebooleanrequired

      This Bizisy server offers it (false: it can't be switched on here).

    • needsstring (enum)required

      Works only with this module on.

      One of: timeoff, timeclock, shifts, documents, assets, checkins, renewals, hiring, training, talent, insights, payroll, finance, analytics, pay_equity, comp_reviews, more_integrations, bank_verification, benefits, surveys.

    • lockedstring | nullrequired

      Why it can't be switched off now (Documents while Payroll is on); null otherwise.

    • default_offbooleanrequired

      Off for every company until switched on (every module, spec 2026-10-20 C3).

    • area"people_time" | "pay" | "documents_equipment" | "growth" | "integrations"required

      Where Settings → Modules groups it: people_time, pay, documents_equipment, growth or integrations.

  • aiobjectrequired

    AI assistants connected by the people themselves (MCP over OAuth), per side: manage (Bizisy for HR, managers and admins) and me (My workspace).

    2 fields
    • managebooleanrequired
    • mebooleanrequired
  • apiobjectrequired

    Personal API keys, per side.

    2 fields
    • managebooleanrequired
    • mebooleanrequired
  • usageobjectrequired
    2 fields
    • aiobjectrequired

      Connected AI apps per side.

      2 fields
      • manageintegerrequired
      • meintegerrequired
    • apiobjectrequired

      API keys per side.

      2 fields
      • manageintegerrequired
      • meintegerrequired
  • chosenbooleanrequired

    The setup guide's "Choose what you use" step was saved.

  • changed_atstring | nullrequired
  • changes_left_todayintegerrequired

Errors

validation_failed unauthenticated forbidden not_found rate_limited internal

curl
curl https://api.bizisy.com/v1/platform/features.get \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
Response
{
  "data": {
    "modules": [
      {
        "default_off": true,
        "id": "timeoff",
        "on": true,
        "available": true,
        "needs": null,
        "locked": null,
        "area": "people_time"
      },
      {
        "default_off": true,
        "id": "timeclock",
        "on": true,
        "available": true,
        "needs": "timeoff",
        "locked": null,
        "area": "people_time"
      },
      {
        "default_off": true,
        "id": "documents",
        "on": true,
        "available": true,
        "needs": null,
        "locked": "Payroll delivers payslips through Documents: switch Payroll off first.",
        "area": "documents_equipment"
      },
      {
        "default_off": true,
        "id": "assets",
        "on": true,
        "available": true,
        "needs": null,
        "locked": null,
        "area": "documents_equipment"
      },
      {
        "default_off": true,
        "id": "hiring",
        "on": false,
        "available": true,
        "needs": null,
        "locked": null,
        "area": "growth"
      },
      {
        "default_off": true,
        "id": "payroll",
        "on": true,
        "available": true,
        "needs": null,
        "locked": null,
        "area": "pay"
      }
    ],
    "ai": {
      "manage": true,
      "me": true
    },
    "api": {
      "manage": true,
      "me": true
    },
    "usage": {
      "ai": {
        "manage": 2,
        "me": 5
      },
      "api": {
        "manage": 1,
        "me": 0
      }
    },
    "chosen": false,
    "changed_at": null,
    "changes_left_today": 20
  }
}

Switch features on or off#

POST/v1/platform/features.updateWrite

Switches the company's modules (modules: { timeoff, timeclock, documents, assets, checkins, renewals, hiring, payroll, finance, analytics, pay_equity, more_integrations, bank_verification }: true on, false off; every module is included at no extra price and off until switched on) and AI assistants or API keys per side (ai / api: { manage, me }). Only what is given changes. Switching a module off keeps all its data (turning it back on shows everything again), hides it or pauses it everywhere and refuses its actions with module_disabled (reads of stored records keep working); Time off off takes the Time clock with it; Payroll on switches Documents on, and Documents can't be switched off while Payroll is on. Switching AI or API access off refuses those credentials on that side with ai_disabled / api_disabled (kept, working again when switched back on; AI off also refuses that side's API keys over MCP); disconnect: true also disconnects them for good. Installed apps and webhooks are not affected. The dry run returns what would stop (waiting requests, AI apps and keys). Web app only (Settings → Modules): API keys and AI assistants are refused. Owners and admins; AI and API changes need a sign-in from the last 10 minutes; 20 changes a day.

Web app only
Refused for API keys and connected apps. Modules and AI and API access are switched in the app only (Settings → Modules), by an owner or admin.
MCP tool
platform_features_update on HR Assistant
Preview
?dry_run=true runs every check and saves nothing
Retries
An Idempotency-Key replays the first result

Input

  • modulesobject
    20 fields
    • timeoffboolean
    • timeclockboolean
    • shiftsboolean
    • documentsboolean
    • assetsboolean
    • checkinsboolean
    • renewalsboolean
    • hiringboolean
    • trainingboolean
    • talentboolean
    • insightsboolean
    • payrollboolean
    • financeboolean
    • analyticsboolean
    • pay_equityboolean
    • comp_reviewsboolean
    • more_integrationsboolean
    • bank_verificationboolean
    • benefitsboolean
    • surveysboolean
  • aiobject
    2 fields
    • manageboolean
    • meboolean
  • apiobject
    2 fields
    • manageboolean
    • meboolean
  • disconnectboolean

    With an AI or API side switched off: also disconnect those AI apps and revoke those keys for good.

  • setupboolean

    Saved from the setup guide's "Choose what you use" step (marks it done).

Returns

12 fields
  • modulesobject[]required
    7 fields
    • idstring (enum)required

      One of: timeoff, timeclock, shifts, documents, assets, checkins, renewals, hiring, training, talent, insights, payroll, finance, analytics, pay_equity, comp_reviews, more_integrations, bank_verification, benefits, surveys.

    • onbooleanrequired

      Usable now: this server has it and the company has it on.

    • availablebooleanrequired

      This Bizisy server offers it (false: it can't be switched on here).

    • needsstring (enum)required

      Works only with this module on.

      One of: timeoff, timeclock, shifts, documents, assets, checkins, renewals, hiring, training, talent, insights, payroll, finance, analytics, pay_equity, comp_reviews, more_integrations, bank_verification, benefits, surveys.

    • lockedstring | nullrequired

      Why it can't be switched off now (Documents while Payroll is on); null otherwise.

    • default_offbooleanrequired

      Off for every company until switched on (every module, spec 2026-10-20 C3).

    • area"people_time" | "pay" | "documents_equipment" | "growth" | "integrations"required

      Where Settings → Modules groups it: people_time, pay, documents_equipment, growth or integrations.

  • aiobjectrequired

    AI assistants connected by the people themselves (MCP over OAuth), per side: manage (Bizisy for HR, managers and admins) and me (My workspace).

    2 fields
    • managebooleanrequired
    • mebooleanrequired
  • apiobjectrequired

    Personal API keys, per side.

    2 fields
    • managebooleanrequired
    • mebooleanrequired
  • usageobjectrequired
    2 fields
    • aiobjectrequired

      Connected AI apps per side.

      2 fields
      • manageintegerrequired
      • meintegerrequired
    • apiobjectrequired

      API keys per side.

      2 fields
      • manageintegerrequired
      • meintegerrequired
  • chosenbooleanrequired

    The setup guide's "Choose what you use" step was saved.

  • changed_atstring | nullrequired
  • changes_left_todayintegerrequired
  • modules_onstring (enum)[]required

    One of: timeoff, timeclock, shifts, documents, assets, checkins, renewals, hiring, training, talent, insights, payroll, finance, analytics, pay_equity, comp_reviews, more_integrations, bank_verification, benefits, surveys.

  • modules_offstring (enum)[]required

    One of: timeoff, timeclock, shifts, documents, assets, checkins, renewals, hiring, training, talent, insights, payroll, finance, analytics, pay_equity, comp_reviews, more_integrations, bank_verification, benefits, surveys.

  • access_onstring[]required
  • access_offstring[]required
  • impactobjectrequired
    4 fields
    • waitingobject[]required

      Requests left waiting in modules switched off (left as they are).

      2 fields
      • modulestring (enum)required

        One of: timeoff, timeclock, shifts, documents, assets, checkins, renewals, hiring, training, talent, insights, payroll, finance, analytics, pay_equity, comp_reviews, more_integrations, bank_verification, benefits, surveys.

      • countintegerrequired
    • ai_appsintegerrequired

      Connected AI apps that stop working.

    • api_keysintegerrequired

      API keys that stop working.

    • disconnectedbooleanrequired

      They are disconnected and revoked for good (disconnect: true).

Errors

validation_failed unauthenticated forbidden not_found conflict rate_limited internal

curl
curl https://api.bizisy.com/v1/platform/features.update \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"modules":{"documents":true},"setup":true}'
Response
{
  "data": {
    "modules": [
      {
        "default_off": true,
        "id": "timeoff",
        "on": false,
        "available": true,
        "needs": null,
        "locked": null,
        "area": "people_time"
      },
      {
        "default_off": true,
        "id": "timeclock",
        "on": false,
        "available": true,
        "needs": "timeoff",
        "locked": null,
        "area": "people_time"
      },
      {
        "default_off": true,
        "id": "documents",
        "on": true,
        "available": true,
        "needs": null,
        "locked": "Payroll delivers payslips through Documents: switch Payroll off first.",
        "area": "documents_equipment"
      },
      {
        "default_off": true,
        "id": "assets",
        "on": true,
        "available": true,
        "needs": null,
        "locked": null,
        "area": "documents_equipment"
      },
      {
        "default_off": true,
        "id": "hiring",
        "on": false,
        "available": true,
        "needs": null,
        "locked": null,
        "area": "growth"
      },
      {
        "default_off": true,
        "id": "payroll",
        "on": true,
        "available": true,
        "needs": null,
        "locked": null,
        "area": "pay"
      }
    ],
    "ai": {
      "manage": true,
      "me": true
    },
    "api": {
      "manage": true,
      "me": true
    },
    "usage": {
      "ai": {
        "manage": 2,
        "me": 5
      },
      "api": {
        "manage": 1,
        "me": 0
      }
    },
    "chosen": false,
    "changed_at": null,
    "changes_left_today": 20,
    "modules_on": [],
    "modules_off": [
      "timeoff",
      "timeclock"
    ],
    "access_on": [],
    "access_off": [],
    "impact": {
      "waiting": [
        {
          "module": "timeoff",
          "count": 3
        }
      ],
      "ai_apps": 0,
      "api_keys": 0,
      "disconnected": false
    }
  }
}

Redeem a promotion code#

POST/v1/platform/promotions.redeemWrite

Applies a promotion code to the company: a discount on the plan lines it names for some months (from the first month the company is charged) or until a date, shown in Plan & billing and on every invoice. One promotion at a time; codes for new companies are refused for a company older than 30 days or that has paid an invoice. Owners and admins, in the web app only (Settings → Plan & billing): API keys and AI assistants are refused; tell the user where to do it. At most 5 attempts per company per hour. Preview with dry_run.

Web app only
Refused for API keys and connected apps. Promotion codes are redeemed in the app only, by an owner or admin.
MCP tool
platform_promotions_redeem on HR Assistant
Preview
?dry_run=true runs every check and saves nothing
Retries
An Idempotency-Key prevents a second run, but the result is never stored (it holds a secret or personal data): a retry gets a 409 that points to Activity

Input

  • codestringrequired

    The promotion code, as given (case, spaces and hyphens do not matter).

    1–64 characters.

Returns

  • labelstringrequired
  • summarystringrequired
  • notestring | nullrequired
  • starts"first_paid_month"required

    first_paid_month: it starts with the first month the company is charged.

  • partnerstring | nullrequired

    The Bizisy partner the company is now linked to (a partner's code), or null.

Errors

validation_failed unauthenticated forbidden not_found conflict rate_limited internal

curl
curl https://api.bizisy.com/v1/platform/promotions.redeem \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"code":"partner-20"}'
Response
{
  "data": {
    "label": "Founding Customers",
    "summary": "Core free for 3 months",
    "note": "You agree to give an honest review of Bizisy and to take part in a short case study.",
    "starts": "first_paid_month",
    "partner": null
  }
}

See billing#

POST/v1/platform/billing.getRead

Returns the organization's Bizisy billing: status (free: the Free plan, up to 9 active people and no extra storage, nothing to set up; free_early_access before the start; free_first_month while the subscription's first, partial month is not charged, until starts_on; then active, past_due, needs_details, starting, paused or canceled; no card is needed: collection says whether invoices are charged to a card or emailed to pay), the active people count, billable (10 or more active people, or extra storage chosen this month), plan (this month's price: free up to 9 active people, then €1.50 per active person, every module included; excluding VAT) and estimated monthly total, how VAT applies, the payment method summary (brand, last 4 digits, expiry; never the card number), the next charge date and the billing details, plus storage (1 GB included on Free, 5 GB from 10 active people; extra GB chosen at €1 each a month, billed on the month's highest limit) and the total so far. Emails and AI credits (included each month, packs bought once) are in platform_usage_get. open_invoices lists the unpaid invoices (overdue ones flagged, overdue totals them) and pause says since when the company is paused and when it is closed if still unpaid. Billed monthly in arrears at the end of each calendar month for the people active then and the month's highest extra storage; the month billing starts in is not charged. Owners and admins only.

Who can call it
Manage key owner admin
MCP tool
platform_billing_get on HR Assistant
Method
POST with a JSON body, or GET with the input as query parameters

Input

No input: send {}.

Returns

27 fields
  • mode"test" | "live"required

    test: Stripe sandbox, nothing is really charged.

  • statusstring (enum)required

    free: the Free plan (up to 9 active people and no paid module): nothing to set up and nothing charged; billing details are needed only from 10 people or once a paid module is switched on. paused: an invoice is unpaid past its due date (or billing details are missing past their deadline): only owners and admins can sign in, to pay, save a card or export data; everything else is refused until it is paid. needs_details: billing has started and billing details are missing (no card is needed).

    One of: free, free_early_access, free_first_month, starting, needs_details, active, past_due, paused, canceled.

  • starts_onstring | nullrequired

    When this organization starts paying (YYYY-MM-DD, always a 1st): the 1st of the month after its start date (the announced date, never earlier than 30 days after its notice email), since the month billing starts in is not charged; null while no date is announced.

  • active_peopleintegerrequired

    People active today (pre-hires and leavers are not counted).

  • quantityintegerrequired

    People billed: the active count.

  • currency"EUR"required
  • billablebooleanrequired

    Billing applies: 10 or more active people, or extra storage chosen this month. false: Free, nothing to set up.

  • planobjectrequired

    This month so far (platform_plan_get has the plan), priced on the active people now: free up to 9, then €1.50 per active person, every module included.

    7 fields
    • peopleintegerrequired

      Active people the month is priced on.

    • freebooleanrequired

      Up to 9 active people: nothing is charged.

    • linesobject[]required

      The charged lines: Core for every active person from 10 (none on Free).

      5 fields
      • line"core"required
      • unit_centsintegerrequired

        Per active person per month, excl. VAT.

      • qtyintegerrequired
      • amount_centsintegerrequired

        List amount (unit × qty).

      • discount_centsintegerrequired

        The promotion's discount on this line (0 without one).

    • subtotal_centsintegerrequired

      The charged lines at list price, before the promotion.

    • discount_centsintegerrequired

      The promotion's discount this month (0 without one).

    • total_centsintegerrequired

      Per month, excluding VAT, after the promotion (extra storage is billed on its own line).

    • promotionobject | nullrequired

      The company's promotion as priced this month, or null.

      8 fields
      • codestringrequired
      • labelstringrequired
      • kind"free_months" | "percent"required
      • percentintegerrequired
      • lines"core"[]required
      • appliesbooleanrequired

        It discounts this month.

      • untilstring | nullrequired

        YYYY-MM-DD: the last day it covers; null while it waits for the first paid month.

      • starts"first_paid_month"required

        first_paid_month: it starts with the first month the company is charged.

  • estimated_monthly_centsintegerrequired

    The plan this month, excluding VAT. Billed monthly in arrears at the end of each calendar month for the people active then and every module on at any point in the month.

  • vat"portuguese_vat" | "reverse_charge" | "export"required

    How VAT applies (from the billing details); null without details.

  • payment_methodobject | nullrequired
    4 fields
    • brandstringrequired
    • last4stringrequired
    • exp_monthintegerrequired
    • exp_yearintegerrequired
  • next_charge_onstring | nullrequired

    The next charge (a 1st: the end of the month being billed); during the uncharged first month, the end of the first paid month.

  • cancel_atstring | nullrequired

    Set when the subscription was canceled: it ends (and access stays) until this date.

  • detailsobject | nullrequired
    5 fields
    • legal_namestringrequired
    • vat_numberstring | nullrequired
    • emailstringrequired
    • addressobjectrequired
      5 fields
      • line1stringrequired

        1–200 characters.

      • line2string | nullrequired

        Up to 200 characters.

      • citystringrequired

        1–100 characters.

      • postal_codestringrequired

        1–20 characters.

      • countrystringrequired

        Pattern ^[A-Z]{2}$.

    • vat_verification"valid" | "invalid" | "unverified_network" | "unverified_error" | "not_applicable"required

      EU VAT numbers outside Portugal are checked with the EU VIES service when saved: invalid means Portuguese VAT applies; unverified_network (VIES unreachable) and unverified_error (VIES refused the check; Bizisy is alerted) keep the format check until VIES answers. null on a dry run: the preview uses the format check and VIES is asked only when the change is saved.

  • billing_starts_onstring | nullrequired

    When billing starts for this organization (YYYY-MM-DD, Lisbon): from this day a payment method is needed; the month it falls in is not charged. null while no date is announced.

  • first_charge_onstring | nullrequired

    When the payment method is first charged (YYYY-MM-DD, a 1st), while nothing has been charged yet: the end of the first paid month, since billing is monthly in arrears and the month billing starts in is not charged. null without an announced start date, once charging has begun, when the subscription is set to cancel, and for an organization subscribed before (a new subscription is then charged from its first month).

  • defaultsobjectrequired

    Suggestions for an empty details form: the legal entity (or the company) and the caller's email.

    5 fields
    • legal_namestringrequired
    • emailstringrequired
    • countrystringrequired
    • vat_numberstring | nullrequired

      The legal entity's tax id, when it has one.

    • source"legal_entity" | "organization"required

      legal_entity: name, country and tax id come from the company's first legal entity; organization: from the company name and country.

  • can_checkoutbooleanrequired

    A card can be saved through Stripe Checkout (no card saved yet, or no running subscription; once a card pays, it changes in the portal). Saving one makes later invoices charged automatically.

  • collection"card" | "invoice"required

    How invoices are paid: card (charged automatically) or invoice (emailed at month end, paid within 14 days on Stripe's page by card, SEPA Direct Debit or bank transfer); null before a subscription exists.

  • open_invoiceobject | nullrequired

    The oldest unpaid invoice, if any.

    8 fields
    • idstringrequired
    • numberstring | nullrequired
    • amount_due_centsintegerrequired

      What is left to pay, VAT included.

    • issued_onstringrequired

      YYYY-MM-DD (Lisbon) the invoice was issued.

    • due_onstringrequired

      YYYY-MM-DD (Lisbon): if it is unpaid then, Bizisy pauses for everyone except owners and admins.

    • days_leftintegerrequired

      Whole days until due_on (0 = due today or past).

    • collection"card" | "invoice"required

      card: a card payment that failed; invoice: emailed, paid on Stripe's page.

    • overduebooleanrequired

      Unpaid past the end of its due day (Lisbon): it counts toward the pause; paying every overdue invoice unpauses.

  • open_invoicesobject[]required

    Every unpaid invoice, oldest first (at most 12). Billing continues while paused, so there may be several.

    8 fields
    • idstringrequired
    • numberstring | nullrequired
    • amount_due_centsintegerrequired

      What is left to pay, VAT included.

    • issued_onstringrequired

      YYYY-MM-DD (Lisbon) the invoice was issued.

    • due_onstringrequired

      YYYY-MM-DD (Lisbon): if it is unpaid then, Bizisy pauses for everyone except owners and admins.

    • days_leftintegerrequired

      Whole days until due_on (0 = due today or past).

    • collection"card" | "invoice"required

      card: a card payment that failed; invoice: emailed, paid on Stripe's page.

    • overduebooleanrequired

      Unpaid past the end of its due day (Lisbon): it counts toward the pause; paying every overdue invoice unpauses.

  • overdueobject | nullrequired

    Unpaid invoices past the end of their due day: every one must be paid to lift a pause (or reopen a company closed for non-payment).

    2 fields
    • countintegerrequired
    • total_centsintegerrequired
  • pauseobject | nullrequired

    Set while the company is paused (pay-or-lock).

    3 fields
    • reason"unpaid" | "details_missing"required
    • sincestringrequired

      YYYY-MM-DD (Lisbon).

    • closes_onstringrequired

      YYYY-MM-DD: if still unpaid then, the company account is closed (deleted 14 days later unless paid).

  • details_due_onstring | nullrequired

    needs_details: YYYY-MM-DD when Bizisy pauses if billing details are still missing.

  • can_open_portalbooleanrequired

    The Stripe customer portal exists (after the first checkout).

  • storageobject | nullrequired

    Storage (spec 2026-10-20 C8); null where the server has no file storage. Emails and AI credits are in platform_usage_get.

    7 fields
    • bytesintegerrequired

      Stored now (documents, photos, logo).

    • included_gbintegerrequired

      Included: 1 GB on Free, 5 GB from 10 active people.

    • extra_gbintegerrequired

      Extra GB chosen now.

    • limit_gbintegerrequired

      included_gb + extra_gb: uploads past it are refused.

    • month_extra_gbintegerrequired

      This month's highest extra GB chosen: what the storage line bills.

    • gb_centsintegerrequired

      €1 per extra GB a month, excluding VAT.

    • estimated_centsintegerrequired

      This month's storage line so far, excluding VAT; billed with the people at month end.

  • estimated_total_centsintegerrequired

    People and extra storage so far this month, excluding VAT (packs are paid when bought).

Errors

validation_failed unauthenticated forbidden not_found rate_limited internal

curl
curl https://api.bizisy.com/v1/platform/billing.get \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
Response
{
  "data": {
    "mode": "test",
    "status": "active",
    "starts_on": "2026-12-01",
    "active_people": 23,
    "quantity": 23,
    "currency": "EUR",
    "estimated_monthly_cents": 3450,
    "billable": true,
    "plan": {
      "people": 23,
      "free": false,
      "lines": [
        {
          "line": "core",
          "unit_cents": 150,
          "qty": 23,
          "amount_cents": 3450,
          "discount_cents": 0
        }
      ],
      "subtotal_cents": 3450,
      "discount_cents": 0,
      "total_cents": 3450,
      "promotion": null
    },
    "vat": "portuguese_vat",
    "payment_method": {
      "brand": "visa",
      "last4": "4242",
      "exp_month": 12,
      "exp_year": 2030
    },
    "next_charge_on": "2027-01-01",
    "cancel_at": null,
    "details": {
      "legal_name": "Acme, Lda",
      "vat_number": "PT501442600",
      "email": "billing@acme.test",
      "address": {
        "line1": "Rua Augusta 100",
        "line2": null,
        "city": "Lisboa",
        "postal_code": "1100-053",
        "country": "PT"
      },
      "vat_verification": "not_applicable"
    },
    "billing_starts_on": "2026-11-04",
    "first_charge_on": null,
    "defaults": {
      "legal_name": "Acme Lda",
      "email": "ana@acme.test",
      "country": "PT",
      "vat_number": "501442600",
      "source": "legal_entity"
    },
    "can_checkout": false,
    "can_open_portal": true,
    "storage": {
      "bytes": 3200000000,
      "included_gb": 5,
      "extra_gb": 2,
      "limit_gb": 7,
      "month_extra_gb": 2,
      "gb_cents": 100,
      "estimated_cents": 200
    },
    "estimated_total_cents": 3650,
    "collection": "card",
    "open_invoice": null,
    "open_invoices": [],
    "overdue": null,
    "pause": null,
    "details_due_on": null
  }
}

Change billing details#

POST/v1/platform/billing.update_detailsWrite

Sets the billing details printed on invoices: legal_name, vat_number (NIF in Portugal, required and checked: companies and sole traders; EU VAT numbers get their country prefix and a format check), email (where invoices go) and address { line1, line2?, city, postal_code, country }. Send the whole set every time. The country and VAT number decide VAT: Portugal (and EU without a VAT number) pays Portuguese VAT, EU businesses with a VAT number are reverse charged, outside the EU is exempt. Owners and admins only; preview with dry_run.

Who can call it
Manage key owner admin
MCP tool
platform_billing_update_details on HR Assistant
Preview
?dry_run=true runs every check and saves nothing
Retries
An Idempotency-Key prevents a second run, but the result is never stored (it holds a secret or personal data): a retry gets a 409 that points to Activity

Input

  • legal_namestringrequired

    The legal name on invoices, e.g. "Acme, Lda".

    2–200 characters.

  • vat_numberstring | null

    NIF / VAT number. Required in Portugal (a valid NIF of a company or sole trader: first digit 1, 2, 3, 5, 6, 8 or 9; 999999990 refused); EU numbers get their country prefix; optional outside Portugal.

    Up to 40 characters.

  • emailemailrequired

    Where invoices and billing emails go.

    Up to 254 characters.

  • addressobjectrequired
    5 fields
    • line1stringrequired

      1–200 characters.

    • line2string | null

      Up to 200 characters.

    • citystringrequired

      1–100 characters.

    • postal_codestringrequired

      1–20 characters.

    • countryanyrequired

      ISO 3166 two-letter code, e.g. PT.

Returns

27 fields
  • mode"test" | "live"required

    test: Stripe sandbox, nothing is really charged.

  • statusstring (enum)required

    free: the Free plan (up to 9 active people and no paid module): nothing to set up and nothing charged; billing details are needed only from 10 people or once a paid module is switched on. paused: an invoice is unpaid past its due date (or billing details are missing past their deadline): only owners and admins can sign in, to pay, save a card or export data; everything else is refused until it is paid. needs_details: billing has started and billing details are missing (no card is needed).

    One of: free, free_early_access, free_first_month, starting, needs_details, active, past_due, paused, canceled.

  • starts_onstring | nullrequired

    When this organization starts paying (YYYY-MM-DD, always a 1st): the 1st of the month after its start date (the announced date, never earlier than 30 days after its notice email), since the month billing starts in is not charged; null while no date is announced.

  • active_peopleintegerrequired

    People active today (pre-hires and leavers are not counted).

  • quantityintegerrequired

    People billed: the active count.

  • currency"EUR"required
  • billablebooleanrequired

    Billing applies: 10 or more active people, or extra storage chosen this month. false: Free, nothing to set up.

  • planobjectrequired

    This month so far (platform_plan_get has the plan), priced on the active people now: free up to 9, then €1.50 per active person, every module included.

    7 fields
    • peopleintegerrequired

      Active people the month is priced on.

    • freebooleanrequired

      Up to 9 active people: nothing is charged.

    • linesobject[]required

      The charged lines: Core for every active person from 10 (none on Free).

      5 fields
      • line"core"required
      • unit_centsintegerrequired

        Per active person per month, excl. VAT.

      • qtyintegerrequired
      • amount_centsintegerrequired

        List amount (unit × qty).

      • discount_centsintegerrequired

        The promotion's discount on this line (0 without one).

    • subtotal_centsintegerrequired

      The charged lines at list price, before the promotion.

    • discount_centsintegerrequired

      The promotion's discount this month (0 without one).

    • total_centsintegerrequired

      Per month, excluding VAT, after the promotion (extra storage is billed on its own line).

    • promotionobject | nullrequired

      The company's promotion as priced this month, or null.

      8 fields
      • codestringrequired
      • labelstringrequired
      • kind"free_months" | "percent"required
      • percentintegerrequired
      • lines"core"[]required
      • appliesbooleanrequired

        It discounts this month.

      • untilstring | nullrequired

        YYYY-MM-DD: the last day it covers; null while it waits for the first paid month.

      • starts"first_paid_month"required

        first_paid_month: it starts with the first month the company is charged.

  • estimated_monthly_centsintegerrequired

    The plan this month, excluding VAT. Billed monthly in arrears at the end of each calendar month for the people active then and every module on at any point in the month.

  • vat"portuguese_vat" | "reverse_charge" | "export"required

    How VAT applies (from the billing details); null without details.

  • payment_methodobject | nullrequired
    4 fields
    • brandstringrequired
    • last4stringrequired
    • exp_monthintegerrequired
    • exp_yearintegerrequired
  • next_charge_onstring | nullrequired

    The next charge (a 1st: the end of the month being billed); during the uncharged first month, the end of the first paid month.

  • cancel_atstring | nullrequired

    Set when the subscription was canceled: it ends (and access stays) until this date.

  • detailsobject | nullrequired
    5 fields
    • legal_namestringrequired
    • vat_numberstring | nullrequired
    • emailstringrequired
    • addressobjectrequired
      5 fields
      • line1stringrequired

        1–200 characters.

      • line2string | nullrequired

        Up to 200 characters.

      • citystringrequired

        1–100 characters.

      • postal_codestringrequired

        1–20 characters.

      • countrystringrequired

        Pattern ^[A-Z]{2}$.

    • vat_verification"valid" | "invalid" | "unverified_network" | "unverified_error" | "not_applicable"required

      EU VAT numbers outside Portugal are checked with the EU VIES service when saved: invalid means Portuguese VAT applies; unverified_network (VIES unreachable) and unverified_error (VIES refused the check; Bizisy is alerted) keep the format check until VIES answers. null on a dry run: the preview uses the format check and VIES is asked only when the change is saved.

  • billing_starts_onstring | nullrequired

    When billing starts for this organization (YYYY-MM-DD, Lisbon): from this day a payment method is needed; the month it falls in is not charged. null while no date is announced.

  • first_charge_onstring | nullrequired

    When the payment method is first charged (YYYY-MM-DD, a 1st), while nothing has been charged yet: the end of the first paid month, since billing is monthly in arrears and the month billing starts in is not charged. null without an announced start date, once charging has begun, when the subscription is set to cancel, and for an organization subscribed before (a new subscription is then charged from its first month).

  • defaultsobjectrequired

    Suggestions for an empty details form: the legal entity (or the company) and the caller's email.

    5 fields
    • legal_namestringrequired
    • emailstringrequired
    • countrystringrequired
    • vat_numberstring | nullrequired

      The legal entity's tax id, when it has one.

    • source"legal_entity" | "organization"required

      legal_entity: name, country and tax id come from the company's first legal entity; organization: from the company name and country.

  • can_checkoutbooleanrequired

    A card can be saved through Stripe Checkout (no card saved yet, or no running subscription; once a card pays, it changes in the portal). Saving one makes later invoices charged automatically.

  • collection"card" | "invoice"required

    How invoices are paid: card (charged automatically) or invoice (emailed at month end, paid within 14 days on Stripe's page by card, SEPA Direct Debit or bank transfer); null before a subscription exists.

  • open_invoiceobject | nullrequired

    The oldest unpaid invoice, if any.

    8 fields
    • idstringrequired
    • numberstring | nullrequired
    • amount_due_centsintegerrequired

      What is left to pay, VAT included.

    • issued_onstringrequired

      YYYY-MM-DD (Lisbon) the invoice was issued.

    • due_onstringrequired

      YYYY-MM-DD (Lisbon): if it is unpaid then, Bizisy pauses for everyone except owners and admins.

    • days_leftintegerrequired

      Whole days until due_on (0 = due today or past).

    • collection"card" | "invoice"required

      card: a card payment that failed; invoice: emailed, paid on Stripe's page.

    • overduebooleanrequired

      Unpaid past the end of its due day (Lisbon): it counts toward the pause; paying every overdue invoice unpauses.

  • open_invoicesobject[]required

    Every unpaid invoice, oldest first (at most 12). Billing continues while paused, so there may be several.

    8 fields
    • idstringrequired
    • numberstring | nullrequired
    • amount_due_centsintegerrequired

      What is left to pay, VAT included.

    • issued_onstringrequired

      YYYY-MM-DD (Lisbon) the invoice was issued.

    • due_onstringrequired

      YYYY-MM-DD (Lisbon): if it is unpaid then, Bizisy pauses for everyone except owners and admins.

    • days_leftintegerrequired

      Whole days until due_on (0 = due today or past).

    • collection"card" | "invoice"required

      card: a card payment that failed; invoice: emailed, paid on Stripe's page.

    • overduebooleanrequired

      Unpaid past the end of its due day (Lisbon): it counts toward the pause; paying every overdue invoice unpauses.

  • overdueobject | nullrequired

    Unpaid invoices past the end of their due day: every one must be paid to lift a pause (or reopen a company closed for non-payment).

    2 fields
    • countintegerrequired
    • total_centsintegerrequired
  • pauseobject | nullrequired

    Set while the company is paused (pay-or-lock).

    3 fields
    • reason"unpaid" | "details_missing"required
    • sincestringrequired

      YYYY-MM-DD (Lisbon).

    • closes_onstringrequired

      YYYY-MM-DD: if still unpaid then, the company account is closed (deleted 14 days later unless paid).

  • details_due_onstring | nullrequired

    needs_details: YYYY-MM-DD when Bizisy pauses if billing details are still missing.

  • can_open_portalbooleanrequired

    The Stripe customer portal exists (after the first checkout).

  • storageobject | nullrequired

    Storage (spec 2026-10-20 C8); null where the server has no file storage. Emails and AI credits are in platform_usage_get.

    7 fields
    • bytesintegerrequired

      Stored now (documents, photos, logo).

    • included_gbintegerrequired

      Included: 1 GB on Free, 5 GB from 10 active people.

    • extra_gbintegerrequired

      Extra GB chosen now.

    • limit_gbintegerrequired

      included_gb + extra_gb: uploads past it are refused.

    • month_extra_gbintegerrequired

      This month's highest extra GB chosen: what the storage line bills.

    • gb_centsintegerrequired

      €1 per extra GB a month, excluding VAT.

    • estimated_centsintegerrequired

      This month's storage line so far, excluding VAT; billed with the people at month end.

  • estimated_total_centsintegerrequired

    People and extra storage so far this month, excluding VAT (packs are paid when bought).

Errors

validation_failed unauthenticated forbidden not_found conflict rate_limited internal

curl
curl https://api.bizisy.com/v1/platform/billing.update_details \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "legal_name": "Acme, Lda",
  "vat_number": "501442600",
  "email": "billing@acme.test",
  "address": {
    "line1": "Rua Augusta 100",
    "city": "Lisboa",
    "postal_code": "1100-053",
    "country": "PT"
  }
}'
Response
{
  "data": {
    "mode": "test",
    "status": "active",
    "starts_on": "2026-12-01",
    "active_people": 23,
    "quantity": 23,
    "currency": "EUR",
    "estimated_monthly_cents": 3450,
    "billable": true,
    "plan": {
      "people": 23,
      "free": false,
      "lines": [
        {
          "line": "core",
          "unit_cents": 150,
          "qty": 23,
          "amount_cents": 3450,
          "discount_cents": 0
        }
      ],
      "subtotal_cents": 3450,
      "discount_cents": 0,
      "total_cents": 3450,
      "promotion": null
    },
    "vat": "portuguese_vat",
    "payment_method": {
      "brand": "visa",
      "last4": "4242",
      "exp_month": 12,
      "exp_year": 2030
    },
    "next_charge_on": "2027-01-01",
    "cancel_at": null,
    "details": {
      "legal_name": "Acme, Lda",
      "vat_number": "PT501442600",
      "email": "billing@acme.test",
      "address": {
        "line1": "Rua Augusta 100",
        "line2": null,
        "city": "Lisboa",
        "postal_code": "1100-053",
        "country": "PT"
      },
      "vat_verification": "not_applicable"
    },
    "billing_starts_on": "2026-11-04",
    "first_charge_on": null,
    "defaults": {
      "legal_name": "Acme Lda",
      "email": "ana@acme.test",
      "country": "PT",
      "vat_number": "501442600",
      "source": "legal_entity"
    },
    "can_checkout": false,
    "can_open_portal": true,
    "storage": {
      "bytes": 3200000000,
      "included_gb": 5,
      "extra_gb": 2,
      "limit_gb": 7,
      "month_extra_gb": 2,
      "gb_cents": 100,
      "estimated_cents": 200
    },
    "estimated_total_cents": 3650,
    "collection": "card",
    "open_invoice": null,
    "open_invoices": [],
    "overdue": null,
    "pause": null,
    "details_due_on": null
  }
}

Add a payment method#

POST/v1/platform/billing.checkoutWrite

Web app only: starts a Stripe Checkout page that saves a payment method and returns its short-lived url. Nothing is charged on that page: from the start date, Bizisy subscribes the organization itself and charges the saved method monthly in arrears at the end of each calendar month (the plan's price per active person, excluding VAT, plus VAT where it applies; see platform_plan_get); the month the subscription starts in is not charged. Needs billing details first; once the subscription runs, the card changes in the billing portal. Refused for API keys and AI assistants: tell the user to open Settings → Plan & billing in Bizisy. Owners and admins only.

Web app only
Refused for API keys and connected apps. Payment pages open in the browser, for owners and admins signed in to Bizisy.
MCP tool
platform_billing_checkout on HR Assistant
Preview
?dry_run=true runs every check and saves nothing
Retries
An Idempotency-Key prevents a second run, but the result is never stored (it holds a secret or personal data): a retry gets a 409 that points to Activity

Input

No input: send {}.

Returns

  • urlstring | nullrequired

    Null on a dry run.

  • mode"setup"required

Errors

validation_failed unauthenticated forbidden not_found conflict rate_limited internal

curl
curl https://api.bizisy.com/v1/platform/billing.checkout \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{}'
Response
{
  "data": {
    "url": "https://checkout.stripe.com/c/pay/cs_test_1",
    "mode": "setup"
  }
}

Open the billing portal#

POST/v1/platform/billing.portalWrite

Web app only: returns a short-lived url to Stripe's customer portal, where the user changes the payment method, downloads Stripe receipts or cancels (at the end of the period already paid). Refused for API keys and AI assistants: tell the user to open Settings → Plan & billing in Bizisy. Owners and admins only; needs a first checkout.

Web app only
Refused for API keys and connected apps. Payment pages open in the browser, for owners and admins signed in to Bizisy.
MCP tool
platform_billing_portal on HR Assistant
Preview
?dry_run=true runs every check and saves nothing
Retries
An Idempotency-Key prevents a second run, but the result is never stored (it holds a secret or personal data): a retry gets a 409 that points to Activity

Input

No input: send {}.

Returns

  • urlstring | nullrequired

    Null on a dry run.

Errors

validation_failed unauthenticated forbidden not_found conflict rate_limited internal

curl
curl https://api.bizisy.com/v1/platform/billing.portal \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{}'
Response
{
  "data": {
    "url": "https://billing.stripe.com/p/session/test_1"
  }
}

List invoices#

POST/v1/platform/billing.invoices.listRead

Lists the organization's Bizisy invoices with an amount to pay, newest first (at most 100; €0 invoices such as the uncharged first month are left out): date, period, people billed, total with and without VAT, payment status (paid, open, failed), the certified invoice (fatura) number and status, and Stripe's receipt page. Owners and admins only.

Who can call it
Manage key owner admin
MCP tool
platform_billing_invoices_list on HR Assistant
Method
POST with a JSON body, or GET with the input as query parameters

Input

No input: send {}.

Returns

An array of objects with 12 fields

An array of objects:

  • idstringrequired
  • numberstring | nullrequired
  • datestringrequired
  • period_startstring | nullrequired
  • period_endstring | nullrequired
  • quantityintegerrequired
  • total_centsintegerrequired
  • total_excluding_vat_centsintegerrequired
  • currencystringrequired
  • status"paid" | "open" | "failed" | "void" | "uncollectible"required
  • faturaobjectrequired
    2 fields
    • status"pending" | "issued" | "failed" | "test"required

      The certified invoice (fatura): pending = being issued (retrying); issued = final; failed = delayed, Bizisy issues it by hand; test = test mode, no fatura is issued.

    • numberstring | nullrequired
  • receipt_urlstring | nullrequired

    Stripe's payment receipt page.

Errors

validation_failed unauthenticated forbidden not_found rate_limited internal

curl
curl https://api.bizisy.com/v1/platform/billing.invoices.list \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
Response
{
  "data": [
    {
      "id": "in_1",
      "number": "BZ-0001",
      "date": "2026-12-01",
      "period_start": "2026-12-01",
      "period_end": "2027-01-01",
      "quantity": 7,
      "total_cents": 1722,
      "total_excluding_vat_cents": 1400,
      "currency": "EUR",
      "status": "paid",
      "fatura": {
        "status": "issued",
        "number": "FR 2026/12"
      },
      "receipt_url": "https://invoice.stripe.com/i/acct_1/test_1"
    }
  ]
}

Download a certified invoice#

POST/v1/platform/billing.invoices.pdfRead

Web app only: returns a download link to the certified invoice (fatura) PDF of one paid invoice (invoice_id from platform_billing_invoices_list), valid for a few seconds. Only for issued faturas. Refused for API keys and AI assistants. Owners and admins only.

Web app only
Refused for API keys and connected apps. Invoices download in the browser, for owners and admins signed in to Bizisy.
MCP tool
platform_billing_invoices_pdf on HR Assistant
Method
POST with a JSON body, or GET with the input as query parameters

Input

  • invoice_idstringrequired

    1–100 characters.

Returns

  • urlstringrequired

Errors

validation_failed unauthenticated forbidden not_found rate_limited internal

curl
curl https://api.bizisy.com/v1/platform/billing.invoices.pdf \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"invoice_id":"in_1"}'
Response
{
  "data": {
    "url": "https://mediaapi.moloni.org/x.pdf?jwt=t"
  }
}

Pay an open invoice#

POST/v1/platform/billing.payRead

Web app only: returns Stripe's payment page for the oldest unpaid Bizisy invoice (or invoice_id from platform_billing_get open_invoice), fetched now and never stored. On that page an owner or admin pays by card, SEPA Direct Debit or bank transfer; paying a paused company's overdue invoice unpauses it at once. Refused for API keys and AI assistants: tell the user to open Settings → Plan & billing in Bizisy and choose Pay now. Owners and admins only.

Web app only
Refused for API keys and connected apps. Invoices are paid on Stripe's page in the browser, by owners and admins signed in to Bizisy.
MCP tool
platform_billing_pay on HR Assistant
Method
POST with a JSON body, or GET with the input as query parameters

Input

  • invoice_idstring

    1–100 characters.

Returns

  • urlstringrequired
  • invoiceobjectrequired
    8 fields
    • idstringrequired
    • numberstring | nullrequired
    • amount_due_centsintegerrequired

      What is left to pay, VAT included.

    • issued_onstringrequired

      YYYY-MM-DD (Lisbon) the invoice was issued.

    • due_onstringrequired

      YYYY-MM-DD (Lisbon): if it is unpaid then, Bizisy pauses for everyone except owners and admins.

    • days_leftintegerrequired

      Whole days until due_on (0 = due today or past).

    • collection"card" | "invoice"required

      card: a card payment that failed; invoice: emailed, paid on Stripe's page.

    • overduebooleanrequired

      Unpaid past the end of its due day (Lisbon): it counts toward the pause; paying every overdue invoice unpauses.

Errors

validation_failed unauthenticated forbidden not_found rate_limited internal

curl
curl https://api.bizisy.com/v1/platform/billing.pay \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"invoice_id":"in_2"}'
Response
{
  "data": {
    "url": "https://invoice.stripe.com/i/acct_1/test_1",
    "invoice": {
      "id": "in_2",
      "number": "BZ-0002",
      "amount_due_cents": 1968,
      "issued_on": "2027-01-01",
      "due_on": "2027-01-15",
      "days_left": 6,
      "collection": "invoice",
      "overdue": false
    }
  }
}

Something missing or wrong on this page? Write to hello@bizisy.com.

Developer docs