Introduction

12 min

Overview

The Tenant Management API provides complete control over tenant provisioning, configuration, and lifecycle management within the NoChannel e-commerce platform. This API is the foundation of the platform's multi-tenancy architecture, enabling you to create and manage isolated business environments with their own sites, configurations, and administrative access.

What is a Tenant?

A tenant represents a complete, isolated e-commerce business within the NoChannel platform. Each tenant has:

Unique Identity: A distinct tenant ID and domain for administrative portal access

Data Isolation: Complete separation from other tenants' data and operations

One or More Sites: Customer-facing storefronts or sales channels

Custom Configuration: Tenant-specific settings, integrations, and branding

Independent Administration: Separate user management and access control

Think of a tenant as a complete e-commerce company or business unit. For example, "Acme Retail" would be a tenant that might operate multiple storefronts (sites) like "Acme US Store", "Acme EU Store", and "Acme Mobile App".

What is a Site?

A site represents a customer-facing storefront or sales channel within a tenant. Sites enable multi-channel commerce where a single business can operate:

Multiple Storefronts: Separate stores for different regions, brands, or customer segments

Multiple Channels: Web, mobile, B2B portals, marketplace integrations

Independent Configuration: Each site can have its own URL, activation schedule, and site-specific settings

Shared Resources: Sites within a tenant share catalog, customer data, and backend systems

For example, a tenant "Global Retail Corp" might have sites for "US Store" (shop-us.globalretail.com), "UK Store" (shop-uk.globalretail.com), and "B2B Portal" (b2b.globalretail.com).

Key Concepts

Multi-Tenancy Architecture

The platform uses a true multi-tenant architecture where each tenant's data is completely isolated. Tenants cannot access or interfere with each other's operations, ensuring security and data privacy. This enables:

White-label Solutions: Each tenant can brand their administrative portal and storefronts independently

Scalability: Add new businesses without infrastructure changes

Cost Efficiency: Shared platform infrastructure with isolated business logic

Domain Management

Each tenant receives a unique domain (subdomain) for accessing their administrative portal. This domain:

Must be globally unique across all tenants

Forms the admin portal URL (e.g., acme.upstartcommerce.com)

Cannot be changed easily once set (requires coordination with users)

Is separate from site URLs (which are customer-facing)

Site Lifecycle Management

Sites support sophisticated lifecycle controls:

Activation Dates: Schedule when a site becomes accessible

Deactivation Dates: Schedule when a site closes

Enabled Flag: Immediate manual override to enable/disable

Archive Status: Soft-delete sites while preserving historical data

These controls enable use cases like seasonal stores, scheduled launches, maintenance windows, and gradual rollouts.

Common Use Cases

Creating a New Business Tenant

Create a tenant with initial site(s) using POST /v1/tenants/create

Tenant admin receives verification email

Admin completes verification to activate the tenant

Begin configuring catalog, users, and integrations

Managing Multiple Storefronts

Create additional sites for a tenant using POST /v1/tenants/{tenantId}/sites

Configure site-specific settings (URLs, activation dates)

Apply site-specific configurations (payment gateways, shipping methods)

Monitor and update sites independently

Scheduled Site Launch

Create site with future activationDate

Configure all site settings while inactive

Site automatically becomes accessible at scheduled time

Optionally set deactivationDate for limited-time stores

Emergency Site Shutdown

Update site with enabled: false using PUT /v1/tenants/{tenantId}/sites/{siteId}

Site becomes immediately inaccessible (independent of activation dates)

Re-enable when issue is resolved with enabled: true

Tenant Rebranding

Update tenant name and/or domain using PUT /v1/tenants/{tenantId}

Coordinate with users regarding new portal URL if domain changed

Site URLs remain unchanged (update separately if needed)

API Organization

The API is organized into these functional areas:

Tenant Operations

Create, retrieve, update, and delete tenants

Manage tenant verification and activation

Query tenants by ID or domain

Retrieve audit history for compliance

Site Operations

Create and manage sites within a tenant

Control site lifecycle (activation, deactivation, archival)

Update site configuration and URLs

Query site status and configuration

Configuration Management

Retrieve Cloudinary media configuration for tenants

Site-specific configuration through configuration records (see Configuration Management API)

Authentication & Authorization

All endpoints require authentication via JWT bearer tokens. Most operations require the NoChannelPortalAccess security scheme, indicating administrative access.

Many endpoints also require the x-upstart-tenant header to specify which tenant context the operation applies to. This ensures operations are scoped correctly in the multi-tenant environment.

Required Permissions

Operations document their required permissions (e.g., tenant.create, tenant.read, tenant.update, tenant.delete). Ensure your access token includes the necessary permissions for the operations you need to perform.

Getting Started

To get started with the Tenant API:

Obtain Authentication: Get a JWT token with appropriate permissions

Create Your First Tenant: Use POST /v1/tenants/create with tenant details and at least one site

Verify the Tenant: Complete email verification using the verification code

Retrieve Tenant Details: Use GET /v1/tenants/{tenantId} to see complete tenant configuration

Manage Sites: Add, update, or configure sites as needed

Refer to the endpoint documentation below for detailed request/response schemas, examples, and error handling.