Get Configuration Records by Template ID

1 min

GET

https://api.upstartcommerce.com/v1/tenants/cfg/records/template/{templateId}

This endpoint retrieves the cfg records data for a given templateId.

Authorized permissions:

tenant.cfg.read

Path Parameters

templateIdstringrequired
Description
Unique identifier for a given template.

Header Parameters

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

Responses

200

Success-records returned.

CfgRecord[]
Example
```
[
  {
    "tenant": "acme001",
    "domain": "acme-retail",
    "recordId": "payment-cybersource-us-prod",
    "templateId": "payment-cybersource",
    "siteIds": [
      "us-west-store",
      "us-east-store"
    ],
    "tags": [
      "production",
      "payment-gateway",
      "us-region"
    ],
    "name": "Cybersource US Production",
    "data": {
      "merchantId": "acme_us_prod",
      "apiKey": "***",
      "currency": "USD"
    },
    "enabled": true,
    "version": 3,
    "accessControl": {
      "read": true,
      "modify": false
    },
    "audit": {
      "by": "[email protected]",
      "byAnonymous": false,
      "at": "2024-01-15T10:30:00Z",
      "traceId": null,
      "serviceName": "tenant-svc",
      "serviceVersion": "1.2.3"
    }
  },
  {
    "tenant": "acme001",
    "domain": "acme-retail",
    "recordId": "payment-cybersource-eu-prod",
    "templateId": "payment-cybersource",
    "siteIds": [
      "eu-store",
      "uk-store"
    ],
    "tags": [
      "production",
      "payment-gateway",
      "eu-region"
    ],
    "name": "Cybersource EU Production",
    "data": {
      "merchantId": "acme_eu_prod",
      "apiKey": "***",
      "currency": "EUR"
    },
    "enabled": true,
    "version": 2,
    "accessControl": {
      "read": true,
      "modify": false
    },
    "audit": {
      "by": "[email protected]",
      "byAnonymous": false,
      "at": "2024-01-10T09:00:00Z",
      "traceId": "abc123",
      "serviceName": "tenant-svc",
      "serviceVersion": "1.2.3"
    }
  }
]
```
Description
A configuration record represents a concrete instance of a configuration template with actual values. Records contain the runtime configuration data used by integrations and services, and can be scoped to specific sites. For example, a record might contain API credentials for a payment gateway for a specific store site.
- tenantstring
  Example
  acme-retail
  Description
  The unique identifier of the tenant that owns this configuration record. All records are isolated by tenant for multi-tenancy.
- domainstringrequired
  Example
  acme
  Description
  The domain name associated with the tenant. This is the subdomain prefix used to access the tenant's portal (e.g., 'acme' in 'acme.upstartcommerce.com').
- recordIdstringrequired
  Example
  cfg-rec-550e8400-e29b-41d4-a716-446655440000
  Description
  The unique identifier for this configuration record within the tenant. Used to reference and manage this specific configuration instance.
- templateIdstringrequired
  Example
  cybersource-payment
  Description
  The identifier of the configuration template this record is based on. The template defines the schema and structure of the data field. Examples include 'cybersource', 'stripe', 'cloudinary'.
- siteIdsstring[]
  Example
```
[
  "site-us-west",
  "site-us-east"
]
```
  Description
  The list of site identifiers this configuration applies to. When empty, the configuration applies to all sites within the tenant. Use this to create site-specific configurations (e.g., different payment credentials per store).
- tagsstring[]
  Example
```
[
  "production",
  "payment-gateway",
  "us-region"
]
```
  Description
  Arbitrary tags for organizing and filtering configuration records. Useful for categorizing records by environment (dev, staging, prod), purpose (payment, shipping, tax), or any custom taxonomy.
- namestringrequired
  Example
  Cybersource US Production Credentials
  Description
  A human-readable name for this configuration record. Should be descriptive and unique within the tenant to make it easy to identify in lists and logs.
- dataobjectrequired
  Example
```
{
  "merchantId": "acme_us",
  "apiKey": "sk_live_...",
  "apiUrl": "https://api.cybersource.com",
  "currency": "USD"
}
```
  Description
  The actual configuration data as a JSON object. The structure is defined by the associated template's propertiesDescriptors. Contains integration credentials, settings, and other configuration values. Sensitive fields (like API keys) should be handled securely.
