Submit a Product Batch#

POST https://sdkapi.ideal.house/product-import/products

Request Body#

Send processImages as a JSON boolean (true or false), not a string such as "true" or "false". Existing integrations that need image preprocessing must now explicitly send processImages: true.

Product Fields#

Re-import Existing Products#

To update product data, submit the product again through POST /product-import/products. Products are matched by shopId and sku. When the same SKU already exists in the shop, the existing product record is updated instead of creating a duplicate, and values supplied by the latest import overwrite the corresponding stored values, including fields such as name, product URLs, status, and dimensions.

The batch import endpoint is not a partial-update endpoint. Every submitted item must satisfy all required product-field rules, even when the SKU already exists.

The SKU is the import identity and cannot be renamed through re-import. Submitting a different SKU creates or updates a different product. To replace a SKU, logically delete the old product and import the product under the new SKU.

Product information is updated even when the image has not changed. Image processing is optional on each submission: set processImages: true when needed. A product previously imported without image processing can be submitted again with this option enabled.

Supported Product Types#

The API accepts the following exact, case-sensitive productType values. Multiple names in a row are aliases for the same Ideal House product type.

For example, "Rugs", "Area Rugs", and "Area Rug" are all valid and are treated as the same product type. Any value not listed above returns 400 Bad Request.

Import Status#

The optional status field accepts the following exact values:

Any other value, including sold_out, returns 400 Bad Request.

For Furniture, non-active submissions return product status: inactive. An active submission may return unprocessed, meaning the product is not yet ready for display. This does not mean that 3D generation has been requested.

Furniture 3D Model Generation#

Furniture 3D model generation is time-consuming and consumes credits, so it is not performed during product import, even when processImages is true. We plan to provide a generation action in the user interface or a separate 3D generation API in the future. If you need 3D models now, please email your Ideal House contact so that we can arrange generation separately.

SKU and Update Behavior#

Ideal House identifies a product by the combination of shopId and sku:

• If the SKU does not exist for the shop, a new product is created.
• If the SKU already exists for the shop, the existing product is updated.

This makes it safe to resubmit a product with the same SKU after an uncertain network result. Use stable SKUs and do not generate a new SKU when retrying the same product. Avoid sending the same SKU more than once in a single batch.

Image Requirements#

• The URL must be reachable by the Ideal House servers without cookies, login sessions, or custom request headers.
• Use a stable URL that returns the image directly.
• Keep the source image available until the import job reaches a terminal status.
• Image download or processing problems are reported as item-level failures.
• To create Floor plank images, set both processImages: true and processFloorImages: true.

Optional Image Processing and Credits#

Image preprocessing is disabled by default:

• With processImages: false or when the field is omitted, active products use their original images without background removal, texture optimization, or floor splitting. Product information is still imported or updated, and no image-processing credit is charged. Non-active products follow the status rules described above.
• With processImages: true, supported active products receive the image processing described below. Furniture 3D generation is not included.

The main processing behaviors are:

Mural and Wall Mural receive the same image improvements as Wall. For the best results, provide complete, clear product images; Rugs and regular Wall Art should have white or near-white backgrounds, and Wall images should avoid severe perspective distortion.

The image processing described above costs 1 credit per newly processed image, including Wall texture optimization. If an existing processed result can be used, no additional processing credit is charged. Ensure sufficient credits before enabling this option. With insufficient credits, image processing will not proceed and the product may remain unprocessed. A completed import batch does not by itself confirm that every product image was processed successfully.

Dimension Requirements#

The API does not have a separate dimension-unit field. width is required. height is normally required, while a Floor product may provide length instead; when both are present, length is used as the floor plank length. Unitless numbers and numeric strings are interpreted as inches. Strings may include in, ft, cm, mm, or m; values are validated as positive dimensions and normalized to inches before storage. thickness is optional and also accepts a range such as "3-4 mm", which is normalized to "0.1-0.2 in".

dimension_display is an optional display label and is not used for size validation or unit conversion. It may use the customer-facing unit and format you want to show, for example "24 in x 36 in" or "26 cm x 36 cm".

Example Request#

{
  "shopId": "shop_123",
  "processImages": false,
  "processFloorImages": false,
  "products": [
    {
      "sku": "SKU-10001",
      "name": "Gold Wall Mirror",
      "imageUrl": "https://cdn.example.com/products/SKU-10001.png",
      "productUrl": "https://www.example.com/products/SKU-10001",
      "width": "24.0 in",
      "height": "36.0 in",
      "thickness": "2.0 in",
      "dimension_display": "24 in x 36 in",
      "category": "Mirror",
      "color": "Gold",
      "brand": "Example Brand",
      "productType": "Wall Art",
      "status": "active",
      "groupId": "mirror-series-01"
    },
    {
      "sku": "SKU-10002",
      "name": "Black Wall Mirror",
      "imageUrl": "https://cdn.example.com/products/SKU-10002.png",
      "productUrl": "https://www.example.com/products/SKU-10002",
      "width": "2 ft",
      "height": "3 ft",
      "thickness": "3-4 mm",
      "dimension_display": "2 ft x 3 ft",
      "category": "Mirror",
      "color": "Black",
      "brand": "Example Brand",
      "productType": "Wall Art",
      "status": "out_of_stock",
      "groupId": "mirror-series-01"
    }
  ]
}

cURL Example (Image Processing Enabled)#

This example explicitly enables image preprocessing. A new background-removal result consumes 1 credit.

curl --request POST \
  'https://sdkapi.ideal.house/product-import/products' \
  --header 'Content-Type: application/json' \
  --header 'X-Client-Id: <YOUR_CLIENT_ID>' \
  --header 'X-Client-Secret: <YOUR_CLIENT_SECRET>' \
  --data-raw '{
    "shopId": "shop_123",
    "processImages": true,
    "products": [
      {
        "sku": "SKU-10001",
        "name": "Gold Wall Mirror",
        "imageUrl": "https://cdn.example.com/products/SKU-10001.png",
        "productUrl": "https://www.example.com/products/SKU-10001",
        "width": 24,
        "height": 36,
        "thickness": 2,
        "dimension_display": "24 in x 36 in",
        "category": "Mirror",
        "color": "Gold",
        "brand": "Example Brand",
        "productType": "Wall Art",
        "status": "active",
        "groupId": "mirror-series-01"
      }
    ]
  }'

Accepted Response#

A valid request returns 202 Accepted. Processing continues asynchronously.

{
  "jobId": "1930000000000000000",
  "shopId": "shop_123",
  "status": "pending",
  "totalCount": 1,
  "processedCount": 0,
  "successCount": 0,
  "failedCount": 0,
  "failures": [],
  "createdAt": "2026-07-21T06:30:00.000Z",
  "startedAt": null,
  "updatedAt": "2026-07-21T06:30:00.000Z",
  "completedAt": null,
  "error": null
}

If the shop already has a pending or running job, the API returns 409 Conflict. Wait for the current job to finish before submitting another batch.