Organization Activation and Billing

Creating an organization and activating it are separate operations. A newly created organization has its protected owner and an exact PixAtlas Free entitlement pin, but ordinary organization features remain unavailable until its billing activation is complete.

Existing organizations from before the billing rollout remain GrandfatheredActive. They keep their exact entitlement version and do not need to add a payment method during the rollout.

Read the activation state

Call:

GET /v1/orgs/{organizationId}/billing

The response requires OrganizationBillingView and contains:

• activationState, such as PendingSubscription, Active, BillingSuspended, or GrandfatheredActive;
• activationSource, which distinguishes StripeSubscription, ManualEnterprise, Grandfathered, and a subscription that is still required;
• the safe local subscription status and current plan key, when present;
• the organization billing email and its concurrency version, when a Stripe Customer has collected one;
• trial and current-period boundaries;
• the current subscription's effectiveUnitAmountMinor and active discounts, including percentage or fixed reduction, duration, and end date when Stripe applies a Coupon;
• the available server-configured plans.

effectiveUnitAmountMinor is the recurring catalog amount after the returned discounts, in the Price currency's minor unit. It is null when no discount is active. Selectable plan amounts remain the undiscounted catalog prices.

The response never contains card details, Stripe secrets, raw webhook events, or an entitlement permission matrix.

Activate with Stripe Checkout

The protected owner receives these organization billing capabilities by default:

• OrganizationBillingView
• OrganizationPaymentMethodsManage
• OrganizationSubscriptionManage

They are administrative, organization-scoped permissions. They are not controlled by an entitlement ceiling, so the owner can complete activation or payment recovery while the rest of the organization is blocked. They can be delegated explicitly after activation; ordinary members do not receive them by default.

The billing overview can first preview a customer offer code without reserving or consuming it:

POST /v1/orgs/{organizationId}/billing/promotion-code/preview
Content-Type: application/json

{
  "promotionCode": "FELIX20"
}

The response contains only display-safe terms and the matching local plan key, so clients can update that tier's trial length or effective price. Checkout and plan-change creation always revalidate the plaintext code; the preview is never commercial authority.

When an operator has marked a public custom code for suggestion, its use remains available, and the requesting owner and organization are still eligible for their first trial, GET /v1/orgs/{organizationId}/billing also returns suggestedPromotionCode. It contains the custom code, an opaque promotionCodeId, and the same display terms. The property is null when no suggestion applies, so clients should keep their ordinary manual-code layout. To apply the suggestion without copying it into the manual field, submit its ID as suggestedPromotionCodeId; the server revalidates it before opening Stripe.

Start Checkout with a local plan key and a client-generated idempotency key:

POST /v1/orgs/{organizationId}/billing/checkout-session
Content-Type: application/json

{
  "planKey": "pixatlas-pro-monthly",
  "idempotencyKey": "org-create-018f61e5-8bb2-7f10-b847-f5a355241584",
  "promotionCode": "ABCD-EFGH-JKLM-NPQR",
  "suggestedPromotionCodeId": null
}

Use the returned Stripe-hosted URL. The request does not accept a caller-owned Price ID, amount, success URL, cancel URL, Stripe Coupon ID, or Stripe Promotion Code ID. promotionCode is an optional PixAtlas customer offer code; suggestedPromotionCodeId is the mutually exclusive opaque ID supplied by the billing overview. Repeating the same request with the same organization, plan, and idempotency key returns the durable Checkout Session instead of creating another subscription.

An environment can attach an organization-and-plan-specific server discount to Checkout. Clients cannot submit, select, or override Stripe Coupon identifiers. An offer code may set the total eligible trial length or a percentage discount for an exact number of paid monthly periods or for the subscription lifetime. Codes can be configured for one, a fixed number, or unlimited successful uses. Checkout reserves one use; failed Session creation or a signed Checkout-expired event releases it, while signed completion reconciliation records the use.

Keep only the returned opaque sessionId in same-tab browser storage while navigating to Checkout. When the user explicitly returns without completing, reconcile that exact Session before reloading the plan list:

POST /v1/orgs/{organizationId}/billing/checkout-session/abandon
Content-Type: application/json

{
  "sessionId": "cs_..."
}

The server verifies organization ownership and asks Stripe to expire the open Session before releasing its trial and code reservations. A completed Session is not released and remains subject to signed webhook reconciliation. Clients must not persist the customer-entered offer code.