- enabledbooleanrequired
  Example
  true
  Description
  Indicates whether this configuration record is currently active and should be used by the system. When false, the record is retained but ignored by runtime processes. Useful for temporarily disabling integrations without deleting configuration data.
- versioninteger<int32>required
  Example
  5
  Description
  The version number of this configuration record, incremented with each update. Used for optimistic locking to prevent concurrent modification conflicts. Clients should provide this value when updating records.
  Format
  int32
- accessControlCfgAccessControlrequired
  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.
- auditAuditrequired
  Description
  Audit information tracking who performed an action, when, and from which system. This provides a complete audit trail for compliance and debugging purposes.
  - byIdstring
    Description
    The unique identifier of the user or system that performed this action. This could be a user ID, service account ID, or system identifier.
  - bystringrequired
    Description
    The human-readable name or email of the user/system that performed the action. Used for display purposes in audit logs and UI.
  - byAnonymousbooleanrequired
    Description
    Indicates whether this action was performed by an anonymous user (true) or an authenticated user/system (false). Anonymous actions have limited audit information.
  - atstring<date-time>required
    Example
    2024-01-15T10:30:00Z
    Description
    The exact timestamp when this action occurred, in ISO 8601 format (e.g., '2024-01-15T10:30
    '). Always in UTC timezone.
    Format
    date-time
  - traceIdstringrequired
    Example
    550e8400-e29b-41d4-a716-446655440000
    Description
    A unique identifier for tracing this request across distributed services. Used for correlating logs and debugging issues across the system. Typically a UUID.
  - serviceNamestringrequired
    Example
    tenant-svc
    Description
    The name of the microservice that processed this request (e.g., 'tenant-svc', 'cart-svc'). Used for identifying which service performed the action.
  - serviceVersionstringrequired
    Example
    1.2.3
    Description
    The version of the service that processed this request (e.g., '1.2.3', 'v2.0.0'). Useful for tracking behavior changes across deployments.
  - byDomainstring
    Example
    example-store
    Description
    The domain or tenant context from which the action was performed. Used in multi-tenant scenarios to track cross-tenant operations.
  - bySubjectTypestring
    Example
    USER
    Description
    The type of subject that performed the action (e.g., 'USER', 'SERVICE_ACCOUNT', 'SYSTEM'). Helps categorize audit entries by actor type.

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.

404The requested resource was not found in the NoChannel system.

ErrorResponse
Example
```
{
  "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."
}
```
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 GET \
     --url https://api.upstartcommerce.com/v1/tenants/cfg/records/template/{templateId} \
     --header 'accept: application/json' \
     --header 'x-upstart-tenant: string'

javascript

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

var requestOptions = {
   method: 'GET',
   headers: myHeaders,
   redirect: 'follow'
};

fetch("https://api.upstartcommerce.com/v1/tenants/cfg/records/template/{templateId}", 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/records/template/{templateId}")

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

request = Net::HTTP::Get.new(url)
request["accept"] = "application/json"
request["content-type"] = "application/json"
request["x-upstart-tenant"] = "string"

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

python

import requests
import json

url = "https://api.upstartcommerce.com/v1/tenants/cfg/records/template/{templateId}"

payload = {}
headers = {
   'accept': 'application/json',
   'content-type': 'application/json',
   'x-upstart-tenant': 'string'
}

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

print(response.text)

200

// Success-records returned.
[
  {
    "tenant": "acme-retail",
    "domain": "acme",
    "recordId": "cfg-rec-550e8400-e29b-41d4-a716-446655440000",
    "templateId": "cybersource-payment",
    "siteIds": [
      ""
    ],
    "tags": [
      ""
    ],
    "name": "Cybersource US Production Credentials",
    "data": {},
    "enabled": true,
    "version": 5,
    "accessControl": {
      "read": true,
      "modify": false
    },
    "audit": {
      "byId": "",
      "by": "",
      "byAnonymous": false,
      "at": "2024-01-15T10:30:00Z",
      "traceId": "550e8400-e29b-41d4-a716-446655440000",
      "serviceName": "tenant-svc",
      "serviceVersion": "1.2.3",
      "byDomain": "example-store",
      "bySubjectType": "USER"
    }
  }
]

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."
}

404

// The requested resource was not found in the NoChannel system.
{
  "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."
}