Create Configuration Template

1 min

POST

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

This endpoint creates a new cfg template.

Authorized permissions:

tenant.cfg.modify

Header Parameters

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

Body Parameters

bodyCreateCfgTemplaterequired
Example
```
{
  "templateId": "payment-stripe",
  "name": "Stripe Payment Gateway Configuration",
  "propertiesDec": {
    "type": "object",
    "properties": {
      "apiKey": {
        "type": "string",
        "format": "password",
        "description": "Stripe secret API key",
        "minLength": 32
      },
      "publishableKey": {
        "type": "string",
        "description": "Stripe publishable API key"
      },
      "webhookSecret": {
        "type": "string",
        "format": "password",
        "description": "Webhook signing secret"
      },
      "currency": {
        "type": "string",
        "enum": [
          "USD",
          "EUR",
          "GBP"
        ],
        "default": "USD"
      }
    },
    "required": [
      "apiKey",
      "publishableKey"
    ]
  },
  "enabled": true,
  "accessControl": {
    "read": true,
    "modify": true
  }
}
```
Description
The configuration template to create, defining the fields a record may set.
- templateIdstring
  Example
  payment-cybersource
  Description
  Optional custom identifier for this template. If not provided, a unique ID will be auto-generated. Must be unique within the tenant. Use descriptive, hierarchical IDs following conventions like 'payment-{provider}', 'shipping-{provider}', 'media-{provider}' (e.g., 'payment-cybersource', 'media-cloudinary'). Cannot be changed after creation.
- namestringrequired
  Example
  Cybersource Payment Gateway Configuration
  Description
  Human-readable name for this template. Displayed in administrative UI, documentation, and when creating records. Should clearly describe what type of configuration this template is for (e.g., 'Cybersource Payment Gateway Configuration', 'FedEx Shipping Integration', 'Cloudinary Media Storage').
- propertiesDecobjectrequired
  Example
```
{
  "type": "object",
  "properties": {
    "merchantId": {
      "type": "string",
      "description": "Merchant identifier from Cybersource",
      "pattern": "^[a-zA-Z0-9_-]+$"
    },
    "apiKey": {
      "type": "string",
      "description": "API key for authentication",
      "format": "password",
      "minLength": 32
    },
    "apiUrl": {
      "type": "string",
      "format": "uri",
      "default": "https://api.cybersource.com",
      "description": "Cybersource API base URL"
    },
    "currency": {
      "type": "string",
      "enum": [
        "USD",
        "EUR",
        "GBP"
      ],
      "default": "USD",
      "description": "Default currency for transactions"
    },
    "testMode": {
      "type": "boolean",
      "default": false,
      "description": "Enable test mode for development"
    }
  },
  "required": [
    "merchantId",
    "apiKey"
  ]
}
```
  Description
  Properties Descriptors (abbreviated as 'propertiesDec'): JSON Schema specification defining the structure, types, and validation rules for configuration records created from this template. Must be valid JSON Schema (draft-07 or compatible). Include field descriptions, required fields, formats, patterns, enums, and defaults. This is the core of the template - it enforces data structure and validation for all records.
- enabledbooleanrequired
  Example
  true
  Description
  Whether this template is initially active and can be used to create new records. Set to false to create templates in draft state for review before enabling. Disabled templates prevent creation of new records but existing records continue to work. Use for template lifecycle management.
- accessControlCfgAccessControl
  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.
  - readbooleanrequired
    Example
    true
    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.
  - modifybooleanrequired
    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.

Responses

201

Success-template created successfully. Returns the generated template ID.

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

ValidationErrorResponse
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.
- 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
  SCHEMA_VALIDATION_FAILED
  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.
- detailstring
  Example
  Configuration data validation failed: data.apiKey is required but was not provided. Expected string with minimum length 32.
  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').

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

ErrorResponse
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.
- namestringrequired
  Example
  ResourceNotFoundError
  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.
- codestringrequired
  Example
  TEMPLATE_NOT_FOUND
  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').
- detailstringrequired
  Example
  The configuration template with ID "payment-stripe" was not found in the system.
  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.
- reasonstring
  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.
  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.

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.

ErrorResponse
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.
- namestringrequired
  Example
  ResourceNotFoundError
  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.
- codestringrequired
  Example
  TEMPLATE_NOT_FOUND
  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').
- detailstringrequired
  Example
  The configuration template with ID "payment-stripe" was not found in the system.
  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.
- reasonstring
  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.
  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.

422

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

ErrorResponse
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.
- namestringrequired
  Example
  ResourceNotFoundError
  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.
- codestringrequired
  Example
  TEMPLATE_NOT_FOUND
  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').
- detailstringrequired
  Example
  The configuration template with ID "payment-stripe" was not found in the system.
  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.
- reasonstring
  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.
  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.

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.

ErrorResponse
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.
- namestringrequired
  Example
  ResourceNotFoundError
  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.
- codestringrequired
  Example
  TEMPLATE_NOT_FOUND
  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').
- detailstringrequired
  Example
  The configuration template with ID "payment-stripe" was not found in the system.
  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.
- reasonstring
  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.
  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.

curl

