This endpoint creates a new cfg record.
\nAuthorized permissions:
\ntenant.cfg.modifyThe configuration record to create, and the template it is based on.
", "customType": "CreateCfgRecord", "schema": [ { "name": "recordId", "kind": "optional", "type": "string", "description": "Optional custom identifier for this record. If not provided, a unique ID will be auto-generated. Must be unique within the tenant. Use descriptive IDs for easier management (e.g., 'cybersource-us-prod', 'cloudinary-main'). Cannot be changed after creation.
", "example": "payment-cybersource-us-prod" }, { "name": "templateId", "kind": "required", "type": "string", "description": "The identifier of the configuration template to use as the schema for this record. Must reference an existing, enabled template. The record's data field must conform to the template's propertiesDescriptors schema. Use GET /tenants/cfg/templates to find available templates.
", "example": "payment-cybersource" }, { "name": "siteIds", "kind": "optional", "type": "array", "description": "Optional list of site IDs this configuration applies to. When empty or omitted, the record applies to all sites within the tenant (tenant-wide default). Use site scoping to create site-specific configurations (e.g., different payment credentials per store). Site-specific records override tenant-wide records.
", "example": "[\"us-west-store\",\"us-east-store\"]", "itemType": "string", "customType": "string[]", "itemExample": "", "itemDefault": "" }, { "name": "tags", "kind": "optional", "type": "array", "description": "Optional tags for organizing and filtering records. Use for environment classification (dev, staging, prod), security levels (pci-sensitive), purposes (payment, shipping), or custom categories. Tags enable efficient querying and management of large configuration sets.
", "example": "[\"production\",\"payment-gateway\",\"pci-sensitive\",\"us-region\"]", "itemType": "string", "customType": "string[]", "itemExample": "", "itemDefault": "" }, { "name": "name", "kind": "required", "type": "string", "description": "Human-readable name for this configuration record. Should be descriptive and unique within the tenant to facilitate identification in UIs, logs, and reports. Use clear, specific names that indicate purpose and environment (e.g., 'Cybersource US Production Credentials', 'Cloudinary Development Media Storage').
", "example": "Cybersource US Production Credentials" }, { "name": "data", "kind": "required", "type": "object", "description": "The actual configuration data as a JSON object. Must conform to the schema defined in the associated template's propertiesDescriptors. Contains integration-specific settings, API credentials, URLs, and other configuration values. Will be validated against the template schema before creation.
", "example": "{\"merchantId\":\"acme_us_prod\",\"apiKey\":\"sk_live_abc123xyz789\",\"apiUrl\":\"https://api.cybersource.com\",\"currency\":\"USD\",\"testMode\":false}", "schema": [] }, { "name": "enabled", "kind": "required", "type": "boolean", "description": "Whether this configuration record is initially active and should be used by the system. Set to false to create configurations in a disabled state for testing before enabling. Can be toggled later without deleting the configuration data. Useful for staged rollouts.", "example": true }, { "name": "accessControl", "kind": "optional", "type": "object", "description": "Access control settings that determine which operations can be performed on a configuration resource. This enables fine-grained permission management for configuration templates and records.
", "modelRef": "#/components/schemas/CfgAccessControl", "customType": "CfgAccessControl", "schema": [ { "name": "read", "kind": "required", "type": "boolean", "description": "Whether the configuration resource can be read/viewed. When false, the resource is hidden from queries and detail views unless the user has elevated privileges. Typically used for sensitive configurations.
", "example": true }, { "name": "modify", "kind": "required", "type": "boolean", "description": "Whether the configuration resource can be modified (updated or deleted). When false, the resource becomes read-only and cannot be changed through the API. Useful for protecting production configurations.
", "example": false } ] } ], "modelRef": "#/components/schemas/CreateCfgRecord", "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" } ], "cookieParameters": [] }, "responses": [ { "statusCode": "201", "description": "Success-record created successfully. Returns the generated record ID.
", "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\":\"SCHEMA_VALIDATION_FAILED\",\"detail\":\"Configuration data validation failed: data.apiKey is required but was not provided. Expected string with minimum length 32.\"}", "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. Common when configuration data doesn't match template schema.
", "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', 'SCHEMA_VALIDATION_FAILED', 'TEMPLATE_NOT_FOUND'. Use for specific handling of different validation scenarios.
", "example": "SCHEMA_VALIDATION_FAILED" }, { "name": "detail", "kind": "optional", "type": "string", "description": "Human-readable validation error message describing which field(s) failed and why. Includes specific details about what was expected vs what was provided. For schema validation failures, may include JSON path to the invalid field (e.g., 'data.apiKey is required but was not provided').
", "example": "Configuration data validation failed: data.apiKey is required but was not provided. Expected string with minimum length 32." } ], "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.cfg.modify permission to perform this operation.\",\"reason\":\"Your access token does not include the necessary permissions. Contact your administrator to request access.\"}", "description": "Standard error response returned when a request fails due to business logic, authorization, or system errors. Provides structured information for debugging and user-facing error messages.
", "customType": "ErrorResponse", "schema": [ { "name": "name", "kind": "required", "type": "string", "description": "The high-level error category or type name. This is a machine-readable identifier for the class of error (e.g., 'AuthorizationError', 'ResourceNotFoundError', 'ValidationError'). Use this for programmatic error handling.
", "example": "ResourceNotFoundError" }, { "name": "code", "kind": "required", "type": "string", "description": "A specific error code identifying the exact error condition. More granular than name, this code can be used for precise error handling and localization. Format is typically uppercase with underscores (e.g., 'TEMPLATE_NOT_FOUND', 'INSUFFICIENT_PERMISSIONS').
", "example": "TEMPLATE_NOT_FOUND" }, { "name": "detail", "kind": "required", "type": "string", "description": "A human-readable description of the error, including context about what went wrong. This message is suitable for display to end users or inclusion in logs. May include specifics like resource IDs or field names.
", "example": "The configuration template with ID \"payment-stripe\" was not found in the system." }, { "name": "reason", "kind": "optional", "type": "string", "description": "Optional additional context explaining why the error occurred or what action the user should take. May include suggestions for resolution, links to documentation, or details about system state that led to the error.
", "example": "The template may have been deleted or you may not have permission to access it. Verify the template ID using GET /tenants/cfg/templates." } ], "modelRef": "#/components/schemas/ErrorResponse", "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\":\"TEMPLATE_ID_ALREADY_EXISTS\",\"detail\":\"A configuration template with the ID \\\"payment-cybersource\\\" already exists in the tenant.\",\"reason\":\"Template IDs must be unique within a tenant. Please choose a different template ID or update the existing template.\"}", "description": "Standard error response returned when a request fails due to business logic, authorization, or system errors. Provides structured information for debugging and user-facing error messages.
", "customType": "ErrorResponse", "schema": [ { "name": "name", "kind": "required", "type": "string", "description": "The high-level error category or type name. This is a machine-readable identifier for the class of error (e.g., 'AuthorizationError', 'ResourceNotFoundError', 'ValidationError'). Use this for programmatic error handling.
", "example": "ResourceNotFoundError" }, { "name": "code", "kind": "required", "type": "string", "description": "A specific error code identifying the exact error condition. More granular than name, this code can be used for precise error handling and localization. Format is typically uppercase with underscores (e.g., 'TEMPLATE_NOT_FOUND', 'INSUFFICIENT_PERMISSIONS').
", "example": "TEMPLATE_NOT_FOUND" }, { "name": "detail", "kind": "required", "type": "string", "description": "A human-readable description of the error, including context about what went wrong. This message is suitable for display to end users or inclusion in logs. May include specifics like resource IDs or field names.
", "example": "The configuration template with ID \"payment-stripe\" was not found in the system." }, { "name": "reason", "kind": "optional", "type": "string", "description": "Optional additional context explaining why the error occurred or what action the user should take. May include suggestions for resolution, links to documentation, or details about system state that led to the error.
", "example": "The template may have been deleted or you may not have permission to access it. Verify the template ID using GET /tenants/cfg/templates." } ], "modelRef": "#/components/schemas/ErrorResponse", "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\":\"TEMPLATE_IN_USE\",\"detail\":\"Cannot delete template \\\"payment-cybersource\\\" because 5 configuration records are still using it.\",\"reason\":\"Delete or migrate all records using this template before deleting the template itself.\"}", "description": "Standard error response returned when a request fails due to business logic, authorization, or system errors. Provides structured information for debugging and user-facing error messages.
", "customType": "ErrorResponse", "schema": [ { "name": "name", "kind": "required", "type": "string", "description": "The high-level error category or type name. This is a machine-readable identifier for the class of error (e.g., 'AuthorizationError', 'ResourceNotFoundError', 'ValidationError'). Use this for programmatic error handling.
", "example": "ResourceNotFoundError" }, { "name": "code", "kind": "required", "type": "string", "description": "A specific error code identifying the exact error condition. More granular than name, this code can be used for precise error handling and localization. Format is typically uppercase with underscores (e.g., 'TEMPLATE_NOT_FOUND', 'INSUFFICIENT_PERMISSIONS').
", "example": "TEMPLATE_NOT_FOUND" }, { "name": "detail", "kind": "required", "type": "string", "description": "A human-readable description of the error, including context about what went wrong. This message is suitable for display to end users or inclusion in logs. May include specifics like resource IDs or field names.
", "example": "The configuration template with ID \"payment-stripe\" was not found in the system." }, { "name": "reason", "kind": "optional", "type": "string", "description": "Optional additional context explaining why the error occurred or what action the user should take. May include suggestions for resolution, links to documentation, or details about system state that led to the error.
", "example": "The template may have been deleted or you may not have permission to access it. Verify the template ID using GET /tenants/cfg/templates." } ], "modelRef": "#/components/schemas/ErrorResponse", "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": "Standard error response returned when a request fails due to business logic, authorization, or system errors. Provides structured information for debugging and user-facing error messages.
", "customType": "ErrorResponse", "schema": [ { "name": "name", "kind": "required", "type": "string", "description": "The high-level error category or type name. This is a machine-readable identifier for the class of error (e.g., 'AuthorizationError', 'ResourceNotFoundError', 'ValidationError'). Use this for programmatic error handling.
", "example": "ResourceNotFoundError" }, { "name": "code", "kind": "required", "type": "string", "description": "A specific error code identifying the exact error condition. More granular than name, this code can be used for precise error handling and localization. Format is typically uppercase with underscores (e.g., 'TEMPLATE_NOT_FOUND', 'INSUFFICIENT_PERMISSIONS').
", "example": "TEMPLATE_NOT_FOUND" }, { "name": "detail", "kind": "required", "type": "string", "description": "A human-readable description of the error, including context about what went wrong. This message is suitable for display to end users or inclusion in logs. May include specifics like resource IDs or field names.
", "example": "The configuration template with ID \"payment-stripe\" was not found in the system." }, { "name": "reason", "kind": "optional", "type": "string", "description": "Optional additional context explaining why the error occurred or what action the user should take. May include suggestions for resolution, links to documentation, or details about system state that led to the error.
", "example": "The template may have been deleted or you may not have permission to access it. Verify the template ID using GET /tenants/cfg/templates." } ], "modelRef": "#/components/schemas/ErrorResponse", "isExpanded": true } ] } ], "hasXCodeSamples": false, "examples": { "languages": [ { "id": "Urc3Lv7ZfAtUkEQTsxMOV", "language": "curl", "label": "cURL", "code": "curl --request POST \\\n --url https://api.upstartcommerce.com/v1/tenants/cfg/records \\\n --header 'accept: text/plain' \\\n --header 'content-type: application/json' \\\n --header 'x-upstart-tenant: string' \\\n --data '{\n \"templateId\": \"payment-cybersource\",\n \"name\": \"Cybersource US Production Credentials\",\n \"data\": \"{\\\"merchantId\\\":\\\"acme_us_prod\\\",\\\"apiKey\\\":\\\"sk_live_abc123xyz789\\\",\\\"apiUrl\\\":\\\"https://api.cybersource.com\\\",\\\"currency\\\":\\\"USD\\\",\\\"testMode\\\":false}\",\n \"enabled\": true,\n \"accessControl\": {\n \"read\": true,\n \"modify\": false\n }\n }'" }, { "id": "XtneaFuMsUHrG_Q1_-dSL", "language": "javascript", "label": "javascript", "code": "var myHeaders = new Headers();\nmyHeaders.append(\"accept\", \"text/plain\");\nmyHeaders.append(\"content-type\", \"application/json\");\nmyHeaders.append(\"x-upstart-tenant\", \"string\");\n\nvar raw = JSON.stringify({\n \"templateId\": \"payment-cybersource\",\n \"name\": \"Cybersource US Production Credentials\",\n \"data\": \"{\\\"merchantId\\\":\\\"acme_us_prod\\\",\\\"apiKey\\\":\\\"sk_live_abc123xyz789\\\",\\\"apiUrl\\\":\\\"https://api.cybersource.com\\\",\\\"currency\\\":\\\"USD\\\",\\\"testMode\\\":false}\",\n \"enabled\": true,\n \"accessControl\": {\n \"read\": true,\n \"modify\": false\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/cfg/records\", requestOptions)\n .then(response => response.text())\n .then(result => console.log(result))\n .catch(error => console.log('error', error));" }, { "id": "fuLk6oxAT5ELei2KLwVOI", "language": "ruby", "label": "Ruby", "code": "require \"uri\"\nrequire \"json\"\nrequire \"net/http\"\n\nurl = URI(\"https://api.upstartcommerce.com/v1/tenants/cfg/records\")\n\nhttps = Net::HTTP.new(url.host, url.port)\nhttps.use_ssl = true\n\nrequest = Net::HTTP::Post.new(url)\nrequest[\"accept\"] = \"text/plain\"\nrequest[\"content-type\"] = \"application/json\"\nrequest[\"x-upstart-tenant\"] = \"string\"\nrequest.body = JSON.dump({\n \"templateId\": \"payment-cybersource\",\n \"name\": \"Cybersource US Production Credentials\",\n \"data\": \"{\\\"merchantId\\\":\\\"acme_us_prod\\\",\\\"apiKey\\\":\\\"sk_live_abc123xyz789\\\",\\\"apiUrl\\\":\\\"https://api.cybersource.com\\\",\\\"currency\\\":\\\"USD\\\",\\\"testMode\\\":false}\",\n \"enabled\": true,\n \"accessControl\": {\n \"read\": true,\n \"modify\": false\n }\n})\n\nresponse = https.request(request)\nputs response.read_body\n" }, { "id": "ROsR0jynqDV5BKvAO71G0", "language": "python", "label": "Python", "code": "import requests\nimport json\n\nurl = \"https://api.upstartcommerce.com/v1/tenants/cfg/records\"\n\npayload = json.dumps({\n \"templateId\": \"payment-cybersource\",\n \"name\": \"Cybersource US Production Credentials\",\n \"data\": \"{\\\"merchantId\\\":\\\"acme_us_prod\\\",\\\"apiKey\\\":\\\"sk_live_abc123xyz789\\\",\\\"apiUrl\\\":\\\"https://api.cybersource.com\\\",\\\"currency\\\":\\\"USD\\\",\\\"testMode\\\":false}\",\n \"enabled\": True,\n \"accessControl\": {\n \"read\": True,\n \"modify\": False\n }\n})\nheaders = {\n 'accept': 'text/plain',\n 'content-type': 'application/json',\n 'x-upstart-tenant': 'string'\n}\n\nresponse = requests.request(\"POST\", url, headers=headers, data=payload)\n\nprint(response.text)\n" } ], "selectedLanguageId": "Urc3Lv7ZfAtUkEQTsxMOV" }, "results": { "languages": [ { "id": "jlo4fohRt-W7W0OL28Bgz", "language": "201", "code": "// Success-record created successfully. Returns the generated record ID.\n" }, { "id": "3HGY1LxPxa3FR0VI-RHnG", "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\": \"SCHEMA_VALIDATION_FAILED\",\n \"detail\": \"Configuration data validation failed: data.apiKey is required but was not provided. Expected string with minimum length 32.\"\n}" }, { "id": "HHQUfSI1E9i9aFNd4Pir_", "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\": \"ResourceNotFoundError\",\n \"code\": \"TEMPLATE_NOT_FOUND\",\n \"detail\": \"The configuration template with ID \\\"payment-stripe\\\" was not found in the system.\",\n \"reason\": \"The template may have been deleted or you may not have permission to access it. Verify the template ID using GET /tenants/cfg/templates.\"\n}" }, { "id": "rHpaHMSQ9ERtPYctReRgX", "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\": \"ResourceNotFoundError\",\n \"code\": \"TEMPLATE_NOT_FOUND\",\n \"detail\": \"The configuration template with ID \\\"payment-stripe\\\" was not found in the system.\",\n \"reason\": \"The template may have been deleted or you may not have permission to access it. Verify the template ID using GET /tenants/cfg/templates.\"\n}" }, { "id": "lUivT_WR_Wq8VesclKcQr", "language": "422", "code": "// The request was well-formed but contains semantic errors or violates business rules that prevent processing.\n{\n \"name\": \"ResourceNotFoundError\",\n \"code\": \"TEMPLATE_NOT_FOUND\",\n \"detail\": \"The configuration template with ID \\\"payment-stripe\\\" was not found in the system.\",\n \"reason\": \"The template may have been deleted or you may not have permission to access it. Verify the template ID using GET /tenants/cfg/templates.\"\n}" }, { "id": "QcLBZuK2IzOfQ1b1o7cL8", "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\": \"ResourceNotFoundError\",\n \"code\": \"TEMPLATE_NOT_FOUND\",\n \"detail\": \"The configuration template with ID \\\"payment-stripe\\\" was not found in the system.\",\n \"reason\": \"The template may have been deleted or you may not have permission to access it. Verify the template ID using GET /tenants/cfg/templates.\"\n}" } ], "selectedLanguageId": "jlo4fohRt-W7W0OL28Bgz" } }, "children": [ { "text": "" } ] }