Billing

Overview

NexusCommerce's billing system manages subscription plans, tracks usage-based metrics, and handles payment processing via Stripe. For self-hosted deployments, billing can be disabled entirely. For SaaS deployments, billing is a first-class feature with per-tenant subscription management, usage overage handling, and invoice generation.

Key Concepts

Plan — A subscription tier with defined feature access and usage limits. NexusCommerce ships with three default plans: Starter, Growth, and Enterprise.

Usage Metric — A measured platform resource that may be capped by plan or charged as an overage. Current usage metrics:

Overage — Usage above the plan limit, charged at a per-unit rate. For example, the Starter plan includes 1,000 AI jobs/month; additional jobs cost €0.02 each.

Billing Cycle — Monthly by default. Annual billing is available at a 20% discount.

Stripe Customer — Each NexusCommerce tenant is linked to one Stripe customer record. Subscriptions, payment methods, and invoices are managed in Stripe.

Getting Started

Navigate to Settings > Billing to manage your subscription.

For SaaS Platform Operators

Configure billing in the .env file:

STRIPE_SECRET_KEY=sk_live_...
STRIPE_WEBHOOK_SECRET=whsec_...
STRIPE_STARTER_PRICE_ID=price_...
STRIPE_GROWTH_PRICE_ID=price_...
STRIPE_ENTERPRISE_PRICE_ID=price_...
STRIPE_AI_JOB_OVERAGE_PRICE_ID=price_...

Create the Stripe products and prices in the Stripe dashboard, then set the price IDs in your environment. The billing.service.ts in the NestJS API handles all Stripe interactions.

For Tenants

If you are on the cloud-hosted version, your plan and billing details are managed through Settings > Billing.

Features

Subscription Overview

The Billing page shows:

• Current plan name and price
• Billing cycle (monthly / annual) and next renewal date
• Payment method (last 4 digits of card)
• Upcoming invoice estimate

Usage Meters

Real-time usage meters for each tracked metric:

Connected Marketplaces  ████████░░  4 / 5
AI Jobs (this month)    ██████████  1,247 / 1,000  (+247 overage)
API Calls (this month)  ████░░░░░░  42,300 / 100,000
Active SKUs             █████░░░░░  2,890 / 5,000
Team Members            ███░░░░░░░  3 / 10

Overage is shown in amber. Metrics approaching the limit (>80%) are shown in amber as a warning.

Plan Management

Upgrade — Click Upgrade Plan to move to a higher tier. Upgrade is prorated: you pay the difference for the remaining days in the current billing period.

Downgrade — Downgrade takes effect at the next billing cycle. If your current usage exceeds the lower plan's limits, a warning is shown. You must reduce usage before the downgrade takes effect.

Cancel — Cancellation takes effect at the end of the current billing period. Your data is retained for 30 days after cancellation.

Invoice History

A table of all past invoices:

Invoices are generated by Stripe and include a line-item breakdown of the base subscription plus any usage overages.

Payment Methods

Manage credit cards or SEPA direct debit mandates. Multiple payment methods can be stored; one is designated as the default.

Click Add Payment Method to open the Stripe payment element for secure card entry. NexusCommerce never stores raw card numbers — all payment processing is delegated to Stripe.

Default Plans

Overage rates:

• Additional AI jobs: €0.02/job
• Additional marketplaces (Growth plan): €25/marketplace/month

Stripe Webhook Handling

NexusCommerce processes the following Stripe events via the webhook handler at POST /api/billing/webhook:

Self-Hosted Billing Disable

For self-hosted deployments that do not need billing, set in .env:

BILLING_ENABLED=false

This removes the Billing section from Settings, disables usage enforcement, and skips all Stripe integrations. All features are available without subscription limits.

Configuration