> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fourthwall.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Create a new customization

> *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.

<Note>
  **OAuth scope:** `offer_write`

  API keys have full access to this endpoint.
</Note>


## OpenAPI

````yaml POST /open-api/v1.0/customizations
openapi: 3.1.0
info:
  title: Fourthwall APIs
  description: Service used for management of orders, carts, and payments.
  termsOfService: https://fourthwall.com/terms-of-service
  contact:
    name: Backend team
    url: https://fourthwall.com
    email: backend@fourthwall.com
  version: unspecified
servers:
  - url: https://api.fourthwall.com
    description: Production server
security: []
externalDocs:
  description: OpenAPI documentation
  url: https://docs.fourthwall.com
paths:
  /open-api/v1.0/customizations:
    post:
      tags:
        - Customizations
      summary: Create a customization (design sketch)
      description: >-
        *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.
      operationId: create-customization
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateCustomizationRequestV1'
        required: true
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateCustomizationResponseV1'
        '400':
          description: >-
            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`
          content:
            application/json:
              examples:
                customization-already-used-error:
                  value:
                    code: CUSTOMIZATION_ALREADY_USED_ERROR
                    customizationId: <customizationid?>
                customization-for-requestable-product-error:
                  value:
                    code: CUSTOMIZATION_FOR_REQUESTABLE_PRODUCT_ERROR
                    productId: <productid>
                customization-option-do-not-exists:
                  value:
                    code: CUSTOMIZATION_OPTION_DO_NOT_EXISTS
                    type: <string>
                    name: <string>
                    productId: <productid>
                customization-regions-duplication:
                  value:
                    code: CUSTOMIZATION_REGIONS_DUPLICATION
                    regions: <list>
                customization-too-many-variants:
                  value:
                    code: CUSTOMIZATION_TOO_MANY_VARIANTS
                    newColorCount: <int>
                    newSizeCount: <int>
                    newVariantCount: <int>
                    max: <int>
                design-pipeline-backend-rendering-not-supported:
                  value:
                    code: DESIGN_PIPELINE_BACKEND_RENDERING_NOT_SUPPORTED
                    reason: <string>
                design-pipeline-invalid-regions:
                  value:
                    code: DESIGN_PIPELINE_INVALID_REGIONS
                    invalidRegions: <set>
                    validRegions: <set>
                designer-not-supported-product-error:
                  value:
                    code: DESIGNER_NOT_SUPPORTED_PRODUCT_ERROR
                    productId: <productid>
                missing-price-for-size-error:
                  value:
                    code: MISSING_PRICE_FOR_SIZE_ERROR
                    size: <string>
                missing-version-error:
                  value:
                    code: MISSING_VERSION_ERROR
                    customizationId: <customizationid>
                offer-invalid-state-error:
                  value:
                    code: OFFER_INVALID_STATE_ERROR
                    offerId: <offerid>
                    state: <offersimplestatus>
                rendering-product-not-supported-error:
                  value:
                    code: RENDERING_PRODUCT_NOT_SUPPORTED_ERROR
                    productId: <string>
                untrusted-asset-source-error:
                  value:
                    code: UNTRUSTED_ASSET_SOURCE_ERROR
                    uri: <uri>
                variant-missing-size-error:
                  value:
                    code: VARIANT_MISSING_SIZE_ERROR
        '404':
          description: >-
            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`
          content:
            application/json:
              examples:
                media-file-do-not-exists:
                  value:
                    code: MEDIA_FILE_DO_NOT_EXISTS
                    uri: <uri>
                offer-by-customization-id-and-shop-id-not-found:
                  value:
                    code: OFFER_BY_CUSTOMIZATION_ID_AND_SHOP_ID_NOT_FOUND
                    customizationId: <customizationid>
                    shopId: <shopid>
                offer-by-customization-id-not-found-error:
                  value:
                    code: OFFER_BY_CUSTOMIZATION_ID_NOT_FOUND_ERROR
                    customizationId: <customizationid>
                offer-not-found-by-shop-id-and-id-error:
                  value:
                    code: OFFER_NOT_FOUND_BY_SHOP_ID_AND_ID_ERROR
                    shopId: <shopid>
                    offerId: <offerid>
                product-catalog-product-id-not-found:
                  value:
                    code: PRODUCT_CATALOG_PRODUCT_ID_NOT_FOUND
                    id: <productid>
                rendering-not-scheduled-error:
                  value:
                    code: RENDERING_NOT_SCHEDULED_ERROR
                    customizationId: <string>
                shop-team-member-shop-not-found-error:
                  value:
                    code: SHOP_TEAM_MEMBER_SHOP_NOT_FOUND_ERROR
                    shopId: <shopid>
        '406':
          description: 'Possible errors: `PRICING_CALCULATION_NOT_SUPPORTED`'
          content:
            application/json:
              examples:
                pricing-calculation-not-supported:
                  value:
                    code: PRICING_CALCULATION_NOT_SUPPORTED
                    customizationType: <customizationversiontype>
        '409':
          description: 'Possible errors: `SQL_CONSTRAINTS_ERROR`'
          content:
            application/json:
              examples:
                sql-constraints-error:
                  value:
                    code: SQL_CONSTRAINTS_ERROR
                    table: <string?>
                    constraint: <string?>
                    msg: <string?>
        '429':
          description: >-
            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
          content:
            application/json:
              examples:
                too-many-requests:
                  value:
                    code: OPEN_API_TOO_MANY_REQUESTS
                    title: Too many requests
                    status: 429
      security:
        - oauth:
            - offer_write
        - basicAuth: []