curl --request POST \
     --url https://api.upstartcommerce.com/v1/tenants/cfg/templates \
     --header 'accept: text/plain' \
     --header 'content-type: application/json' \
     --header 'x-upstart-tenant: string' \
     --data '{
     "name": "Cybersource Payment Gateway Configuration",
     "propertiesDec": "{\"type\":\"object\",\"properties\":{\"merchantId\":{\"type\":\"string\",\"description\":\"Merchant identifier from Cybersource\",\"pattern\":\"^[a-zA-Z0-9_-]+$\"},\"apiKey\":{\"type\":\"string\",\"description\":\"API key for authentication\",\"format\":\"password\",\"minLength\":32},\"apiUrl\":{\"type\":\"string\",\"format\":\"uri\",\"default\":\"https://api.cybersource.com\",\"description\":\"Cybersource API base URL\"},\"currency\":{\"type\":\"string\",\"enum\":[\"USD\",\"EUR\",\"GBP\"],\"default\":\"USD\",\"description\":\"Default currency for transactions\"},\"testMode\":{\"type\":\"boolean\",\"default\":false,\"description\":\"Enable test mode for development\"}},\"required\":[\"merchantId\",\"apiKey\"]}",
     "enabled": true,
     "accessControl": {
     "read": true,
     "modify": false
     }
     }'

javascript

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

var raw = JSON.stringify({
   "name": "Cybersource Payment Gateway Configuration",
   "propertiesDec": "{\"type\":\"object\",\"properties\":{\"merchantId\":{\"type\":\"string\",\"description\":\"Merchant identifier from Cybersource\",\"pattern\":\"^[a-zA-Z0-9_-]+$\"},\"apiKey\":{\"type\":\"string\",\"description\":\"API key for authentication\",\"format\":\"password\",\"minLength\":32},\"apiUrl\":{\"type\":\"string\",\"format\":\"uri\",\"default\":\"https://api.cybersource.com\",\"description\":\"Cybersource API base URL\"},\"currency\":{\"type\":\"string\",\"enum\":[\"USD\",\"EUR\",\"GBP\"],\"default\":\"USD\",\"description\":\"Default currency for transactions\"},\"testMode\":{\"type\":\"boolean\",\"default\":false,\"description\":\"Enable test mode for development\"}},\"required\":[\"merchantId\",\"apiKey\"]}",
   "enabled": true,
   "accessControl": {
      "read": true,
      "modify": false
   }
});

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

fetch("https://api.upstartcommerce.com/v1/tenants/cfg/templates", 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/cfg/templates")

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

request = Net::HTTP::Post.new(url)
request["accept"] = "text/plain"
request["content-type"] = "application/json"
request["x-upstart-tenant"] = "string"
request.body = JSON.dump({
   "name": "Cybersource Payment Gateway Configuration",
   "propertiesDec": "{\"type\":\"object\",\"properties\":{\"merchantId\":{\"type\":\"string\",\"description\":\"Merchant identifier from Cybersource\",\"pattern\":\"^[a-zA-Z0-9_-]+$\"},\"apiKey\":{\"type\":\"string\",\"description\":\"API key for authentication\",\"format\":\"password\",\"minLength\":32},\"apiUrl\":{\"type\":\"string\",\"format\":\"uri\",\"default\":\"https://api.cybersource.com\",\"description\":\"Cybersource API base URL\"},\"currency\":{\"type\":\"string\",\"enum\":[\"USD\",\"EUR\",\"GBP\"],\"default\":\"USD\",\"description\":\"Default currency for transactions\"},\"testMode\":{\"type\":\"boolean\",\"default\":false,\"description\":\"Enable test mode for development\"}},\"required\":[\"merchantId\",\"apiKey\"]}",
   "enabled": true,
   "accessControl": {
      "read": true,
      "modify": false
   }
})

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

python

import requests
import json

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

payload = json.dumps({
   "name": "Cybersource Payment Gateway Configuration",
   "propertiesDec": "{\"type\":\"object\",\"properties\":{\"merchantId\":{\"type\":\"string\",\"description\":\"Merchant identifier from Cybersource\",\"pattern\":\"^[a-zA-Z0-9_-]+$\"},\"apiKey\":{\"type\":\"string\",\"description\":\"API key for authentication\",\"format\":\"password\",\"minLength\":32},\"apiUrl\":{\"type\":\"string\",\"format\":\"uri\",\"default\":\"https://api.cybersource.com\",\"description\":\"Cybersource API base URL\"},\"currency\":{\"type\":\"string\",\"enum\":[\"USD\",\"EUR\",\"GBP\"],\"default\":\"USD\",\"description\":\"Default currency for transactions\"},\"testMode\":{\"type\":\"boolean\",\"default\":false,\"description\":\"Enable test mode for development\"}},\"required\":[\"merchantId\",\"apiKey\"]}",
   "enabled": True,
   "accessControl": {
      "read": True,
      "modify": False
   }
})
headers = {
   'accept': 'text/plain',
   'content-type': 'application/json',
   'x-upstart-tenant': 'string'
}

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

print(response.text)

201

// Success-template created successfully. Returns the generated template ID.

400

// The request contained information that the server was unable to process. Appropriate errors are provided in the response body.
{
  "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."
}

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": "ResourceNotFoundError",
  "code": "TEMPLATE_NOT_FOUND",
  "detail": "The configuration template with ID \"payment-stripe\" was not found in the system.",
  "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."
}

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": "ResourceNotFoundError",
  "code": "TEMPLATE_NOT_FOUND",
  "detail": "The configuration template with ID \"payment-stripe\" was not found in the system.",
  "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."
}

422

// The request was well-formed but contains semantic errors or violates business rules that prevent processing.
{
  "name": "ResourceNotFoundError",
  "code": "TEMPLATE_NOT_FOUND",
  "detail": "The configuration template with ID \"payment-stripe\" was not found in the system.",
  "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."
}

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": "ResourceNotFoundError",
  "code": "TEMPLATE_NOT_FOUND",
  "detail": "The configuration template with ID \"payment-stripe\" was not found in the system.",
  "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."
}