---
title: "Create a customization (design sketch)"
method: POST
path: "/open-api/v1.0/customizations"
tags: ["Customizations"]
---

# Create a customization (design sketch)

`POST /open-api/v1.0/customizations`

*Rate limit: 5 requests / minute per shop. See [Rate limiting](/guides/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.

## Request body

- CreateCustomizationRequestV1 — 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.
  - `productTemplateId` string, required — Id of the product template the sketch targets, from `GET /open-api/v1.0/product-templates`. Same id space as `CreateDesignProductRequestV1.productTemplateId`.
  - `regions` ProductDesignRegionV1[] — 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.
    - `region` string, required — Name of the product region to place the image on, e.g. `front` or `back`.
    - `imageId` string, required — Id of a registered media-library image to render on the region. Register the image first via `POST /open-api/v1.0/media/images` and pass the returned id here.
    - `placementId` string — Placement to target when `placementStrategy` is `PLACEMENT_ID`. Required for that strategy and ignored by the others.
    - `placementStrategy` 'AUTO' | 'FILL_ALL' | 'FULL_REGION' | 'PLACEMENT_ID' — How the image is placed on the region. Defaults to `AUTO` when omitted, and takes precedence over `placementId`/`fillAllPlacements`. - `AUTO` — let the renderer decide using the product's automation defaults (its preferred placement, or fill-all for products like mugs/stickers). - `FILL_ALL` — apply the image to every placement in the region. - `FULL_REGION` — render the image across the full region, skipping the preferred placement. - `PLACEMENT_ID` — target the single placement named by `placementId` (required for this strategy).
  - `colors` string[] — Colors to render. Defaults to all available product colors.
  - `sizes` string[] — Sizes to include. Defaults to all available product sizes.

## Response `201`

Created

- CreateCustomizationResponseV1 — Response from creating a customization. `pipelineId` and `images` are populated only when `regions` were supplied in the request.
  - `customizationId` string, required — Id of the newly created customization sketch.
  - `pipelineId` string — Id of the design pipeline run; null when no regions were supplied.
  - `images` ComFourthwallOpenapiModelDesignpipelineDesignPipelineImageV1[], required — Rendered preview images. Empty when no regions were supplied.
    - `url` string, required
    - `width` integer, required
    - `height` integer, required
    - `style` string, required
    - `color` string, required
    - `size` string
    - `region` string

## Other responses

- `400` — Possible errors: `CUSTOMIZATION_ALREADY_USED_ERROR`, `CUSTOMIZATION_FOR_REQUESTABLE_PRODUCT_ERROR`, `CUSTOMIZATION_OPTION_DO_NOT_EXISTS`, `CUSTOMIZATION_REGIONS_DUPLICATION`, `CUSTOMIZATION_TOO_MANY_VARIANTS`, `DESIGN_PIPELINE_BACKEND_RENDERING_NOT_SUPPORTED`, `DESIGN_PIPELINE_INVALID_REGIONS`, `DESIGNER_NOT_SUPPORTED_PRODUCT_ERROR`, `MISSING_PRICE_FOR_SIZE_ERROR`, `MISSING_VERSION_ERROR`, `OFFER_INVALID_STATE_ERROR`, `RENDERING_PRODUCT_NOT_SUPPORTED_ERROR`, `UNTRUSTED_ASSET_SOURCE_ERROR`, `VARIANT_MISSING_SIZE_ERROR`
- `404` — Possible errors: `MEDIA_FILE_DO_NOT_EXISTS`, `OFFER_BY_CUSTOMIZATION_ID_AND_SHOP_ID_NOT_FOUND`, `OFFER_BY_CUSTOMIZATION_ID_NOT_FOUND_ERROR`, `OFFER_NOT_FOUND_BY_SHOP_ID_AND_ID_ERROR`, `PRODUCT_CATALOG_PRODUCT_ID_NOT_FOUND`, `RENDERING_NOT_SCHEDULED_ERROR`, `SHOP_TEAM_MEMBER_SHOP_NOT_FOUND_ERROR`
- `406` — Possible errors: `PRICING_CALCULATION_NOT_SUPPORTED`
- `409` — Possible errors: `SQL_CONSTRAINTS_ERROR`
- `429` — Rate limited: 5 requests / minute per shop (effective limit). All applicable limits: - `customization-unauth-rate-limiter` — 50 requests / 10 seconds per client IP - `open-api-heavy-rate-limiter` — 5 requests / minute per shop - `open-api-rate-limiter` — 100 requests / 10 seconds per shop

---

[API](https://skmtc.net/fourthwall/apis/fourthwall-apis-2.md) · [All operations](https://skmtc.net/fourthwall/apis/fourthwall-apis-2/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/fourthwall/fourthwall-apis-2/revisions/ef273312f051/schema)