components:
  schemas:
    CreateCustomizationRequestV1:
      type: object
      description: >-
        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.
      properties:
        productTemplateId:
          type: string
          description: >-
            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
        regions:
          type: array
          description: >-
            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.
          items:
            $ref: '#/components/schemas/ProductDesignRegionV1'
        colors:
          type: array
          description: Colors to render. Defaults to all available product colors.
          items:
            type: string
        sizes:
          type: array
          description: Sizes to include. Defaults to all available product sizes.
          items:
            type: string
      required:
        - productTemplateId
      title: Create Customization Request
    CreateCustomizationResponseV1:
      type: object
      description: >-
        Response from creating a customization. `pipelineId` and `images` are
        populated only when `regions` were supplied in the request.
      properties:
        customizationId:
          type: string
          description: Id of the newly created customization sketch.
          example: cst_k66ZW4fsRm6c2def3itltA
        pipelineId:
          type: string
          description: Id of the design pipeline run; null when no regions were supplied.
          example: dpl_k66ZW4fsRm6c2def3itltA
        images:
          type: array
          description: Rendered preview images. Empty when no regions were supplied.
          items:
            $ref: >-
              #/components/schemas/com.fourthwall.openapi.model.designpipeline.DesignPipelineImageV1
      required:
        - customizationId
        - images
      title: Create Customization Response
    ProductDesignRegionV1:
      type: object
      description: A product region paired with the registered media image to render on it.
      properties:
        region:
          type: string
          description: >-
            Name of the product region to place the image on, e.g. `front` or
            `back`.
          example: front
        imageId:
          type: string
          description: >-
            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.
          example: img_k66ZW4fsRm6c2def3itltA
        placementId:
          type: string
          description: >-
            Placement to target when `placementStrategy` is `PLACEMENT_ID`.
            Required for that strategy and ignored by the others.
        placementStrategy:
          type: string
          description: >-
            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).
          enum:
            - AUTO
            - FILL_ALL
            - FULL_REGION
            - PLACEMENT_ID
          example: AUTO
      required:
        - imageId
        - region
      title: Product Design Region
    com.fourthwall.openapi.model.designpipeline.DesignPipelineImageV1:
      type: object
      properties:
        url:
          type: string
        width:
          type: integer
          format: int32
        height:
          type: integer
          format: int32
        style:
          type: string
        color:
          type: string
        size:
          type: string
        region:
          type: string
      required:
        - color
        - height
        - style
        - url
        - width
      title: Design Pipeline Image
  securitySchemes:
    oauth:
      type: oauth2
      flows:
        implicit:
          authorizationUrl: >-
            https://auth.staging.fourthwall.com/auth/realms/Fourthwall/protocol/openid-connect/auth
          scopes:
            donation_read: donation_read
            order_read: order_read
            order_write: order_write
            fulfillment_write: fulfillment_write
            giveaway_read: giveaway_read
            giveaway_write: giveaway_write
            memberships_read: memberships_read
            memberships_write: memberships_write
            promotions_write: promotions_write
            promotions_read: promotions_read
            offer_read: offer_read
            offer_write: offer_write
            shop_read: shop_read
            thankyou_read: thankyou_read
            thankyou_write: thankyou_write
            webhook_read: webhook_read
            webhook_write: webhook_write
            media_read: media_read
            media_write: media_write
            analytics_read: analytics_read
            samples_read: samples_read
            samples_write: samples_write
            dns_read: dns_read
            dns_write: dns_write
            settings_read: settings_read
            payout_read: payout_read
            integrations_read: integrations_read
    basicAuth:
      type: http
      scheme: basic

````