PixAtlas Free is a real recurring €0 Stripe subscription and still requires a reusable payment method. PixAtlas Pro uses the configured €99 monthly Price with 30 standard trial days from subscription creation. Checkout sends this as Stripe's relative trial_period_days=30 value only when both the organization and its initiating owner are eligible. The trial can be consumed once per organization and once per user. A user who already initiated a trial, or who owns another organization that has reserved or consumed one, receives a normal paid Pro Checkout without a second trial. The billing overview reports trialMonths: 0 for that user and organization so clients do not advertise an unavailable trial. Checkout repeats the eligibility check transactionally and does not trust the value previously displayed by a client. An eligible trial-duration code can replace 30 with a configured total such as 90 days; it never bypasses the organization-and-user trial rule. A finite percentage code starts after any trial and lasts exactly its configured paid-month duration; an unlimited percentage code remains discounted for the subscription lifetime. An active subscription can carry a validated percentage code into Stripe's hosted plan-change confirmation. Trial-duration codes remain limited to the first subscription Checkout because Stripe's hosted subscription-update flow cannot add a trial.

The Pro entitlement's seeded policy enables all current product capabilities except personal access token (PAT) API access; it allows ten accepted 3D-model Jobs per UTC month, 500 GiB default Document storage, Unlimited building capacity, integrated chat, and Whiteboards. The Price and exact entitlement version are selected by an environment-local server binding, not by the displayed euro amount.

Checkout does not copy the initiating PixAtlas user's email into Stripe. The email field remains editable so a company can enter its accounting address. After Checkout, current-object reconciliation stores that address as the organization billing email without changing any PixAtlas user account.

Wait for authoritative activation

The browser success redirect does not activate the organization. PixService verifies a signed Stripe event, stores it in a durable inbox, retrieves the current Stripe subscription, and then reconciles local state.

trialing, active, and past_due provision the exact entitlement version only when a reusable payment method is present. past_due remains usable while Stripe retry policy is in progress. Terminal, paused, incomplete, missing-card, or unknown-Price states do not provision ordinary use.

Poll the billing read endpoint after Checkout. A client should treat activationState: Active as authoritative. Until then, ordinary protected operations fail with the stable reason organization_subscription_required; billing activation and recovery remain available to authorized billing principals.

Manage a payment method

Create a short-lived Customer Portal session with:

POST /v1/orgs/{organizationId}/billing/portal-session

This requires OrganizationPaymentMethodsManage. The return URL is configured by the server, and the API returns only the Stripe-hosted session identifier, URL, and optional expiry.

Change the current plan

An organization with a current Stripe subscription can switch between active server-configured plans through a hosted Stripe confirmation flow:

POST /v1/orgs/{organizationId}/billing/plan-change-session
Content-Type: application/json

{
  "planKey": "pixatlas-free-monthly"
}

This requires OrganizationSubscriptionManage. The request accepts only the local plan key; PixService resolves the target Price and the organization's current Stripe subscription. Use the returned Customer Portal URL to let the customer review and confirm the change. Stripe applies the configured tax, proration, and invoice behavior. The return redirect is informational: wait for webhook reconciliation and read GET /v1/orgs/{organizationId}/billing until its planKey reflects the target plan.

Manage the billing contact

The organization billing email is intended for transactional invoice and subscription communication. A principal with OrganizationPaymentMethodsManage can update it in both PixAtlas and Stripe:

PUT /v1/orgs/{organizationId}/billing/contact
Content-Type: application/json

{
  "billingEmail": "rechnung@example.com",
  "expectedConcurrencyVersion": 1
}

Read the current version from billingEmailConcurrencyVersion in the billing status response. A stale version returns a conflict instead of overwriting a newer change. Stripe customer.updated events also synchronize later external changes. The raw address is not copied into webhook inbox, permission audit, or permission-change outbox payloads.

Understand manual enterprise organizations

A negotiated enterprise organization can be activated by a full PixService platform administrator without Stripe and without a payment method. Its activation source is ManualEnterprise, and the administrator assigns its customer-specific exact published entitlement version through the platform administration workflow.

While this source is current, Stripe Checkout and the Customer Portal are not available for the organization. Delayed Stripe events cannot replace its activation or entitlement. Contact PixService support to enter or leave manual enterprise management; changing an entitlement pin alone does not activate a pending organization.