All URIs are relative to https://secure.ultracart.com/rest/v2
| Method | HTTP request | Description |
|---|---|---|
| compileSfvbCjson | POST /sfvb/cjson/compile | Compile CJSON to Velocity |
| createSfvbPreviewSession | POST /sfvb/storefronts/{storefront_oid}/preview_sessions | Create a preview session |
| deleteSfvbFile | DELETE /sfvb/storefronts/{storefront_oid}/files | Delete a storefront file |
| deleteSfvbPreviewSession | DELETE /sfvb/storefronts/{storefront_oid}/preview_sessions/{preview_session_id} | Delete a preview session |
| downloadSfvbFile | GET /sfvb/storefronts/{storefront_oid}/files/download | Read a storefront file's raw bytes |
| duplicateSfvbTheme | POST /sfvb/storefronts/{storefront_oid}/themes/{theme_oid}/duplicate | Duplicate a theme |
| getSfvbCjsonUsedElements | POST /sfvb/cjson/elements | Element types used by a container |
| getSfvbContainer | GET /sfvb/storefronts/{storefront_oid}/containers/{owner_type}/{owner_object_id} | Read a container stored outside the file system |
| getSfvbContainerVersion | GET /sfvb/storefronts/{storefront_oid}/container_versions/{container_history_oid} | Read the CJSON stored in one container history entry |
| getSfvbElement | GET /sfvb/elements/{element_type} | Configuration schema for one element type |
| getSfvbFileContent | GET /sfvb/storefronts/{storefront_oid}/files/content | Read a storefront file |
| getSfvbFileUploadUrl | GET /sfvb/storefronts/{storefront_oid}/files/upload_url/{extension} | Get a URL to upload a binary asset to |
| getSfvbLibraryEntry | GET /sfvb/storefronts/{storefront_oid}/library/{library_oid} | Read one library entry including its CJSON |
| getSfvbPreviewUrl | GET /sfvb/storefronts/{storefront_oid}/preview_sessions/{preview_session_id}/url | URL that renders a preview session |
| getSfvbTheme | GET /sfvb/storefronts/{storefront_oid}/themes/{theme_oid} | Get a theme |
| getSfvbThemeJob | GET /sfvb/storefronts/{storefront_oid}/theme_jobs/{job_id} | Status of an asynchronous theme job |
| getSfvbVersion | GET /sfvb/version | Compiler version for this merchant |
| getSfvbWhoami | GET /sfvb/whoami | Who this token is |
| installSfvbLibraryEntry | POST /sfvb/storefronts/{storefront_oid}/library/{library_oid}/install | Install a library entry into a storefront |
| listSfvbContainerVersions | GET /sfvb/storefronts/{storefront_oid}/container_versions | Version history for a container stored outside the file system |
| listSfvbElements | GET /sfvb/elements | List every SFVB element type |
| listSfvbFileVersions | GET /sfvb/storefronts/{storefront_oid}/files/versions | Version history for a storefront file |
| listSfvbFiles | GET /sfvb/storefronts/{storefront_oid}/files | List a storefront directory |
| listSfvbStorefronts | GET /sfvb/storefronts | List storefronts |
| listSfvbThemes | GET /sfvb/storefronts/{storefront_oid}/themes | List themes for a storefront |
| listSfvbUpsellOffers | GET /sfvb/storefronts/{storefront_oid}/upsell_offers | List upsell offers |
| putSfvbContainer | PUT /sfvb/storefronts/{storefront_oid}/containers/{owner_type}/{owner_object_id} | Write a container stored outside the file system |
| putSfvbFileContent | PUT /sfvb/storefronts/{storefront_oid}/files/content | Write a storefront file |
| putSfvbPreviewSession | PUT /sfvb/storefronts/{storefront_oid}/preview_sessions/{preview_session_id} | Push containers into a preview session |
| renderSfvbWidgets | POST /sfvb/storefronts/{storefront_oid}/themes/{theme_oid}/render | Render a CJSON node to HTML |
| reserveSfvbWidgetIds | POST /sfvb/storefronts/{storefront_oid}/widget_ids | Reserve a block of widget ids |
| revertSfvbContainer | POST /sfvb/storefronts/{storefront_oid}/containers/{owner_type}/{owner_object_id}/revert | Revert a container stored outside the file system |
| revertSfvbFile | POST /sfvb/storefronts/{storefront_oid}/files/revert | Revert a storefront file to an earlier version |
| searchSfvbFiles | POST /sfvb/storefronts/{storefront_oid}/files/search | Search storefront files |
| searchSfvbLibrary | GET /sfvb/storefronts/{storefront_oid}/library | Search the element library |
| uploadSfvbFile | POST /sfvb/storefronts/{storefront_oid}/files/upload | Store a binary asset that was already uploaded |
| validateSfvbCjson | POST /sfvb/cjson/validate | Validate CJSON |
| validateSfvbVelocity | POST /sfvb/storefronts/{storefront_oid}/themes/{theme_oid}/velocity/validate | Validate a Velocity template against a theme |
SfvbCompileResponse compileSfvbCjson(compileRequest)
Compile CJSON to Velocity
Compiles a container document to Velocity without storing anything. Supply theme_oid to compile with the theme's inherit groups applied; omit it to compile standalone.
(No example for this operation).
| Name | Type | Description | Notes |
|---|---|---|---|
| compileRequest | SfvbCompileRequest | CJSON to compile |
ultraCartOauth, ultraCartSimpleApiKey
- Content-Type: application/json
- Accept: application/json
| Status code | Description | Response headers |
|---|---|---|
| 200 | Successful response | - |
| 400 | Status Code 400: bad request input such as invalid json | * UC-REST-ERROR - Contains human readable error message |
| 401 | Status Code 401: invalid credentials supplied | * UC-REST-ERROR - Contains human readable error message |
| 413 | - | |
| 429 | Status Code 429: you have exceeded the allowed API call rate limit for your application. | * UC-REST-ERROR - Contains human readable error message |
| 500 | Status Code 500: any server side error. the body will contain a generic server error message | * UC-REST-ERROR - Contains human readable error message |
SfvbPreviewSessionResponse createSfvbPreviewSession(storefrontOid)
Create a preview session
Returns a server generated session id to push containers into. The id is not caller supplied, because concurrent agents choosing their own would be free to collide, and the browser editor's habit of minting one with Math.random is not a property worth carrying into an API. Expires after eight hours and can be deleted sooner. Requires a token that resolves to a user, so use the device authorization flow.
(No example for this operation).
| Name | Type | Description | Notes |
|---|---|---|---|
| storefrontOid | Integer |
ultraCartOauth, ultraCartSimpleApiKey
- Content-Type: Not defined
- Accept: application/json
| Status code | Description | Response headers |
|---|---|---|
| 200 | Successful response | - |
| 400 | Status Code 400: bad request input such as invalid json | * UC-REST-ERROR - Contains human readable error message |
| 401 | Status Code 401: invalid credentials supplied | * UC-REST-ERROR - Contains human readable error message |
| 403 | Status Code 403: forbidden | * UC-REST-ERROR - Contains human readable error message |
| 404 | Status Code 404: not found | * UC-REST-ERROR - Contains human readable error message |
| 500 | Status Code 500: any server side error. the body will contain a generic server error message | * UC-REST-ERROR - Contains human readable error message |
deleteSfvbFile(storefrontOid, ifMatch, path)
Delete a storefront file
Recoverable from the recycle bin.
(No example for this operation).
| Name | Type | Description | Notes |
|---|---|---|---|
| storefrontOid | Integer | ||
| ifMatch | String | Content hash of the file being deleted. Required; 428 when absent, 412 when stale. | |
| path | String | [optional] |
null (empty response body)
ultraCartOauth, ultraCartSimpleApiKey
- Content-Type: Not defined
- Accept: application/json
| Status code | Description | Response headers |
|---|---|---|
| 400 | Status Code 400: bad request input such as invalid json | * UC-REST-ERROR - Contains human readable error message |
| 401 | Status Code 401: invalid credentials supplied | * UC-REST-ERROR - Contains human readable error message |
| 403 | Status Code 403: forbidden | * UC-REST-ERROR - Contains human readable error message |
| 404 | Status Code 404: not found | * UC-REST-ERROR - Contains human readable error message |
| 500 | Status Code 500: any server side error. the body will contain a generic server error message | * UC-REST-ERROR - Contains human readable error message |
deleteSfvbPreviewSession(storefrontOid, previewSessionId)
Delete a preview session
Releases the session before its eight hour expiry. Without this the only way to free one is to wait, which is a poor answer for a tool that may open a dozen in an afternoon.
(No example for this operation).
| Name | Type | Description | Notes |
|---|---|---|---|
| storefrontOid | Integer | ||
| previewSessionId | String |
null (empty response body)
ultraCartOauth, ultraCartSimpleApiKey
- Content-Type: Not defined
- Accept: application/json
| Status code | Description | Response headers |
|---|---|---|
| 400 | Status Code 400: bad request input such as invalid json | * UC-REST-ERROR - Contains human readable error message |
| 401 | Status Code 401: invalid credentials supplied | * UC-REST-ERROR - Contains human readable error message |
| 403 | Status Code 403: forbidden | * UC-REST-ERROR - Contains human readable error message |
| 404 | Status Code 404: not found | * UC-REST-ERROR - Contains human readable error message |
| 500 | Status Code 500: any server side error. the body will contain a generic server error message | * UC-REST-ERROR - Contains human readable error message |
downloadSfvbFile(storefrontOid, path)
Read a storefront file's raw bytes
Returns the file itself rather than a JSON envelope, for any type including binaries that files/content refuses. Use this to verify what you uploaded, and note it is the only way to read a file inside a theme that is not active - such a file is served to nobody until the theme is promoted, so it has no public URL to fetch instead. On success the body is the file; on failure it is the usual JSON error object, so do not assume the content type without checking the status.
(No example for this operation).
| Name | Type | Description | Notes |
|---|---|---|---|
| storefrontOid | Integer | ||
| path | String | [optional] |
null (empty response body)
ultraCartOauth, ultraCartSimpleApiKey
- Content-Type: Not defined
- Accept: application/octet-stream
| Status code | Description | Response headers |
|---|---|---|
| 400 | Status Code 400: bad request input such as invalid json | * UC-REST-ERROR - Contains human readable error message |
| 401 | Status Code 401: invalid credentials supplied | * UC-REST-ERROR - Contains human readable error message |
| 404 | Status Code 404: not found | * UC-REST-ERROR - Contains human readable error message |
| 500 | Status Code 500: any server side error. the body will contain a generic server error message | * UC-REST-ERROR - Contains human readable error message |
SfvbThemeJobResponse duplicateSfvbTheme(storefrontOid, themeOid, duplicateRequest)
Duplicate a theme
Copies a theme into a new one and returns a job handle to poll. Asynchronous, because copying a theme copies every file in it. Needs sfvb_write rather than sfvb_publish, because the job explicitly does not activate what it creates, so the worst outcome of a mistaken call is a spare theme. This is how you get somewhere safe to work - duplicate, edit the copy with an ordinary write scope, and let a human promote it.
(No example for this operation).
| Name | Type | Description | Notes |
|---|---|---|---|
| storefrontOid | Integer | ||
| themeOid | Integer | ||
| duplicateRequest | SfvbThemeDuplicateRequest | Theme duplication details |
ultraCartOauth, ultraCartSimpleApiKey
- Content-Type: application/json
- Accept: application/json
| Status code | Description | Response headers |
|---|---|---|
| 200 | Successful response | - |
| 400 | Status Code 400: bad request input such as invalid json | * UC-REST-ERROR - Contains human readable error message |
| 401 | Status Code 401: invalid credentials supplied | * UC-REST-ERROR - Contains human readable error message |
| 403 | Status Code 403: forbidden | * UC-REST-ERROR - Contains human readable error message |
| 404 | Status Code 404: not found | * UC-REST-ERROR - Contains human readable error message |
| 412 | - | |
| 500 | Status Code 500: any server side error. the body will contain a generic server error message | * UC-REST-ERROR - Contains human readable error message |
SfvbElementsResponse getSfvbCjsonUsedElements(compileRequest)
Element types used by a container
(No example for this operation).
| Name | Type | Description | Notes |
|---|---|---|---|
| compileRequest | SfvbCompileRequest | CJSON to inspect |
ultraCartOauth, ultraCartSimpleApiKey
- Content-Type: application/json
- Accept: application/json
| Status code | Description | Response headers |
|---|---|---|
| 200 | Successful response | - |
| 400 | Status Code 400: bad request input such as invalid json | * UC-REST-ERROR - Contains human readable error message |
| 401 | Status Code 401: invalid credentials supplied | * UC-REST-ERROR - Contains human readable error message |
| 500 | Status Code 500: any server side error. the body will contain a generic server error message | * UC-REST-ERROR - Contains human readable error message |
SfvbContainerResponse getSfvbContainer(storefrontOid, ownerType, ownerObjectId, containerName)
Read a container stored outside the file system
owner_type is one of upsell, email, postcardfront, postcardback or item. Item containers also require container_name. Theme and page containers are files; read those through files/content.
(No example for this operation).
| Name | Type | Description | Notes |
|---|---|---|---|
| storefrontOid | Integer | ||
| ownerType | String | ||
| ownerObjectId | String | ||
| containerName | String | [optional] |
ultraCartOauth, ultraCartSimpleApiKey
- Content-Type: Not defined
- Accept: application/json
| Status code | Description | Response headers |
|---|---|---|
| 200 | Successful response | - |
| 400 | Status Code 400: bad request input such as invalid json | * UC-REST-ERROR - Contains human readable error message |
| 401 | Status Code 401: invalid credentials supplied | * UC-REST-ERROR - Contains human readable error message |
| 404 | Status Code 404: not found | * UC-REST-ERROR - Contains human readable error message |
| 500 | Status Code 500: any server side error. the body will contain a generic server error message | * UC-REST-ERROR - Contains human readable error message |
SfvbContainerVersion getSfvbContainerVersion(storefrontOid, containerHistoryOid, ownerType, ownerObjectId, containerName)
Read the CJSON stored in one container history entry
Inspect or diff an earlier version without reverting to it. The version is addressed through the container that owns it, so a history oid belonging to some other resource cannot be read through this route.
(No example for this operation).
| Name | Type | Description | Notes |
|---|---|---|---|
| storefrontOid | Integer | ||
| containerHistoryOid | Integer | ||
| ownerType | String | [optional] | |
| ownerObjectId | String | [optional] | |
| containerName | String | [optional] |
ultraCartOauth, ultraCartSimpleApiKey
- Content-Type: Not defined
- Accept: application/json
| Status code | Description | Response headers |
|---|---|---|
| 200 | Successful response | - |
| 400 | Status Code 400: bad request input such as invalid json | * UC-REST-ERROR - Contains human readable error message |
| 401 | Status Code 401: invalid credentials supplied | * UC-REST-ERROR - Contains human readable error message |
| 404 | Status Code 404: not found | * UC-REST-ERROR - Contains human readable error message |
| 500 | Status Code 500: any server side error. the body will contain a generic server error message | * UC-REST-ERROR - Contains human readable error message |
SfvbElementSchemaResponse getSfvbElement(elementType)
Configuration schema for one element type
(No example for this operation).
| Name | Type | Description | Notes |
|---|---|---|---|
| elementType | String |
ultraCartOauth, ultraCartSimpleApiKey
- Content-Type: Not defined
- Accept: application/json
| Status code | Description | Response headers |
|---|---|---|
| 200 | Successful response | - |
| 400 | Status Code 400: bad request input such as invalid json | * UC-REST-ERROR - Contains human readable error message |
| 401 | Status Code 401: invalid credentials supplied | * UC-REST-ERROR - Contains human readable error message |
| 404 | Status Code 404: not found | * UC-REST-ERROR - Contains human readable error message |
| 500 | Status Code 500: any server side error. the body will contain a generic server error message | * UC-REST-ERROR - Contains human readable error message |
SfvbFileContentResponse getSfvbFileContent(storefrontOid, path, version)
Read a storefront file
Returns the current content, or an earlier version when version is supplied. Send the body's hash_sha256 back as If-Match when writing. The ETag header carries the same hash, but a compressing proxy may append a suffix such as -gzip to it, so prefer the body value.
(No example for this operation).
| Name | Type | Description | Notes |
|---|---|---|---|
| storefrontOid | Integer | ||
| path | String | [optional] | |
| version | Integer | [optional] |
ultraCartOauth, ultraCartSimpleApiKey
- Content-Type: Not defined
- Accept: application/json
| Status code | Description | Response headers |
|---|---|---|
| 200 | Successful response | - |
| 400 | Status Code 400: bad request input such as invalid json | * UC-REST-ERROR - Contains human readable error message |
| 401 | Status Code 401: invalid credentials supplied | * UC-REST-ERROR - Contains human readable error message |
| 404 | Status Code 404: not found | * UC-REST-ERROR - Contains human readable error message |
| 413 | - | |
| 500 | Status Code 500: any server side error. the body will contain a generic server error message | * UC-REST-ERROR - Contains human readable error message |
SfvbFileUploadUrlResponse getSfvbFileUploadUrl(storefrontOid, extension)
Get a URL to upload a binary asset to
Binary content does not travel through this API as JSON, so uploading an image, font, video or PDF is two steps. Ask here for a URL, PUT the raw bytes straight to it, then call uploadSfvbFile quoting the key you were given. The bytes never pass through the API server. The extension is checked against the accepted type list before a URL is issued, so an unsupported type fails here rather than after you have sent the file. The URL is short lived and the key is bound to your account.
(No example for this operation).
| Name | Type | Description | Notes |
|---|---|---|---|
| storefrontOid | Integer | ||
| extension | String |
ultraCartOauth, ultraCartSimpleApiKey
- Content-Type: Not defined
- Accept: application/json
| Status code | Description | Response headers |
|---|---|---|
| 200 | Successful response | - |
| 400 | Status Code 400: bad request input such as invalid json | * UC-REST-ERROR - Contains human readable error message |
| 401 | Status Code 401: invalid credentials supplied | * UC-REST-ERROR - Contains human readable error message |
| 403 | Status Code 403: forbidden | * UC-REST-ERROR - Contains human readable error message |
| 404 | Status Code 404: not found | * UC-REST-ERROR - Contains human readable error message |
| 500 | Status Code 500: any server side error. the body will contain a generic server error message | * UC-REST-ERROR - Contains human readable error message |
SfvbLibraryEntry getSfvbLibraryEntry(storefrontOid, libraryOid)
Read one library entry including its CJSON
Returns the fragment as authored. If it references images or other storefront files those paths will not resolve on this storefront until the entry is installed, so use install rather than this when the intent is to place the fragment.
(No example for this operation).
| Name | Type | Description | Notes |
|---|---|---|---|
| storefrontOid | Integer | ||
| libraryOid | Integer |
ultraCartOauth, ultraCartSimpleApiKey
- Content-Type: Not defined
- Accept: application/json
| Status code | Description | Response headers |
|---|---|---|
| 200 | Successful response | - |
| 400 | Status Code 400: bad request input such as invalid json | * UC-REST-ERROR - Contains human readable error message |
| 401 | Status Code 401: invalid credentials supplied | * UC-REST-ERROR - Contains human readable error message |
| 403 | Status Code 403: forbidden | * UC-REST-ERROR - Contains human readable error message |
| 404 | Status Code 404: not found | * UC-REST-ERROR - Contains human readable error message |
| 500 | Status Code 500: any server side error. the body will contain a generic server error message | * UC-REST-ERROR - Contains human readable error message |
SfvbPreviewUrlResponse getSfvbPreviewUrl(storefrontOid, previewSessionId, path)
URL that renders a preview session
Refuses a session that does not exist, so a URL you receive is for a session that was really there. expires_in_seconds is the time actually remaining, not the configured lifetime. Needs a token that resolves to a user, because a preview session belongs to the person who created it.
(No example for this operation).
| Name | Type | Description | Notes |
|---|---|---|---|
| storefrontOid | Integer | ||
| previewSessionId | String | ||
| path | String | [optional] |
ultraCartOauth, ultraCartSimpleApiKey
- Content-Type: Not defined
- Accept: application/json
| Status code | Description | Response headers |
|---|---|---|
| 200 | Successful response | - |
| 400 | Status Code 400: bad request input such as invalid json | * UC-REST-ERROR - Contains human readable error message |
| 401 | Status Code 401: invalid credentials supplied | * UC-REST-ERROR - Contains human readable error message |
| 403 | Status Code 403: forbidden | * UC-REST-ERROR - Contains human readable error message |
| 404 | Status Code 404: not found | * UC-REST-ERROR - Contains human readable error message |
| 500 | Status Code 500: any server side error. the body will contain a generic server error message | * UC-REST-ERROR - Contains human readable error message |
SfvbTheme getSfvbTheme(storefrontOid, themeOid)
Get a theme
(No example for this operation).
| Name | Type | Description | Notes |
|---|---|---|---|
| storefrontOid | Integer | ||
| themeOid | Integer |
ultraCartOauth, ultraCartSimpleApiKey
- Content-Type: Not defined
- Accept: application/json
| Status code | Description | Response headers |
|---|---|---|
| 200 | Successful response | - |
| 400 | Status Code 400: bad request input such as invalid json | * UC-REST-ERROR - Contains human readable error message |
| 401 | Status Code 401: invalid credentials supplied | * UC-REST-ERROR - Contains human readable error message |
| 404 | Status Code 404: not found | * UC-REST-ERROR - Contains human readable error message |
| 500 | Status Code 500: any server side error. the body will contain a generic server error message | * UC-REST-ERROR - Contains human readable error message |
SfvbThemeJobResponse getSfvbThemeJob(storefrontOid, jobId)
Status of an asynchronous theme job
Poll until complete is true, then check success. Note that the new theme's oid is not returned. The job's product is a plain text report rather than a structured result, so once it completes, list themes and match on the target_path the start call gave you.
(No example for this operation).
| Name | Type | Description | Notes |
|---|---|---|---|
| storefrontOid | Integer | ||
| jobId | Integer |
ultraCartOauth, ultraCartSimpleApiKey
- Content-Type: Not defined
- Accept: application/json
| Status code | Description | Response headers |
|---|---|---|
| 200 | Successful response | - |
| 400 | Status Code 400: bad request input such as invalid json | * UC-REST-ERROR - Contains human readable error message |
| 401 | Status Code 401: invalid credentials supplied | * UC-REST-ERROR - Contains human readable error message |
| 403 | Status Code 403: forbidden | * UC-REST-ERROR - Contains human readable error message |
| 404 | Status Code 404: not found | * UC-REST-ERROR - Contains human readable error message |
| 500 | Status Code 500: any server side error. the body will contain a generic server error message | * UC-REST-ERROR - Contains human readable error message |
SfvbVersionResponse getSfvbVersion()
Compiler version for this merchant
The visual builder release channel is per merchant, so a CLI holding cached schema or element data should compare against this to know when it has gone stale.
(No example for this operation).
This endpoint does not need any parameter.
ultraCartOauth, ultraCartSimpleApiKey
- Content-Type: Not defined
- Accept: application/json
| Status code | Description | Response headers |
|---|---|---|
| 200 | Successful response | - |
| 401 | Status Code 401: invalid credentials supplied | * UC-REST-ERROR - Contains human readable error message |
| 500 | Status Code 500: any server side error. the body will contain a generic server error message | * UC-REST-ERROR - Contains human readable error message |
SfvbWhoamiResponse getSfvbWhoami()
Who this token is
Returns the merchant, user, granted scopes and reachable storefronts for the calling token. Declared for any scope so an application can always discover which account it is connected to.
(No example for this operation).
This endpoint does not need any parameter.
ultraCartOauth, ultraCartSimpleApiKey
- Content-Type: Not defined
- Accept: application/json
| Status code | Description | Response headers |
|---|---|---|
| 200 | Successful response | - |
| 401 | Status Code 401: invalid credentials supplied | * UC-REST-ERROR - Contains human readable error message |
| 410 | Status Code 410: Your authorized application has been disabled by UltraCart | * UC-REST-ERROR - Contains human readable error message |
| 429 | Status Code 429: you have exceeded the allowed API call rate limit for your application. | * UC-REST-ERROR - Contains human readable error message |
| 500 | Status Code 500: any server side error. the body will contain a generic server error message | * UC-REST-ERROR - Contains human readable error message |
SfvbLibraryEntry installSfvbLibraryEntry(storefrontOid, libraryOid)
Install a library entry into a storefront
Copies the fragment's referenced assets into the storefront file system and returns the CJSON with its paths resolved, ready to place. This writes, which is why it is a POST rather than the GET the internal admin endpoint uses. It also requires sfvb_publish, because the assets land in the shared storefront file system, which is served to shoppers regardless of which theme is active, so no amount of working inside a duplicate theme isolates them.
(No example for this operation).
| Name | Type | Description | Notes |
|---|---|---|---|
| storefrontOid | Integer | ||
| libraryOid | Integer |
ultraCartOauth, ultraCartSimpleApiKey
- Content-Type: Not defined
- Accept: application/json
| Status code | Description | Response headers |
|---|---|---|
| 200 | Successful response | - |
| 400 | Status Code 400: bad request input such as invalid json | * UC-REST-ERROR - Contains human readable error message |
| 401 | Status Code 401: invalid credentials supplied | * UC-REST-ERROR - Contains human readable error message |
| 403 | Status Code 403: forbidden | * UC-REST-ERROR - Contains human readable error message |
| 404 | Status Code 404: not found | * UC-REST-ERROR - Contains human readable error message |
| 500 | Status Code 500: any server side error. the body will contain a generic server error message | * UC-REST-ERROR - Contains human readable error message |
SfvbContainerVersionsResponse listSfvbContainerVersions(storefrontOid, ownerType, ownerObjectId, containerName)
Version history for a container stored outside the file system
(No example for this operation).
| Name | Type | Description | Notes |
|---|---|---|---|
| storefrontOid | Integer | ||
| ownerType | String | [optional] | |
| ownerObjectId | String | [optional] | |
| containerName | String | [optional] |
ultraCartOauth, ultraCartSimpleApiKey
- Content-Type: Not defined
- Accept: application/json
| Status code | Description | Response headers |
|---|---|---|
| 200 | Successful response | - |
| 400 | Status Code 400: bad request input such as invalid json | * UC-REST-ERROR - Contains human readable error message |
| 401 | Status Code 401: invalid credentials supplied | * UC-REST-ERROR - Contains human readable error message |
| 404 | Status Code 404: not found | * UC-REST-ERROR - Contains human readable error message |
| 500 | Status Code 500: any server side error. the body will contain a generic server error message | * UC-REST-ERROR - Contains human readable error message |
SfvbElementsResponse listSfvbElements()
List every SFVB element type
The authoritative vocabulary, taken from the same lookup the compiler uses. A type absent from this list compiles to a literal placeholder line in the page rather than failing, which is why validation treats an unknown type as an error.
(No example for this operation).
This endpoint does not need any parameter.
ultraCartOauth, ultraCartSimpleApiKey
- Content-Type: Not defined
- Accept: application/json
| Status code | Description | Response headers |
|---|---|---|
| 200 | Successful response | - |
| 401 | Status Code 401: invalid credentials supplied | * UC-REST-ERROR - Contains human readable error message |
| 500 | Status Code 500: any server side error. the body will contain a generic server error message | * UC-REST-ERROR - Contains human readable error message |
SfvbFileVersionsResponse listSfvbFileVersions(storefrontOid, path)
Version history for a storefront file
Version history is the undo for anything in the storefront file system, which is what makes an agent's writes recoverable.
(No example for this operation).
| Name | Type | Description | Notes |
|---|---|---|---|
| storefrontOid | Integer | ||
| path | String | [optional] |
ultraCartOauth, ultraCartSimpleApiKey
- Content-Type: Not defined
- Accept: application/json
| Status code | Description | Response headers |
|---|---|---|
| 200 | Successful response | - |
| 400 | Status Code 400: bad request input such as invalid json | * UC-REST-ERROR - Contains human readable error message |
| 401 | Status Code 401: invalid credentials supplied | * UC-REST-ERROR - Contains human readable error message |
| 404 | Status Code 404: not found | * UC-REST-ERROR - Contains human readable error message |
| 500 | Status Code 500: any server side error. the body will contain a generic server error message | * UC-REST-ERROR - Contains human readable error message |
SfvbFilesResponse listSfvbFiles(storefrontOid, path, storefrontFsDirectoryOid, themeOid, maxEntries)
List a storefront directory
Directories first, then files, each sorted by name. Address by path or by directory oid; supplying theme_oid also retries a path that does not resolve at the storefront root relative to that theme, so /theme/css/ works without knowing the theme's directory name. Each file carries its content hash, so a listing is enough to start an If-Match write without a separate read.
(No example for this operation).
| Name | Type | Description | Notes |
|---|---|---|---|
| storefrontOid | Integer | ||
| path | String | [optional] | |
| storefrontFsDirectoryOid | Integer | [optional] | |
| themeOid | Integer | [optional] | |
| maxEntries | Integer | [optional] |
ultraCartOauth, ultraCartSimpleApiKey
- Content-Type: Not defined
- Accept: application/json
| Status code | Description | Response headers |
|---|---|---|
| 200 | Successful response | - |
| 400 | Status Code 400: bad request input such as invalid json | * UC-REST-ERROR - Contains human readable error message |
| 401 | Status Code 401: invalid credentials supplied | * UC-REST-ERROR - Contains human readable error message |
| 404 | Status Code 404: not found | * UC-REST-ERROR - Contains human readable error message |
| 429 | Status Code 429: you have exceeded the allowed API call rate limit for your application. | * UC-REST-ERROR - Contains human readable error message |
| 500 | Status Code 500: any server side error. the body will contain a generic server error message | * UC-REST-ERROR - Contains human readable error message |
SfvbStorefrontsResponse listSfvbStorefronts()
List storefronts
(No example for this operation).
This endpoint does not need any parameter.
ultraCartOauth, ultraCartSimpleApiKey
- Content-Type: Not defined
- Accept: application/json
| Status code | Description | Response headers |
|---|---|---|
| 200 | Successful response | - |
| 401 | Status Code 401: invalid credentials supplied | * UC-REST-ERROR - Contains human readable error message |
| 500 | Status Code 500: any server side error. the body will contain a generic server error message | * UC-REST-ERROR - Contains human readable error message |
SfvbThemesResponse listSfvbThemes(storefrontOid)
List themes for a storefront
Exactly one theme is flagged active. Writing to the active theme is writing live and requires the sfvb_publish scope.
(No example for this operation).
| Name | Type | Description | Notes |
|---|---|---|---|
| storefrontOid | Integer |
ultraCartOauth, ultraCartSimpleApiKey
- Content-Type: Not defined
- Accept: application/json
| Status code | Description | Response headers |
|---|---|---|
| 200 | Successful response | - |
| 400 | Status Code 400: bad request input such as invalid json | * UC-REST-ERROR - Contains human readable error message |
| 401 | Status Code 401: invalid credentials supplied | * UC-REST-ERROR - Contains human readable error message |
| 404 | Status Code 404: not found | * UC-REST-ERROR - Contains human readable error message |
| 500 | Status Code 500: any server side error. the body will contain a generic server error message | * UC-REST-ERROR - Contains human readable error message |
SfvbUpsellOffersResponse listSfvbUpsellOffers(storefrontOid)
List upsell offers
Without container JSON, so the funnel can be surveyed cheaply. A large container size alongside a small element count is the signature of markup pasted into a single html element.
(No example for this operation).
| Name | Type | Description | Notes |
|---|---|---|---|
| storefrontOid | Integer |
ultraCartOauth, ultraCartSimpleApiKey
- Content-Type: Not defined
- Accept: application/json
| Status code | Description | Response headers |
|---|---|---|
| 200 | Successful response | - |
| 400 | Status Code 400: bad request input such as invalid json | * UC-REST-ERROR - Contains human readable error message |
| 401 | Status Code 401: invalid credentials supplied | * UC-REST-ERROR - Contains human readable error message |
| 404 | Status Code 404: not found | * UC-REST-ERROR - Contains human readable error message |
| 500 | Status Code 500: any server side error. the body will contain a generic server error message | * UC-REST-ERROR - Contains human readable error message |
SfvbContainerResponse putSfvbContainer(storefrontOid, ownerType, ownerObjectId, ifMatch, containerWriteRequest, containerName)
Write a container stored outside the file system
Validation is mandatory and runs here regardless of whether the caller validated first. The previous value is snapshotted before the write, so the change can be reverted. Side effects the visual builder performs on save, such as upsell screenshot regeneration and email content review flagging, are applied too.
(No example for this operation).
| Name | Type | Description | Notes |
|---|---|---|---|
| storefrontOid | Integer | ||
| ownerType | String | ||
| ownerObjectId | String | ||
| ifMatch | String | CJSON hash from the last read. Required; 428 when absent, 412 when stale. | |
| containerWriteRequest | SfvbContainerWriteRequest | Container CJSON to write | |
| containerName | String | [optional] |
ultraCartOauth, ultraCartSimpleApiKey
- Content-Type: application/json
- Accept: application/json
| Status code | Description | Response headers |
|---|---|---|
| 200 | Successful response | - |
| 400 | Status Code 400: bad request input such as invalid json | * UC-REST-ERROR - Contains human readable error message |
| 401 | Status Code 401: invalid credentials supplied | * UC-REST-ERROR - Contains human readable error message |
| 404 | Status Code 404: not found | * UC-REST-ERROR - Contains human readable error message |
| 412 | - | |
| 500 | Status Code 500: any server side error. the body will contain a generic server error message | * UC-REST-ERROR - Contains human readable error message |
SfvbFileWriteResponse putSfvbFileContent(storefrontOid, ifMatch, fileWriteRequest, path)
Write a storefront file
Runs the template sandbox, Velocity validation and the internationalization check, records a version, and compiles the sibling .vm when the file is a .cjson under a theme. Send If-Match with the hash from the last read to avoid clobbering a concurrent change. Writing into the active theme requires sfvb_publish.
(No example for this operation).
| Name | Type | Description | Notes |
|---|---|---|---|
| storefrontOid | Integer | ||
| ifMatch | String | Content hash from the last read. Required; 428 when absent, 412 when stale. | |
| fileWriteRequest | SfvbFileWriteRequest | File content to write | |
| path | String | [optional] |
ultraCartOauth, ultraCartSimpleApiKey
- Content-Type: application/json
- Accept: application/json
| Status code | Description | Response headers |
|---|---|---|
| 200 | Successful response | - |
| 400 | Status Code 400: bad request input such as invalid json | * UC-REST-ERROR - Contains human readable error message |
| 401 | Status Code 401: invalid credentials supplied | * UC-REST-ERROR - Contains human readable error message |
| 403 | Status Code 403: forbidden | * UC-REST-ERROR - Contains human readable error message |
| 404 | Status Code 404: not found | * UC-REST-ERROR - Contains human readable error message |
| 412 | - | |
| 413 | - | |
| 500 | Status Code 500: any server side error. the body will contain a generic server error message | * UC-REST-ERROR - Contains human readable error message |
SfvbPreviewSessionResponse putSfvbPreviewSession(storefrontOid, previewSessionId, previewSession, themeOid)
Push containers into a preview session
Stores compiled containers against a session created by createSfvbPreviewSession. Replaces whatever the session held. Nothing durable is written. Requires a token that resolves to a user, so use the device authorization flow.
(No example for this operation).
| Name | Type | Description | Notes |
|---|---|---|---|
| storefrontOid | Integer | ||
| previewSessionId | String | ||
| previewSession | SfvbPreviewSessionRequest | Containers to stage in the preview session | |
| themeOid | Integer | [optional] |
ultraCartOauth, ultraCartSimpleApiKey
- Content-Type: application/json
- Accept: application/json
| Status code | Description | Response headers |
|---|---|---|
| 200 | Successful response | - |
| 400 | Status Code 400: bad request input such as invalid json | * UC-REST-ERROR - Contains human readable error message |
| 401 | Status Code 401: invalid credentials supplied | * UC-REST-ERROR - Contains human readable error message |
| 403 | Status Code 403: forbidden | * UC-REST-ERROR - Contains human readable error message |
| 404 | Status Code 404: not found | * UC-REST-ERROR - Contains human readable error message |
| 500 | Status Code 500: any server side error. the body will contain a generic server error message | * UC-REST-ERROR - Contains human readable error message |
SfvbRenderResponse renderSfvbWidgets(storefrontOid, themeOid, renderRequest)
Render a CJSON node to HTML
Renders one node in the context of a theme and a page. Unlike compile this is stateful. Rendering resolves merchant data, so an element bound to an item renders wrongly, and silently, without a context item id. One node per call, so a node that fails to render fails on its own rather than taking a batch with it, and a failure says why.
(No example for this operation).
| Name | Type | Description | Notes |
|---|---|---|---|
| storefrontOid | Integer | ||
| themeOid | Integer | ||
| renderRequest | SfvbRenderRequest | Widgets to render |
ultraCartOauth, ultraCartSimpleApiKey
- Content-Type: application/json
- Accept: application/json
| Status code | Description | Response headers |
|---|---|---|
| 200 | Successful response | - |
| 400 | Status Code 400: bad request input such as invalid json | * UC-REST-ERROR - Contains human readable error message |
| 401 | Status Code 401: invalid credentials supplied | * UC-REST-ERROR - Contains human readable error message |
| 404 | Status Code 404: not found | * UC-REST-ERROR - Contains human readable error message |
| 429 | Status Code 429: you have exceeded the allowed API call rate limit for your application. | * UC-REST-ERROR - Contains human readable error message |
| 500 | Status Code 500: any server side error. the body will contain a generic server error message | * UC-REST-ERROR - Contains human readable error message |
SfvbWidgetIdsResponse reserveSfvbWidgetIds(storefrontOid, count)
Reserve a block of widget ids
Widget ids are allocated by the server, not invented by the caller. Reserve a block, then form ids as elementType-number. This is the single most likely thing to get wrong on a first write. A POST rather than a GET because it consumes a sequence. A GET that mutates will eventually be prefetched, retried or cached by something that assumed it was safe.
(No example for this operation).
| Name | Type | Description | Notes |
|---|---|---|---|
| storefrontOid | Integer | ||
| count | Integer | [optional] |
ultraCartOauth, ultraCartSimpleApiKey
- Content-Type: Not defined
- Accept: application/json
| Status code | Description | Response headers |
|---|---|---|
| 200 | Successful response | - |
| 400 | Status Code 400: bad request input such as invalid json | * UC-REST-ERROR - Contains human readable error message |
| 401 | Status Code 401: invalid credentials supplied | * UC-REST-ERROR - Contains human readable error message |
| 404 | Status Code 404: not found | * UC-REST-ERROR - Contains human readable error message |
| 500 | Status Code 500: any server side error. the body will contain a generic server error message | * UC-REST-ERROR - Contains human readable error message |
SfvbContainerResponse revertSfvbContainer(storefrontOid, ownerType, ownerObjectId, ifMatch, containerRevertRequest, containerName)
Revert a container stored outside the file system
The restore is itself snapshotted, so a revert can be undone in turn. Reverting to an entry recorded before the container existed removes it again. Addressed through the owning container and guarded by If-Match, because a revert overwrites live content just as much as an ordinary write does.
(No example for this operation).
| Name | Type | Description | Notes |
|---|---|---|---|
| storefrontOid | Integer | ||
| ownerType | String | ||
| ownerObjectId | String | ||
| ifMatch | String | CJSON hash of the container being reverted. Required; 428 when absent, 412 when stale. | |
| containerRevertRequest | SfvbContainerRevertRequest | Version to revert the container to | |
| containerName | String | [optional] |
ultraCartOauth, ultraCartSimpleApiKey
- Content-Type: application/json
- Accept: application/json
| Status code | Description | Response headers |
|---|---|---|
| 200 | Successful response | - |
| 400 | Status Code 400: bad request input such as invalid json | * UC-REST-ERROR - Contains human readable error message |
| 401 | Status Code 401: invalid credentials supplied | * UC-REST-ERROR - Contains human readable error message |
| 403 | Status Code 403: forbidden | * UC-REST-ERROR - Contains human readable error message |
| 404 | Status Code 404: not found | * UC-REST-ERROR - Contains human readable error message |
| 412 | - | |
| 428 | - | |
| 500 | Status Code 500: any server side error. the body will contain a generic server error message | * UC-REST-ERROR - Contains human readable error message |
SfvbFileWriteResponse revertSfvbFile(storefrontOid, ifMatch, fileRevertRequest)
Revert a storefront file to an earlier version
The revert lands as a new version, so it is itself undoable.
(No example for this operation).
| Name | Type | Description | Notes |
|---|---|---|---|
| storefrontOid | Integer | ||
| ifMatch | String | Content hash of the file being reverted. Required; 428 when absent, 412 when stale. | |
| fileRevertRequest | SfvbFileRevertRequest | Version to revert the file to |
ultraCartOauth, ultraCartSimpleApiKey
- Content-Type: application/json
- Accept: application/json
| Status code | Description | Response headers |
|---|---|---|
| 200 | Successful response | - |
| 400 | Status Code 400: bad request input such as invalid json | * UC-REST-ERROR - Contains human readable error message |
| 401 | Status Code 401: invalid credentials supplied | * UC-REST-ERROR - Contains human readable error message |
| 403 | Status Code 403: forbidden | * UC-REST-ERROR - Contains human readable error message |
| 404 | Status Code 404: not found | * UC-REST-ERROR - Contains human readable error message |
| 500 | Status Code 500: any server side error. the body will contain a generic server error message | * UC-REST-ERROR - Contains human readable error message |
SfvbFileSearchResponse searchSfvbFiles(storefrontOid, searchRequest)
Search storefront files
Searches names and, when text is supplied, file contents. For a CLI with no local copy this is the only way to answer where something is defined without walking the whole tree. Results are capped and truncation is always reported.
(No example for this operation).
| Name | Type | Description | Notes |
|---|---|---|---|
| storefrontOid | Integer | ||
| searchRequest | SfvbFileSearchRequest | File search |
ultraCartOauth, ultraCartSimpleApiKey
- Content-Type: application/json
- Accept: application/json
| Status code | Description | Response headers |
|---|---|---|
| 200 | Successful response | - |
| 400 | Status Code 400: bad request input such as invalid json | * UC-REST-ERROR - Contains human readable error message |
| 401 | Status Code 401: invalid credentials supplied | * UC-REST-ERROR - Contains human readable error message |
| 404 | Status Code 404: not found | * UC-REST-ERROR - Contains human readable error message |
| 429 | Status Code 429: you have exceeded the allowed API call rate limit for your application. | * UC-REST-ERROR - Contains human readable error message |
| 500 | Status Code 500: any server side error. the body will contain a generic server error message | * UC-REST-ERROR - Contains human readable error message |
SfvbLibraryResponse searchSfvbLibrary(storefrontOid, segment, search, pageNumber, resultsPerPage)
Search the element library
Known-good CJSON fragments a human already built out of real elements. This is what a lint warning about a monolithic html element should point at - a warning that names a fragment solving the same problem is an instruction, where a warning on its own is only criticism. Results are terse; fetch a single entry for its CJSON. Narrow with facet_{name}={option} query parameters.
(No example for this operation).
| Name | Type | Description | Notes |
|---|---|---|---|
| storefrontOid | Integer | ||
| segment | String | [optional] | |
| search | String | [optional] | |
| pageNumber | Integer | [optional] | |
| resultsPerPage | Integer | [optional] |
ultraCartOauth, ultraCartSimpleApiKey
- Content-Type: Not defined
- Accept: application/json
| Status code | Description | Response headers |
|---|---|---|
| 200 | Successful response | - |
| 400 | Status Code 400: bad request input such as invalid json | * UC-REST-ERROR - Contains human readable error message |
| 401 | Status Code 401: invalid credentials supplied | * UC-REST-ERROR - Contains human readable error message |
| 403 | Status Code 403: forbidden | * UC-REST-ERROR - Contains human readable error message |
| 404 | Status Code 404: not found | * UC-REST-ERROR - Contains human readable error message |
| 500 | Status Code 500: any server side error. the body will contain a generic server error message | * UC-REST-ERROR - Contains human readable error message |
SfvbFileWriteResponse uploadSfvbFile(storefrontOid, fileUploadRequest, ifMatch)
Store a binary asset that was already uploaded
The second half of the two step upload. The bytes are fetched from the key, checked against the extension they claim to be, and written exactly as a text write is - so the same If-Match precondition, the same read only refusal and the same publish gate apply. An SVG is sanitized before it is stored. Writing outside /themes/ requires sfvb_publish, because anything served off the storefront root is live by definition.
(No example for this operation).
| Name | Type | Description | Notes |
|---|---|---|---|
| storefrontOid | Integer | ||
| fileUploadRequest | SfvbFileUploadRequest | Where to store the uploaded bytes | |
| ifMatch | String | Content hash from the last read. Required when the file already exists; 428 when absent, 412 when stale. | [optional] |
ultraCartOauth, ultraCartSimpleApiKey
- Content-Type: application/json
- Accept: application/json
| Status code | Description | Response headers |
|---|---|---|
| 200 | Successful response | - |
| 400 | Status Code 400: bad request input such as invalid json | * UC-REST-ERROR - Contains human readable error message |
| 401 | Status Code 401: invalid credentials supplied | * UC-REST-ERROR - Contains human readable error message |
| 403 | Status Code 403: forbidden | * UC-REST-ERROR - Contains human readable error message |
| 404 | Status Code 404: not found | * UC-REST-ERROR - Contains human readable error message |
| 412 | - | |
| 413 | - | |
| 500 | Status Code 500: any server side error. the body will contain a generic server error message | * UC-REST-ERROR - Contains human readable error message |
SfvbValidationResponse validateSfvbCjson(validateRequest)
Validate CJSON
Runs the structural schema, the contextual business rules for the destination owner type, and the quality lint. A document that fails returns HTTP 200 with valid false rather than a transport error - the request was well formed, the document was not.
(No example for this operation).
| Name | Type | Description | Notes |
|---|---|---|---|
| validateRequest | SfvbValidateRequest | CJSON to validate |
ultraCartOauth, ultraCartSimpleApiKey
- Content-Type: application/json
- Accept: application/json
| Status code | Description | Response headers |
|---|---|---|
| 200 | Successful response | - |
| 400 | Status Code 400: bad request input such as invalid json | * UC-REST-ERROR - Contains human readable error message |
| 401 | Status Code 401: invalid credentials supplied | * UC-REST-ERROR - Contains human readable error message |
| 429 | Status Code 429: you have exceeded the allowed API call rate limit for your application. | * UC-REST-ERROR - Contains human readable error message |
| 500 | Status Code 500: any server side error. the body will contain a generic server error message | * UC-REST-ERROR - Contains human readable error message |
SfvbValidationResponse validateSfvbVelocity(storefrontOid, themeOid, velocityValidateRequest)
Validate a Velocity template against a theme
Theme scoped rather than stateless. Validation builds a theme template context and evaluates against it. Also applies the template sandbox, so an agent learns the rule before a write fails.
(No example for this operation).
| Name | Type | Description | Notes |
|---|---|---|---|
| storefrontOid | Integer | ||
| themeOid | Integer | ||
| velocityValidateRequest | SfvbVelocityValidateRequest | Velocity template to validate |
ultraCartOauth, ultraCartSimpleApiKey
- Content-Type: application/json
- Accept: application/json
| Status code | Description | Response headers |
|---|---|---|
| 200 | Successful response | - |
| 400 | Status Code 400: bad request input such as invalid json | * UC-REST-ERROR - Contains human readable error message |
| 401 | Status Code 401: invalid credentials supplied | * UC-REST-ERROR - Contains human readable error message |
| 404 | Status Code 404: not found | * UC-REST-ERROR - Contains human readable error message |
| 500 | Status Code 500: any server side error. the body will contain a generic server error message | * UC-REST-ERROR - Contains human readable error message |