CompanyActivations

Switch a company on

Switches an existing company on in the mode carried in the body. The mode is always explicit and never taken from the credential's environment, so a Test key can switch a NIF on in Live.

Modes and billing

  • TEST: immediate and free.
  • PROD: immediate when the account already has a card on file or an enterprise contract, and the NIF is added to the existing subscription. With no card on file it answers 402 CHECKOUT_REQUIRED, returning a checkout_url when success_url and cancel_url are supplied. It also requires being the billing subject of the account (403 NOT_BILLING_OWNER otherwise).
  • billing_period: picks the plan the checkout sells — MONTHLY (default) or ANNUAL. It only matters when a checkout is opened. Accounts with a negotiated rate or an enterprise contract cannot buy the annual plan (422 ANNUAL_PLAN_NOT_AVAILABLE).

Idempotency and pending switch-offs

  • Repeating the call: opens no second checkout and adds no second subscription item; it returns the existing activation with already_active: true. The same Idempotency-Key sent to this route and to the nested one it replaces is the same operation, so it is replayed and never charged twice.
  • A pending switch-off is cancelled: while it is pending the NIF is still on — it just carries an effective date — so switching it on again only removes that date, answers scheduled_deactivation_cancelled: true, and charges or credits nothing. It does commit the NIF to the next billing cycle, though, so under an agreement capped at a number of Live NIFs it asks for a seat like a new NIF would, and is rejected with 409 NIF_LIMIT_REACHED when the cap is already full.
post/v1/companies/{company_id}/activations

Request

  • Base URL: https://app.beel.es/api
  • URL: https://app.beel.es/api/v1/companies/{company_id}/activations
  • Auth: HTTP bearer

Headers

Idempotency-Keystring

Idempotency key to prevent duplicates in sensitive operations.

  • Any unique client-generated string (e.g. an order id). A UUID also works but is not required
  • Allowed characters: letters, digits, _ and - (max 255 chars)
  • Retrying with the same key replays the first response when it was a success (2xx) or a server error (5xx): same status and body, plus the header Idempotency-Replay: true. After a 5xx, check whether the operation took effect before retrying with a new key
  • A 4xx is not stored: the key is released, so the corrected request can reuse it
  • Stored responses expire 24 hours after processing

The key is scoped per user and environment, and bound to the request body, so retrying after a network timeout replays the stored response instead of repeating the operation.

StatusCodeWhen
400INVALID_IDEMPOTENCY_KEYThe key breaks the format rules above.
409IDEMPOTENCY_KEY_PROCESSINGThe first request is still in flight. Wait for the Retry-After seconds (2) and retry with the same key.
409IDEMPOTENCY_KEY_MISMATCHThe key was already used with a different body. Use a new key.

Request body

environment'TEST' | 'PROD' required

Mode a record lives in — its Test/Live twin. It decides where invoices, customers and quota are accounted.

For a company it also decides which AEAT its NIF is registered against: switching a company on in PROD is what registers it with the real AEAT, so aeat_environment is that same mode and uses this same enum.

success_urlstring

Where Stripe returns after the card is captured. Only used when switching on in Live with no card on file. May embed Stripe's {CHECKOUT_SESSION_ID} template, which is why it is a plain string and not a uri: the braces are not legal URI characters.

cancel_urlstring uri

Where Stripe returns if the checkout is abandoned.

billing_period'MONTHLY' | 'ANNUAL'

Nominal billing period of a subscription.

Example request

{
  "environment": "PROD",
  "success_url": "https://your-app.example.com/billing/return?session={CHECKOUT_SESSION_ID}",
  "cancel_url": "https://your-app.example.com/billing",
  "billing_period": "MONTHLY"
}

Response

The NIF is switched on in that mode.

successboolean required

Example response

{
  "success": true,
  "data": {
    "environment": "PROD"
  },
  "meta": {
    "timestamp": "2025-01-15T10:30:00Z",
    "request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
  }
}

Changes

No recorded changes to this operation across all 1 revision of this API.