Create Tenant

1 min

POST

https://api.upstartcommerce.com/v1/tenants

Warning: Deprecated This endpoint creates a new tenant.

Authorized permissions:

tenant.create

Header Parameters

x-upstart-tenantstringrequired
Description
Tenant identifier associated with the site this call is for.

Body Parameters

bodyCreateTenantrequired
Example
```
{
  "name": "Acme Retail Corporation",
  "email": "[email protected]",
  "domain": "acme-retail",
  "tenant": "acme001",
  "sites": [
    {
      "name": "Main Store",
      "url": "shop.acmeretail.com",
      "enabled": true,
      "activationDate": "2024-01-15T00:00:00Z"
    }
  ]
}
```
Description
The tenant to create, with its name, domain and contact details.
- namestringrequired
  Example
  Acme Retail Corporation
  Description
  The business or organization name for this tenant. This appears in the administrative portal header, emails, and throughout the system. Should be the legal business name or recognizable brand name (e.g., 'Acme Retail Corporation', 'Bob's Hardware').
- emailstring<email>required
  Example
  [email protected]
  Description
  The email address for the initial administrator account. This user will receive a verification email and will have full administrative access to the tenant. Must be a valid, deliverable email address. This becomes the primary contact for the tenant.
  Format
  email
- domainstring
  Example
  acme-retail
  Description
  The subdomain prefix used to access the tenant's administrative portal (e.g., 'acme' becomes 'acme.upstartcommerce.com'). Must be unique across all tenants, contain only alphanumeric characters and hyphens, start and end with alphanumeric characters, and be between 3-63 characters. Cannot be changed after creation.
  Pattern
  ^[a-zA-Z0-9][a-zA-Z0-9-]{1,61}[a-zA-Z0-9]$
- sitesCreateSite[]required
  Description
  An array of sites (storefronts/channels) to create for this tenant. At least one site is required. Each site represents a customer-facing storefront with its own URL and configuration. You can add more sites later through the site management APIs.
  - activationDatestring<date-time>
    Example
    2025-01-15T00:00:00Z
    Description
    The date and time when this site becomes active and accessible to customers. If not specified, the site is activated immediately upon creation. Use this to schedule future site launches. Must be in ISO 8601 format (UTC).
    Format
    date-time
  - archivedboolean
    Description
    Whether this site is archived (soft deleted). Archived sites are hidden from normal operations but data is retained for historical purposes. Defaults to false for new sites. Set to true only when migrating historical data.
    Default
    false
  - deactivationDatestring<date-time>
    Example
    2025-12-31T23:59:59Z
    Description
    The date and time when this site will automatically become inactive. Optional - if not set, the site remains active indefinitely. Useful for temporary sites, seasonal stores, or scheduled site closures. Must be after activationDate.
    Format
    date-time
  - enabledboolean
    Example
    true
    Description
    Controls whether the site is currently enabled for operations, independent of activation dates. Use this as a manual override to quickly enable/disable a site. When false, the site is inaccessible even if within activation dates. Defaults to true.
    Default
    true
  - idstring
    Example
    us-west-store
    Description
    Optional custom identifier for the site. If not provided, a unique identifier will be automatically generated. Must be unique within the tenant. Use lowercase alphanumeric characters and hyphens. Once set, this ID cannot be changed.
  - namestringrequired
    Example
    US West Coast Store
    Description
    The display name for the site, shown in administrative interfaces and reports. Should be descriptive and unique within the tenant for easy identification (e.g., 'US West Coast Store', 'Mobile App Channel', 'B2B Portal').
  - urlstringrequired
    Example
    westcoast.acmeretail.com
    Description
    The primary URL/domain where this site is accessible to customers. Should include the full domain without protocol (e.g., 'store.example.com' not 'https://store.example.com'). Must be unique across all tenants in the platform.
- tenantstring
  Example
  acme001
  Description
  Optional custom tenant identifier. If not provided, one will be auto-generated. Must be globally unique, contain only alphanumeric characters, and be max 40 characters. Use this to maintain consistent identifiers across environments or during migrations. Once set, cannot be changed.
  Pattern
  ^[0-9a-zA-Z]{0,40}$

Responses

201

Success-tenant created successfully.

TenantSummary
Example
```
{
  "tenant": "acme001",
  "name": "Acme Retail Corporation",
  "email": "[email protected]",
  "domain": "acme-retail",
  "sites": [
    {
      "id": "main-store",
      "name": "Main Store",
      "url": "shop.acmeretail.com",
      "enabled": true,
      "archived": false,
      "activationDate": "2024-01-15T00:00:00Z"
    }
  ]
}
```
Description
Complete tenant information including all associated sites. Returned by tenant creation, update, and retrieval operations. Provides a full view of a tenant's configuration and all its storefronts/channels.
- namestringrequired
  Example
  Acme Retail Corporation
  Description
  The business or organization name for this tenant. Displayed in administrative interfaces and used for identification. Typically the legal business name or primary brand name.
- sitesSiteData[]required
  Description
  Array of all sites (storefronts/channels) associated with this tenant. Each site represents a customer-facing storefront with its own URL and configuration. A tenant must have at least one site. Sites are returned in creation order.
  - activationDatestring<date-time>
    Example
    2024-01-15T00:00:00Z
    Description
    The date and time when this site became (or will become) active and accessible to customers. Sites before this date are not accessible. null indicates the site is active from creation. Always in ISO 8601 format (UTC).
    Format
    date-time
  - archivedbooleanrequired
    Description
    Indicates the site has been soft-deleted and is retained only for historical/audit purposes. Archived sites are excluded from all queries and operations. Cannot be unarchived - create a new site instead. This is different from 'enabled' which is a temporary disable.
    Default
    false
  - deactivationDatestring<date-time>
    Example
    2025-12-31T23:59:59Z
    Description
    The date and time after which this site becomes inactive and inaccessible. null means the site has no scheduled end date and remains active indefinitely (subject to 'enabled' flag). Useful for temporary sites or scheduled closures.
    Format
    date-time
  - enabledbooleanrequired
    Example
    true
    Description
    Manual override flag that immediately enables/disables the site, independent of activation dates. When false, the site is inaccessible even if within active dates. Use this for emergency shutdowns or maintenance windows. Can be toggled at any time without affecting activation dates.
    Default
    true
  - idstringrequired
    Example
    us-west-store
    Description
    The unique identifier for this site within the tenant. Immutable once created. Used in API calls, configuration records, and for associating data with specific sites. Format is alphanumeric with hyphens.
  - namestringrequired
    Example
    US West Coast Store
    Description
    The display name for the site shown in administrative interfaces, reports, and internal systems. Should be descriptive and unique within the tenant for easy identification by administrators.
  - urlstringrequired
    Example
    westcoast.acmeretail.com
    Description
    The primary domain where customers access this site. Must be unique across the entire platform. Does not include protocol (https:// is assumed). This URL is used for routing and site identification.
- tenantstringrequired
  Example
  acme001
  Description
  The unique identifier for this tenant. Immutable once created. Use this value in the x-upstart-tenant header for all tenant-scoped API operations. Must be unique across the entire platform.
- emailstringrequired
  Example
  [email protected]
  Description
  The primary contact email address for this tenant. Used for administrative notifications, password resets, and system communications. Typically belongs to the primary administrator or technical contact.
- domainstring
  Example
  acme-retail
  Description
  The domain prefix/subdomain used to access this tenant's administrative portal (e.g., 'acme' for 'acme.upstartcommerce.com'). Unique across all tenants. Cannot be changed after creation. This is different from site URLs which are customer-facing.

400The request contained information that the server was unable to process. Appropriate errors are provided in the response body.

ValidationErrorResponse
Example
```
{
  "name": "ValidationError",
  "code": "INVALID_EMAIL_FORMAT",
  "detail": "The email field must be a valid email address. Received: \"invalid-email\""
}
```
Description
Error response returned when request validation fails (HTTP 400). Contains details about which fields failed validation and why. Used for client-side error display and form validation feedback.
- namestringrequired
  Example
  ValidationError
  Description
  The error type, typically 'ValidationError' for all validation failures. Use this to distinguish validation errors from other error types in your error handling logic.
- codestringrequired
  Example
  INVALID_EMAIL_FORMAT
  Description
  A validation-specific error code indicating the validation rule that failed. Examples include 'REQUIRED_FIELD_MISSING', 'INVALID_FORMAT', 'VALUE_OUT_OF_RANGE', 'DUPLICATE_VALUE'. Use for specific handling of different validation scenarios.
- detailstring
  Example
  The email field must be a valid email address. Received: "invalid-email"
  Description
  Human-readable validation error message describing which field(s) failed and why. Should be specific enough for developers to fix the issue. May include field paths for nested objects (e.g., 'sites[0].url is not a valid domain').

401The provided credentials were not valid for this endpoint. It may be that they are expired or that the user's roles are insufficient.

UnauthorizedError
Example
```
{
  "name": "AuthorizationError",
  "code": "INSUFFICIENT_PERMISSIONS",
  "detail": "User does not have the required tenant.create permission to perform this operation.",
  "reason": "Your access token does not include the necessary permissions. Contact your administrator to request access."
}
```
Description
Returned when credentials are missing, expired or insufficient (HTTP 401).
- namestringrequired
  Description
  The high-level error category or type name.
- codestringrequired
  Description
  A specific error code identifying the exact error condition.
- detailstring
  Description
  A human-readable description of what went wrong.
- reasonstring
  Description
  Optional additional context or suggested resolution.

409The request conflicts with the current state of the resource. This typically occurs when trying to create a resource that already exists or when there's a conflict with business rules.

ConflictError
Example
```
{
  "name": "ConflictError",
  "code": "TENANT_DOMAIN_ALREADY_EXISTS",
  "detail": "A tenant with the domain \"acme-retail\" already exists in the system.",
  "reason": "Tenant domains must be globally unique. Please choose a different domain name for your tenant."
}
```
Description
Returned when the request conflicts with the current resource state (HTTP 409).
- namestringrequired
  Description
  The high-level error category or type name.
- codestringrequired
  Description
  A specific error code identifying the exact error condition.
- detailstring
  Description
  A human-readable description of what went wrong.
- reasonstring
  Description
  Optional additional context or suggested resolution.

422

The request was well-formed but contains semantic errors or violates business rules that prevent processing.

UnprocessableEntityError
Example
```
{
  "name": "UnprocessableEntityError",
  "code": "INVALID_SITE_CONFIGURATION",
  "detail": "The deactivationDate must be after the activationDate.",
  "reason": "A site cannot be deactivated before it is activated. Please adjust the dates so that deactivation occurs after activation."
}
```
Description
Returned when the request is well-formed but violates business rules (HTTP 422).
- namestringrequired
  Description
  The high-level error category or type name.
- codestringrequired
  Description
  A specific error code identifying the exact error condition.
- detailstring
  Description
  A human-readable description of what went wrong.
- reasonstring
  Description
  Optional additional context or suggested resolution.

500

An unexpected internal server error occurred. The request may be retried, and if the problem persists, contact support with the traceId from the error response.

InternalServerError
Example
```
{
  "name": "InternalServerError",
  "code": "UNEXPECTED_ERROR",
  "detail": "An unexpected error occurred while processing your request.",
  "reason": "Our team has been notified. Please try again, and if the problem persists, contact support with trace ID: 550e8400-e29b-41d4-a716-446655440000"
}
```
Description
Returned for an unexpected server-side failure (HTTP 500).
- namestringrequired
  Description
  The high-level error category or type name.
- codestringrequired
  Description
  A specific error code identifying the exact error condition.
- detailstring
  Description
  A human-readable description of what went wrong.
- reasonstring
  Description
  Optional additional context or suggested resolution.

503

A downstream dependency was unavailable, so the request could not be authorized or completed. The request may be retried.

ServiceUnavailableError
Example
```
{
  "name": "Service Unavailable",
  "code": "UNKNOWN",
  "detail": "Permission resolution is unavailable, please retry",
  "reason": "A dependency required to authorize this request is temporarily unreachable. Please retry shortly."
}
```
Description
Returned when a downstream dependency this request needed is unavailable (HTTP 503).

Distinct from 401: the caller's credentials are fine. The service could not resolve the permissions required to authorize the request, so the outcome is unknown rather than denied. The request may be retried.
- namestringrequired
  Description
  The high-level error category or type name.
- codestringrequired
  Description
  A specific error code identifying the exact error condition.
- detailstring
  Description
  A human-readable description of what went wrong.
- reasonstring
  Description
  Optional additional context or suggested resolution.

curl

curl --request POST \
     --url https://api.upstartcommerce.com/v1/tenants \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --header 'x-upstart-tenant: string' \
     --data-raw '{
     "name": "Acme Retail Corporation",
     "email": "[email protected]",
     "sites": [
     {
     "enabled": true,
     "name": "US West Coast Store",
     "url": "westcoast.acmeretail.com"
     }
     ]
     }'

javascript

var myHeaders = new Headers();
myHeaders.append("accept", "application/json");
myHeaders.append("content-type", "application/json");
myHeaders.append("x-upstart-tenant", "string");

var raw = JSON.stringify({
   "name": "Acme Retail Corporation",
   "email": "[email protected]",
   "sites": [
      {
         "enabled": true,
         "name": "US West Coast Store",
         "url": "westcoast.acmeretail.com"
      }
   ]
});

var requestOptions = {
   method: 'POST',
   headers: myHeaders,
   body: raw,
   redirect: 'follow'
};

fetch("https://api.upstartcommerce.com/v1/tenants", requestOptions)
   .then(response => response.text())
   .then(result => console.log(result))
   .catch(error => console.log('error', error));

ruby

require "uri"
require "json"
require "net/http"

url = URI("https://api.upstartcommerce.com/v1/tenants")

https = Net::HTTP.new(url.host, url.port)
https.use_ssl = true

request = Net::HTTP::Post.new(url)
request["accept"] = "application/json"
request["content-type"] = "application/json"
request["x-upstart-tenant"] = "string"
request.body = JSON.dump({
   "name": "Acme Retail Corporation",
   "email": "[email protected]",
   "sites": [
      {
         "enabled": true,
         "name": "US West Coast Store",
         "url": "westcoast.acmeretail.com"
      }
   ]
})

response = https.request(request)
puts response.read_body

python

import requests
import json

url = "https://api.upstartcommerce.com/v1/tenants"

payload = json.dumps({
   "name": "Acme Retail Corporation",
   "email": "[email protected]",
   "sites": [
      {
         "enabled": True,
         "name": "US West Coast Store",
         "url": "westcoast.acmeretail.com"
      }
   ]
})
headers = {
   'accept': 'application/json',
   'content-type': 'application/json',
   'x-upstart-tenant': 'string'
}

response = requests.request("POST", url, headers=headers, data=payload)

print(response.text)

201

// Success-tenant created successfully.
{
  "name": "Acme Retail Corporation",
  "sites": [
    {
      "activationDate": "2024-01-15T00:00:00Z",
      "archived": false,
      "deactivationDate": "2025-12-31T23:59:59Z",
      "enabled": true,
      "id": "us-west-store",
      "name": "US West Coast Store",
      "url": "westcoast.acmeretail.com"
    }
  ],
  "tenant": "acme001",
  "email": "[email protected]",
  "domain": "acme-retail"
}

400

// The request contained information that the server was unable to process. Appropriate errors are provided in the response body.
{
  "name": "ValidationError",
  "code": "INVALID_EMAIL_FORMAT",
  "detail": "The email field must be a valid email address. Received: \"invalid-email\""
}

401

// The provided credentials were not valid for this endpoint. It may be that they are expired or that the user's roles are insufficient.
{
  "name": "",
  "code": "",
  "detail": "",
  "reason": ""
}

409

// The request conflicts with the current state of the resource. This typically occurs when trying to create a resource that already exists or when there's a conflict with business rules.
{
  "name": "",
  "code": "",
  "detail": "",
  "reason": ""
}

422

// The request was well-formed but contains semantic errors or violates business rules that prevent processing.
{
  "name": "",
  "code": "",
  "detail": "",
  "reason": ""
}

500

// An unexpected internal server error occurred. The request may be retried, and if the problem persists, contact support with the traceId from the error response.
{
  "name": "",
  "code": "",
  "detail": "",
  "reason": ""
}

503

// A downstream dependency was unavailable, so the request could not be authorized or completed. The request may be retried.
{
  "name": "",
  "code": "",
  "detail": "",
  "reason": ""
}