--- title: Update Tenant Site slug: api-documentation/update-tenant-site docTags: createdAt: 2026-10-19T10:26:54.944Z --- { "id": "nko0j3AawdUZTYcl-laXt", "type": "api-oas-v2", "data": { "method": "PUT", "url": "https://api.upstartcommerce.com/v1/tenants/{tenantId}/sites/{siteId}", "servers": [ { "url": "https://api.upstartcommerce.com/v1/tenants/{tenantId}/sites/{siteId}" } ], "name": "Update Tenant Site", "description": "

This endpoint updates the details of a site associated with a tenant.

\n

Authorized permissions:

\n", "contentType": "application/json", "request": { "pathParameters": [ { "kind": "required", "name": "tenantId", "type": "string", "description": "Unique identifier for a given tenant." }, { "kind": "required", "name": "siteId", "type": "string", "description": "Unique identifier for the site." } ], "headerParameters": [ { "name": "accept", "type": "string", "kind": "optional", "description": "Generated from available response content types", "enum": [ "application/json" ], "default": "application/json" }, { "kind": "required", "name": "x-upstart-tenant", "type": "string", "description": "Tenant identifier associated with the site this call is for." } ], "queryParameters": [], "bodyDataParameters": [ { "kind": "required", "name": "body", "type": "object", "example": "{\"name\":\"US West Coast Store - Updated\",\"url\":\"west.acmeretail.com\",\"enabled\":false}", "description": "The request body should contain the updated values for the site.", "customType": "UpdateSite", "schema": [ { "name": "activationDate", "kind": "optional", "type": "string", "description": "

Update the date/time when this site becomes active. Set to a future date to schedule activation, or null to activate immediately. Changes take effect based on the new date. Must be in ISO 8601 format (UTC). Can be used to reschedule site launches.

", "example": "2025-02-01T00:00:00Z", "format": "date-time" }, { "name": "archived", "kind": "optional", "type": "boolean", "description": "

Set to true to archive (soft delete) this site. Archived sites are hidden from all operations but data is preserved. Cannot be undone - you must create a new site to restore functionality. Use this for permanently closing a storefront while retaining historical data for reporting.

", "example": false, "default": false }, { "name": "deactivationDate", "kind": "optional", "type": "string", "description": "

Update the date/time when this site becomes inactive. Set to a date to schedule deactivation, or null to remove any scheduled end date. Useful for extending temporary sites or scheduling permanent closures. Must be after activationDate if both are set.

", "example": "2025-12-31T23:59:59Z", "format": "date-time" }, { "name": "enabled", "kind": "optional", "type": "boolean", "description": "

Toggle to immediately enable/disable the site, overriding activation dates. Set to false for emergency shutdown or maintenance, true to re-enable. This is a quick control that doesn't affect activation/deactivation dates - useful for temporary operations.

", "example": true, "default": true }, { "name": "name", "kind": "required", "type": "string", "description": "Update the display name for the site. Should remain unique within the tenant for easy identification. Changes reflect immediately in all administrative interfaces and reports. Use descriptive names that clearly identify the site's purpose.", "example": "US West Coast Store - Updated" }, { "name": "url", "kind": "required", "type": "string", "description": "

Update the primary domain for this site. Must be unique across the entire platform. Changing the URL affects routing immediately - ensure DNS is configured before making this change. Does not include protocol (https:// is assumed). Coordinate with infrastructure team for domain changes.

", "example": "new-domain.acmeretail.com" } ], "modelRef": "#/components/schemas/UpdateSite", "isExpanded": true } ], "formDataParameters": [], "oAuthParameters": [ { "id": "NoChannelPortalAccess", "name": "NoChannelPortalAccess", "kind": "optional", "type": "http", "description": "

This authentication is required for clients to interact with any of the management APIs. Similar to 'LoggedIn', it indicates that the user has actually logged into the system, but in this case with a management role.

", "scheme": "bearer" }, { "id": "SessionIdAuth", "name": "X-Upstart-Session-Id", "kind": "optional", "type": "apiKey", "description": "

Legacy auth-mgmt session credential, obtained from user-svc POST /v1/user/session-login.

\n

Accepted as an alternative to a bearer token: every operation that lists both schemes takes either one.\nThis is what control-center sends -- it attaches X-Upstart-Session-Id and never an Authorization header.\nDeclaring it here is what stops Tapir refusing those requests at the transport for a missing Authorization.

", "in": "header" }, { "id": "ApiKeyAuth", "name": "X-UpStart-API-Key", "kind": "optional", "type": "apiKey", "description": "

Legacy auth-mgmt API key, for service and integration callers.

\n

Accepted as an alternative to a bearer token or session id: every operation that lists these schemes takes any one of them.\nDeclaring it here is what stops Tapir refusing API-key-only requests at the transport for a missing Authorization.

", "in": "header" } ], "cookieParameters": [] }, "responses": [ { "statusCode": "200", "description": "

Success-site updated.

", "jsonExample": "", "isExpanded": true, "schema": [ { "kind": "optional", "type": "object", "example": "{\"tenant\":\"acme001\",\"name\":\"Acme Retail Corporation\",\"email\":\"admin@acmeretail.com\",\"domain\":\"acme-retail\",\"sites\":[{\"id\":\"us-west-store\",\"name\":\"US West Coast Store - Updated\",\"url\":\"west.acmeretail.com\",\"enabled\":false,\"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.

", "customType": "TenantSummary", "schema": [ { "name": "name", "kind": "required", "type": "string", "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.", "example": "Acme Retail Corporation" }, { "name": "sites", "kind": "required", "type": "array", "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.

", "modelRef": "#/components/schemas/SiteData", "customType": "SiteData[]", "schema": [ { "name": "activationDate", "kind": "optional", "type": "string", "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).

", "example": "2024-01-15T00:00:00Z", "format": "date-time" }, { "name": "archived", "kind": "required", "type": "boolean", "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.

", "example": false, "default": false }, { "name": "deactivationDate", "kind": "optional", "type": "string", "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.

", "example": "2025-12-31T23:59:59Z", "format": "date-time" }, { "name": "enabled", "kind": "required", "type": "boolean", "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.

", "example": true, "default": true }, { "name": "id", "kind": "required", "type": "string", "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.

", "example": "us-west-store" }, { "name": "name", "kind": "required", "type": "string", "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.

", "example": "US West Coast Store" }, { "name": "url", "kind": "required", "type": "string", "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.

", "example": "westcoast.acmeretail.com" } ] }, { "name": "tenant", "kind": "required", "type": "string", "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.

", "example": "acme001" }, { "name": "email", "kind": "required", "type": "string", "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.

", "example": "admin@acmeretail.com" }, { "name": "domain", "kind": "optional", "type": "string", "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.

", "example": "acme-retail" } ], "modelRef": "#/components/schemas/TenantSummary", "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": "404", "description": "The requested resource was not found in the NoChannel system.", "jsonExample": "", "isExpanded": true, "schema": [ { "kind": "optional", "type": "object", "example": "{\"name\":\"ResourceNotFoundError\",\"code\":\"TENANT_NOT_FOUND\",\"detail\":\"The tenant with ID \\\"acme001\\\" was not found in the system.\",\"reason\":\"The tenant may have been deleted or you may not have permission to access it. Verify the tenant ID and your access rights.\"}", "description": "

Returned when the requested resource does not exist (HTTP 404).

", "customType": "NotFoundError", "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/NotFoundError", "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).

\n

Distinct 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": "lev7gpR4F2hujtV8SoKza", "language": "curl", "label": "cURL", "code": "curl --request PUT \\\n --url https://api.upstartcommerce.com/v1/tenants/{tenantId}/sites/{siteId} \\\n --header 'accept: application/json' \\\n --header 'content-type: application/json' \\\n --header 'x-upstart-tenant: string' \\\n --data '{\n \"enabled\": true,\n \"name\": \"US West Coast Store - Updated\",\n \"url\": \"new-domain.acmeretail.com\"\n }'" }, { "id": "lhGrm5sAzld2wT3uVFXvF", "language": "javascript", "label": "javascript", "code": "var myHeaders = new Headers();\nmyHeaders.append(\"accept\", \"application/json\");\nmyHeaders.append(\"content-type\", \"application/json\");\nmyHeaders.append(\"x-upstart-tenant\", \"string\");\n\nvar raw = JSON.stringify({\n \"enabled\": true,\n \"name\": \"US West Coast Store - Updated\",\n \"url\": \"new-domain.acmeretail.com\"\n});\n\nvar requestOptions = {\n method: 'PUT',\n headers: myHeaders,\n body: raw,\n redirect: 'follow'\n};\n\nfetch(\"https://api.upstartcommerce.com/v1/tenants/{tenantId}/sites/{siteId}\", requestOptions)\n .then(response => response.text())\n .then(result => console.log(result))\n .catch(error => console.log('error', error));" }, { "id": "QYdY9Pcfof8gk1UPlR9dD", "language": "ruby", "label": "Ruby", "code": "require \"uri\"\nrequire \"json\"\nrequire \"net/http\"\n\nurl = URI(\"https://api.upstartcommerce.com/v1/tenants/{tenantId}/sites/{siteId}\")\n\nhttps = Net::HTTP.new(url.host, url.port)\nhttps.use_ssl = true\n\nrequest = Net::HTTP::Put.new(url)\nrequest[\"accept\"] = \"application/json\"\nrequest[\"content-type\"] = \"application/json\"\nrequest[\"x-upstart-tenant\"] = \"string\"\nrequest.body = JSON.dump({\n \"enabled\": true,\n \"name\": \"US West Coast Store - Updated\",\n \"url\": \"new-domain.acmeretail.com\"\n})\n\nresponse = https.request(request)\nputs response.read_body\n" }, { "id": "9nDgjNVG7FJS5oaACMvXW", "language": "python", "label": "Python", "code": "import requests\nimport json\n\nurl = \"https://api.upstartcommerce.com/v1/tenants/{tenantId}/sites/{siteId}\"\n\npayload = json.dumps({\n \"enabled\": True,\n \"name\": \"US West Coast Store - Updated\",\n \"url\": \"new-domain.acmeretail.com\"\n})\nheaders = {\n 'accept': 'application/json',\n 'content-type': 'application/json',\n 'x-upstart-tenant': 'string'\n}\n\nresponse = requests.request(\"PUT\", url, headers=headers, data=payload)\n\nprint(response.text)\n" } ], "selectedLanguageId": "lev7gpR4F2hujtV8SoKza" }, "results": { "languages": [ { "id": "QgKkYZCXrT0iy1O50fmvf", "language": "200", "code": "// Success-site updated.\n{\n \"name\": \"Acme Retail Corporation\",\n \"sites\": [\n {\n \"activationDate\": \"2024-01-15T00:00:00Z\",\n \"archived\": false,\n \"deactivationDate\": \"2025-12-31T23:59:59Z\",\n \"enabled\": true,\n \"id\": \"us-west-store\",\n \"name\": \"US West Coast Store\",\n \"url\": \"westcoast.acmeretail.com\"\n }\n ],\n \"tenant\": \"acme001\",\n \"email\": \"admin@acmeretail.com\",\n \"domain\": \"acme-retail\"\n}" }, { "id": "X-boYO4oynIR_fYSrd5cy", "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": "g143pZ5jLP0j4VnLez0bF", "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": "uc9zVGs_D0SmwZGlgnIPN", "language": "404", "code": "// The requested resource was not found in the NoChannel system.\n{\n \"name\": \"\",\n \"code\": \"\",\n \"detail\": \"\",\n \"reason\": \"\"\n}" }, { "id": "zBP5s0Lco-mUwMjziuHHD", "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": "EYONxT9TWlPC4uP_pO2IC", "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": "u4KUQmkv4Ufo9IKtbC5IF", "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": "QgKkYZCXrT0iy1O50fmvf" } }, "children": [ { "text": "" } ] }