US Market New Function：POD Customization Config APIs

TikTok Shop now supports configuring Print-on-Demand (POD) customization for Made-to-Order (MTO) products through the Product APIs. ISVs and seller applications can upload customization assets, submit template configurations, and retrieve the saved configuration programmatically. With this capability, an integration can:

• Upload background, mask, and default customization images.
• Associate one or more SKUs with a POD template.
• Define product surfaces and ordered image or text customization areas.
• Read back the resulting POD configuration and returned image metadata.

What’s New

To support POD image uploads, add CUSTOMIZATION_IMAGE to the request use_case enum. The response structure is unchanged.

What ISVs Need to Do

Required to support POD customization

1. Update the image upload enum. Add CUSTOMIZATION_IMAGE to the supported use_case values.
2. Upload assets first. Upload each background image, mask image, and default image with use_case=CUSTOMIZATION_IMAGE, then retain the returned uri.
3. Extend the edit request model. Add optional pod_info support to Partial Edit Product and build the hierarchy pod_info → pod_templates[] → surfaces[] → custom_areas[].
4. Implement type-specific areas. Send image_area when area_type=IMAGE, or text_area when area_type=TEXT.
5. Extend the read model. Parse pod_info from Get Product, including the additional metadata returned for image objects.
6. Validate before submission. Enforce SKU uniqueness, list limits, layer ordering, enum casing, two-decimal placement strings, and the documented image URI requirements.
7. Read back after an update. Call Get Product to verify the saved configuration and retain the system-generated pod_template_id for future reads and updates.

Recommended for all existing integrations

• Make response deserialization tolerant of the new optional pod_info field and future optional fields.
• Add CUSTOMIZATION_IMAGE to strict enum parsers, even if the integration does not yet create POD configuration.
• Do not treat an absent pod_info object as an error for a non-POD product.

Integration Flow

Image

1. Upload customization images with Upload Product Image and keep each returned uri.
2. Build the POD configuration using templates, SKU associations, surfaces, ordered areas, and the uploaded image URIs.
3. Submit pod_info through Partial Edit Product.
4. Call Get Product to read back the stored configuration and image metadata.

Integration Details

1. Upload Product Image

Use CUSTOMIZATION_IMAGE for images that render or preview consumer-customizable content, including:

• surface background images;
• surface mask images;
• default images for image customization areas.

The existing upload constraints remain unchanged: supported formats are JPG, JPEG, PNG, WEBP, HEIC, and BMP; the maximum file size is 10 MB; the general accepted dimension range is 100 × 100 through 20,000 × 20,000 pixels. Existing use-case-specific requirements continue to apply.

2. Partial Edit Product

Send pod_info when creating or updating POD customization configuration for an MTO product that supports this capability. A new template does not require pod_template_id; the identifier is generated by the system. The POD fields are optional. Include image_area when area_type=IMAGE, and include text_area when area_type=TEXT.

3. Get Product

The returned configuration uses the same template, surface, area, placement, image-area, and text-area structure. Image objects include additional read-only metadata:

POD Data Model and Validation Rules

Template and surface hierarchy

Customization areas and placement

Type-specific area objects

Key validation summary: one SKU may belong to only one template; each template supports up to 10 surfaces; each surface supports up to 10 areas; the custom_areas array order is the layer order; image URIs must come from a CUSTOMIZATION_IMAGE upload.

Request Example

The following request fragment shows a POD configuration with one image area and one text area. pod_template_id is omitted because the template is new.

{
  "pod_info": {
    "pod_templates": [
      {
        "template_name": "Summer T-shirt Customization",
        "remark": "Primary customization template",
        "sku_ids": ["SKU_001", "SKU_002"],
        "surfaces": [
          {
            "external_surface_id": "front",
            "surface_name": "Front Side",
            "background_image": {
              "uri": "YOUR_BACKGROUND_IMAGE_URI"
            },
            "mask_image": {
              "uri": "YOUR_MASK_IMAGE_URI"
            },
            "custom_areas": [
              {
                "external_area_id": "logo",
                "area_name": "Logo Area",
                "area_type": "IMAGE",
                "is_required": true,
                "area_placement": {
                  "x_coordinate": "400.00",
                  "y_coordinate": "300.00",
                  "width": "200.00",
                  "height": "200.00",
                  "rotate_degree": "0.00"
                },
                "image_area": {
                  "min_width": 200,
                  "min_height": 200,
                  "default_image": {
                    "uri": "YOUR_DEFAULT_IMAGE_URI"
                  }
                }
              },
              {
                "external_area_id": "slogan",
                "area_name": "Slogan Text",
                "area_type": "TEXT",
                "is_required": false,
                "area_placement": {
                  "x_coordinate": "300.00",
                  "y_coordinate": "550.00",
                  "width": "400.00",
                  "height": "50.00",
                  "rotate_degree": "0.00"
                },
                "text_area": {
                  "default_text": "Your Text Here",
                  "max_text_length": 20,
                  "fonts": ["YOUR_SUPPORTED_FONT_KEY_1", "YOUR_SUPPORTED_FONT_KEY_2"],
                  "colors": ["#FFFFFF", "#000000", "#FF0000"],
                  "align_type": "CENTER"
                }
              }
            ]
          }
        ]
      }
    ]
  }
}

Compatibility and Testing

Backward compatibility

These API changes are additive. Existing integrations that do not create POD configurations do not need to send pod_info.

• For non-POD products, pod_info may be absent.
• Response models should accept the new optional object and unknown optional fields.
• Strict enum models should recognize CUSTOMIZATION_IMAGE, IMAGE, TEXT, LEFT, CENTER, and RIGHT where applicable.

Recommended test coverage

• Create a template without pod_template_id, then confirm the generated ID through Get Product.
• Upload and reference background, mask, and default images using CUSTOMIZATION_IMAGE.
• Validate both IMAGE and TEXT area payloads.
• Verify decimal-string serialization for all five area_placement fields.
• Verify custom-area list order is preserved during readback.
• Reject duplicate SKU assignment across templates.
• Test the 10-surface-per-template and 10-area-per-surface limits.
• Confirm Get Product parsing for urls[], thumb_urls[], and image dimensions.
• Regression-test non-POD products and products with no pod_info.