This endpoint creates a new tenant asynchronously. The tenant will be created and a verification email sent to the provided email address.
\nThis endpoint is unauthenticated. It is the entry point to self-service tenant signup, so the caller has neither a tenant nor credentials yet. The tenant is not usable until the emailed verification code is presented to verifyTenantRequest.
The tenant to create, with its name, domain and contact details.
", "customType": "CreateTenant", "schema": [ { "name": "name", "kind": "required", "type": "string", "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').
", "example": "Acme Retail Corporation" }, { "name": "email", "kind": "required", "type": "stringThe 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.
", "example": "admin@acmeretail.com", "format": "email" }, { "name": "domain", "kind": "optional", "type": "string", "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.
", "example": "acme-retail", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9-]{1,61}[a-zA-Z0-9]$" }, { "name": "sites", "kind": "required", "type": "array", "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.
", "modelRef": "#/components/schemas/CreateSite", "customType": "CreateSite[]", "schema": [ { "name": "activationDate", "kind": "optional", "type": "stringThe 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).
", "example": "2025-01-15T00:00:00Z", "format": "date-time" }, { "name": "archived", "kind": "optional", "type": "boolean", "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.
", "example": false, "default": false }, { "name": "deactivationDate", "kind": "optional", "type": "stringThe 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.
", "example": "2025-12-31T23:59:59Z", "format": "date-time" }, { "name": "enabled", "kind": "optional", "type": "boolean", "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.
", "example": true, "default": true }, { "name": "id", "kind": "optional", "type": "string", "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.
", "example": "us-west-store" }, { "name": "name", "kind": "required", "type": "string", "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').
", "example": "US West Coast Store" }, { "name": "url", "kind": "required", "type": "string", "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.
", "example": "westcoast.acmeretail.com" } ] }, { "name": "tenant", "kind": "optional", "type": "string", "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.
", "example": "acme001", "pattern": "^[0-9a-zA-Z]{0,40}$" } ], "modelRef": "#/components/schemas/CreateTenant", "isExpanded": true } ], "formDataParameters": [], "oAuthParameters": [], "cookieParameters": [] }, "responses": [ { "statusCode": "202", "description": "Success-tenant creation initiated. Verification email sent to the provided address.
", "jsonExample": "", "isExpanded": true }, { "statusCode": "400", "description": "The request contained information that the server was unable to process. Appropriate errors are provided in the response body.", "jsonExample": "", "isExpanded": true, "schema": [ { "kind": "optional", "type": "object", "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.
", "customType": "ValidationErrorResponse", "schema": [ { "name": "name", "kind": "required", "type": "string", "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.
", "example": "ValidationError" }, { "name": "code", "kind": "required", "type": "string", "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.
", "example": "INVALID_EMAIL_FORMAT" }, { "name": "detail", "kind": "optional", "type": "string", "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').
", "example": "The email field must be a valid email address. Received: \"invalid-email\"" } ], "modelRef": "#/components/schemas/ValidationErrorResponse", "isExpanded": true } ] }, { "statusCode": "401", "description": "The provided credentials were not valid for this endpoint. It may be that they are expired or that the user's roles are insufficient.", "jsonExample": "", "isExpanded": true, "schema": [ { "kind": "optional", "type": "object", "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).
", "customType": "UnauthorizedError", "schema": [ { "name": "name", "kind": "required", "type": "string", "description": "The high-level error category or type name.
" }, { "name": "code", "kind": "required", "type": "string", "description": "A specific error code identifying the exact error condition." }, { "name": "detail", "kind": "optional", "type": "string", "description": "A human-readable description of what went wrong.
" }, { "name": "reason", "kind": "optional", "type": "string", "description": "Optional additional context or suggested resolution." } ], "modelRef": "#/components/schemas/UnauthorizedError", "isExpanded": true } ] }, { "statusCode": "409", "description": "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.", "jsonExample": "", "isExpanded": true, "schema": [ { "kind": "optional", "type": "object", "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).
", "customType": "ConflictError", "schema": [ { "name": "name", "kind": "required", "type": "string", "description": "The high-level error category or type name.
" }, { "name": "code", "kind": "required", "type": "string", "description": "A specific error code identifying the exact error condition." }, { "name": "detail", "kind": "optional", "type": "string", "description": "A human-readable description of what went wrong.
" }, { "name": "reason", "kind": "optional", "type": "string", "description": "Optional additional context or suggested resolution." } ], "modelRef": "#/components/schemas/ConflictError", "isExpanded": true } ] }, { "statusCode": "422", "description": "The request was well-formed but contains semantic errors or violates business rules that prevent processing.
", "jsonExample": "", "isExpanded": true, "schema": [ { "kind": "optional", "type": "object", "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).
", "customType": "UnprocessableEntityError", "schema": [ { "name": "name", "kind": "required", "type": "string", "description": "The high-level error category or type name.
" }, { "name": "code", "kind": "required", "type": "string", "description": "A specific error code identifying the exact error condition." }, { "name": "detail", "kind": "optional", "type": "string", "description": "A human-readable description of what went wrong.
" }, { "name": "reason", "kind": "optional", "type": "string", "description": "Optional additional context or suggested resolution." } ], "modelRef": "#/components/schemas/UnprocessableEntityError", "isExpanded": true } ] }, { "statusCode": "500", "description": "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.
", "jsonExample": "", "isExpanded": true, "schema": [ { "kind": "optional", "type": "object", "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).
", "customType": "InternalServerError", "schema": [ { "name": "name", "kind": "required", "type": "string", "description": "The high-level error category or type name.
" }, { "name": "code", "kind": "required", "type": "string", "description": "A specific error code identifying the exact error condition." }, { "name": "detail", "kind": "optional", "type": "string", "description": "A human-readable description of what went wrong.
" }, { "name": "reason", "kind": "optional", "type": "string", "description": "Optional additional context or suggested resolution." } ], "modelRef": "#/components/schemas/InternalServerError", "isExpanded": true } ] }, { "statusCode": "503", "description": "A downstream dependency was unavailable, so the request could not be authorized or completed. The request may be retried.
", "jsonExample": "", "isExpanded": true, "schema": [ { "kind": "optional", "type": "object", "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).
\nDistinct from 401: the caller's credentials are fine. The service could not resolve the permissions\nrequired to authorize the request, so the outcome is unknown rather than denied. The request may be retried.
", "customType": "ServiceUnavailableError", "schema": [ { "name": "name", "kind": "required", "type": "string", "description": "The high-level error category or type name.
" }, { "name": "code", "kind": "required", "type": "string", "description": "A specific error code identifying the exact error condition." }, { "name": "detail", "kind": "optional", "type": "string", "description": "A human-readable description of what went wrong.
" }, { "name": "reason", "kind": "optional", "type": "string", "description": "Optional additional context or suggested resolution." } ], "modelRef": "#/components/schemas/ServiceUnavailableError", "isExpanded": true } ] } ], "hasXCodeSamples": false, "examples": { "languages": [ { "id": "d0sCLY0XS6cqxEGKqun0L", "language": "curl", "label": "cURL", "code": "curl --request POST \\\n --url https://api.upstartcommerce.com/v1/tenants/create \\\n --header 'accept: application/json' \\\n --header 'content-type: application/json' \\\n --data-raw '{\n \"name\": \"Acme Retail Corporation\",\n \"email\": \"admin@acmeretail.com\",\n \"sites\": [\n {\n \"enabled\": true,\n \"name\": \"US West Coast Store\",\n \"url\": \"westcoast.acmeretail.com\"\n }\n ]\n }'" }, { "id": "cBo2KiX2D3i_2W6C_d-9w", "language": "javascript", "label": "javascript", "code": "var myHeaders = new Headers();\nmyHeaders.append(\"accept\", \"application/json\");\nmyHeaders.append(\"content-type\", \"application/json\");\n\nvar raw = JSON.stringify({\n \"name\": \"Acme Retail Corporation\",\n \"email\": \"admin@acmeretail.com\",\n \"sites\": [\n {\n \"enabled\": true,\n \"name\": \"US West Coast Store\",\n \"url\": \"westcoast.acmeretail.com\"\n }\n ]\n});\n\nvar requestOptions = {\n method: 'POST',\n headers: myHeaders,\n body: raw,\n redirect: 'follow'\n};\n\nfetch(\"https://api.upstartcommerce.com/v1/tenants/create\", requestOptions)\n .then(response => response.text())\n .then(result => console.log(result))\n .catch(error => console.log('error', error));" }, { "id": "H6rUYKtQhSiYf7E41sClI", "language": "ruby", "label": "Ruby", "code": "require \"uri\"\nrequire \"json\"\nrequire \"net/http\"\n\nurl = URI(\"https://api.upstartcommerce.com/v1/tenants/create\")\n\nhttps = Net::HTTP.new(url.host, url.port)\nhttps.use_ssl = true\n\nrequest = Net::HTTP::Post.new(url)\nrequest[\"accept\"] = \"application/json\"\nrequest[\"content-type\"] = \"application/json\"\nrequest.body = JSON.dump({\n \"name\": \"Acme Retail Corporation\",\n \"email\": \"admin@acmeretail.com\",\n \"sites\": [\n {\n \"enabled\": true,\n \"name\": \"US West Coast Store\",\n \"url\": \"westcoast.acmeretail.com\"\n }\n ]\n})\n\nresponse = https.request(request)\nputs response.read_body\n" }, { "id": "OMxQ2YOViuNAZjCBvkflS", "language": "python", "label": "Python", "code": "import requests\nimport json\n\nurl = \"https://api.upstartcommerce.com/v1/tenants/create\"\n\npayload = json.dumps({\n \"name\": \"Acme Retail Corporation\",\n \"email\": \"admin@acmeretail.com\",\n \"sites\": [\n {\n \"enabled\": True,\n \"name\": \"US West Coast Store\",\n \"url\": \"westcoast.acmeretail.com\"\n }\n ]\n})\nheaders = {\n 'accept': 'application/json',\n 'content-type': 'application/json'\n}\n\nresponse = requests.request(\"POST\", url, headers=headers, data=payload)\n\nprint(response.text)\n" } ], "selectedLanguageId": "d0sCLY0XS6cqxEGKqun0L" }, "results": { "languages": [ { "id": "naoCfUcAXSgXG-ACHwAv4", "language": "202", "code": "// Success-tenant creation initiated. Verification email sent to the provided address.\n" }, { "id": "oxmVKmNxPlYV1h3eL6QO_", "language": "400", "code": "// The request contained information that the server was unable to process. Appropriate errors are provided in the response body.\n{\n \"name\": \"ValidationError\",\n \"code\": \"INVALID_EMAIL_FORMAT\",\n \"detail\": \"The email field must be a valid email address. Received: \\\"invalid-email\\\"\"\n}" }, { "id": "MO84jKgaTDVLXHup_4tA-", "language": "401", "code": "// The provided credentials were not valid for this endpoint. It may be that they are expired or that the user's roles are insufficient.\n{\n \"name\": \"\",\n \"code\": \"\",\n \"detail\": \"\",\n \"reason\": \"\"\n}" }, { "id": "tTE-4INZ9awosXFIvpYxQ", "language": "409", "code": "// 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.\n{\n \"name\": \"\",\n \"code\": \"\",\n \"detail\": \"\",\n \"reason\": \"\"\n}" }, { "id": "FGlTv1bQvILe7_xHHLa2E", "language": "422", "code": "// The request was well-formed but contains semantic errors or violates business rules that prevent processing.\n{\n \"name\": \"\",\n \"code\": \"\",\n \"detail\": \"\",\n \"reason\": \"\"\n}" }, { "id": "BsLUyS-BsqK3ixfgXik2x", "language": "500", "code": "// 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.\n{\n \"name\": \"\",\n \"code\": \"\",\n \"detail\": \"\",\n \"reason\": \"\"\n}" }, { "id": "uzJu90-Q68aNdRcR90vWK", "language": "503", "code": "// A downstream dependency was unavailable, so the request could not be authorized or completed. The request may be retried.\n{\n \"name\": \"\",\n \"code\": \"\",\n \"detail\": \"\",\n \"reason\": \"\"\n}" } ], "selectedLanguageId": "naoCfUcAXSgXG-ACHwAv4" } }, "children": [ { "text": "" } ] }