Create a customization (design sketch)
curl --request POST \
--url https://api.fourthwall.com/open-api/v1.0/customizations \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"productTemplateId": "pro_k66ZW4fsRm6c2def3itltA",
"regions": [
{
"region": "front",
"imageId": "img_k66ZW4fsRm6c2def3itltA",
"placementId": "<string>",
"placementStrategy": "AUTO"
}
],
"colors": [
"<string>"
],
"sizes": [
"<string>"
]
}
'import requests
url = "https://api.fourthwall.com/open-api/v1.0/customizations"
payload = {
"productTemplateId": "pro_k66ZW4fsRm6c2def3itltA",
"regions": [
{
"region": "front",
"imageId": "img_k66ZW4fsRm6c2def3itltA",
"placementId": "<string>",
"placementStrategy": "AUTO"
}
],
"colors": ["<string>"],
"sizes": ["<string>"]
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
productTemplateId: 'pro_k66ZW4fsRm6c2def3itltA',
regions: [
{
region: 'front',
imageId: 'img_k66ZW4fsRm6c2def3itltA',
placementId: '<string>',
placementStrategy: 'AUTO'
}
],
colors: ['<string>'],
sizes: ['<string>']
})
};
fetch('https://api.fourthwall.com/open-api/v1.0/customizations', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.fourthwall.com/open-api/v1.0/customizations",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'productTemplateId' => 'pro_k66ZW4fsRm6c2def3itltA',
'regions' => [
[
'region' => 'front',
'imageId' => 'img_k66ZW4fsRm6c2def3itltA',
'placementId' => '<string>',
'placementStrategy' => 'AUTO'
]
],
'colors' => [
'<string>'
],
'sizes' => [
'<string>'
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.fourthwall.com/open-api/v1.0/customizations"
payload := strings.NewReader("{\n \"productTemplateId\": \"pro_k66ZW4fsRm6c2def3itltA\",\n \"regions\": [\n {\n \"region\": \"front\",\n \"imageId\": \"img_k66ZW4fsRm6c2def3itltA\",\n \"placementId\": \"<string>\",\n \"placementStrategy\": \"AUTO\"\n }\n ],\n \"colors\": [\n \"<string>\"\n ],\n \"sizes\": [\n \"<string>\"\n ]\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.fourthwall.com/open-api/v1.0/customizations")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"productTemplateId\": \"pro_k66ZW4fsRm6c2def3itltA\",\n \"regions\": [\n {\n \"region\": \"front\",\n \"imageId\": \"img_k66ZW4fsRm6c2def3itltA\",\n \"placementId\": \"<string>\",\n \"placementStrategy\": \"AUTO\"\n }\n ],\n \"colors\": [\n \"<string>\"\n ],\n \"sizes\": [\n \"<string>\"\n ]\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.fourthwall.com/open-api/v1.0/customizations")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"productTemplateId\": \"pro_k66ZW4fsRm6c2def3itltA\",\n \"regions\": [\n {\n \"region\": \"front\",\n \"imageId\": \"img_k66ZW4fsRm6c2def3itltA\",\n \"placementId\": \"<string>\",\n \"placementStrategy\": \"AUTO\"\n }\n ],\n \"colors\": [\n \"<string>\"\n ],\n \"sizes\": [\n \"<string>\"\n ]\n}"
response = http.request(request)
puts response.read_body{
"customizationId": "cst_k66ZW4fsRm6c2def3itltA",
"images": [
{
"url": "<string>",
"width": 123,
"height": 123,
"style": "<string>",
"color": "<string>",
"size": "<string>",
"region": "<string>"
}
],
"pipelineId": "dpl_k66ZW4fsRm6c2def3itltA"
}Customization
Create a new customization
Rate limit: 5 requests / minute per shop. See Rate limiting.
Creates a shop-bound customization sketch on a product template. When regions are supplied, the sync design pipeline runs immediately and the response carries the rendered preview images. With no regions, only the sketch is created (pipelineId: null, images: []). Iteration = re-POST with adjusted selections; there is no update-in-place.
POST
/
open-api
/
v1.0
/
customizations
Create a customization (design sketch)
curl --request POST \
--url https://api.fourthwall.com/open-api/v1.0/customizations \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"productTemplateId": "pro_k66ZW4fsRm6c2def3itltA",
"regions": [
{
"region": "front",
"imageId": "img_k66ZW4fsRm6c2def3itltA",
"placementId": "<string>",
"placementStrategy": "AUTO"
}
],
"colors": [
"<string>"
],
"sizes": [
"<string>"
]
}
'import requests
url = "https://api.fourthwall.com/open-api/v1.0/customizations"
payload = {
"productTemplateId": "pro_k66ZW4fsRm6c2def3itltA",
"regions": [
{
"region": "front",
"imageId": "img_k66ZW4fsRm6c2def3itltA",
"placementId": "<string>",
"placementStrategy": "AUTO"
}
],
"colors": ["<string>"],
"sizes": ["<string>"]
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
productTemplateId: 'pro_k66ZW4fsRm6c2def3itltA',
regions: [
{
region: 'front',
imageId: 'img_k66ZW4fsRm6c2def3itltA',
placementId: '<string>',
placementStrategy: 'AUTO'
}
],
colors: ['<string>'],
sizes: ['<string>']
})
};
fetch('https://api.fourthwall.com/open-api/v1.0/customizations', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.fourthwall.com/open-api/v1.0/customizations",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'productTemplateId' => 'pro_k66ZW4fsRm6c2def3itltA',
'regions' => [
[
'region' => 'front',
'imageId' => 'img_k66ZW4fsRm6c2def3itltA',
'placementId' => '<string>',
'placementStrategy' => 'AUTO'
]
],
'colors' => [
'<string>'
],
'sizes' => [
'<string>'
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.fourthwall.com/open-api/v1.0/customizations"
payload := strings.NewReader("{\n \"productTemplateId\": \"pro_k66ZW4fsRm6c2def3itltA\",\n \"regions\": [\n {\n \"region\": \"front\",\n \"imageId\": \"img_k66ZW4fsRm6c2def3itltA\",\n \"placementId\": \"<string>\",\n \"placementStrategy\": \"AUTO\"\n }\n ],\n \"colors\": [\n \"<string>\"\n ],\n \"sizes\": [\n \"<string>\"\n ]\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.fourthwall.com/open-api/v1.0/customizations")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"productTemplateId\": \"pro_k66ZW4fsRm6c2def3itltA\",\n \"regions\": [\n {\n \"region\": \"front\",\n \"imageId\": \"img_k66ZW4fsRm6c2def3itltA\",\n \"placementId\": \"<string>\",\n \"placementStrategy\": \"AUTO\"\n }\n ],\n \"colors\": [\n \"<string>\"\n ],\n \"sizes\": [\n \"<string>\"\n ]\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.fourthwall.com/open-api/v1.0/customizations")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"productTemplateId\": \"pro_k66ZW4fsRm6c2def3itltA\",\n \"regions\": [\n {\n \"region\": \"front\",\n \"imageId\": \"img_k66ZW4fsRm6c2def3itltA\",\n \"placementId\": \"<string>\",\n \"placementStrategy\": \"AUTO\"\n }\n ],\n \"colors\": [\n \"<string>\"\n ],\n \"sizes\": [\n \"<string>\"\n ]\n}"
response = http.request(request)
puts response.read_body{
"customizationId": "cst_k66ZW4fsRm6c2def3itltA",
"images": [
{
"url": "<string>",
"width": 123,
"height": 123,
"style": "<string>",
"color": "<string>",
"size": "<string>",
"region": "<string>"
}
],
"pipelineId": "dpl_k66ZW4fsRm6c2def3itltA"
}OAuth scope:
offer_writeAPI keys have full access to this endpoint.Authorizations
bearerAuthbasicAuth
OAuth 2.0 access token, sent as Authorization: Bearer <token>. See https://docs.fourthwall.com/guides/oauth. The scopes an operation requires are listed in its x-fourthwall-scopes.
Body
application/json
Create a shop-bound customization (design sketch) for a product template. When regions are supplied, the sync design pipeline runs immediately and the response carries the rendered preview images; with no regions, only the sketch is created and the response carries pipelineId: null and an empty images list. To iterate, re-POST with adjusted selections — there is no update-in-place.
Id of the product template the sketch targets, from GET /open-api/v1.0/product-templates. Same id space as CreateDesignProductRequestV1.productTemplateId.
Example:
"pro_k66ZW4fsRm6c2def3itltA"
Design regions to render on the product. Each region references a registered media-library image by id (register first via POST /open-api/v1.0/media/images and pass the returned id as imageId). Omit or pass an empty list to create the sketch without running the pipeline.
Show child attributes
Show child attributes
Colors to render. Defaults to all available product colors.
Sizes to include. Defaults to all available product sizes.
Response
Created
Response from creating a customization. pipelineId and images are populated only when regions were supplied in the request.
Id of the newly created customization sketch.
Example:
"cst_k66ZW4fsRm6c2def3itltA"
Rendered preview images. Empty when no regions were supplied.
Show child attributes
Show child attributes
Id of the design pipeline run; null when no regions were supplied.
Example:
"dpl_k66ZW4fsRm6c2def3itltA"