/product-listings/{platform}

Submit a product for listing on a marketplace. This is the same AI enrichment flow the Wherehouse app uses: Wherehouse maps your product to a marketplace category, fills the required attributes, and creates the marketplace draft or QC submission.

The call is synchronous up to the point of submission, then marketplace QC takes over. A 200 means the marketplace accepted the submission, not that the listing is live. Follow it with GET /product-listings.

Each accepted submission spends one listing credit.

Platforms

Pass the platform uid in the path: takealot, amazon, makro, leroy_merlin, shopify, loot, woocommerce. The platform must already be connected and authorised in Wherehouse, otherwise you get 404 connector_not_found.

Picking the seller account

Connected accounts for the platform	What to send
One	Nothing, it is used automatically
More than one	`seller_id`

Omitting seller_id when several accounts are connected returns 409 connector_selection_required with an available_accounts array. Retry with one of those seller_id values.

New product or existing product

`create_product`	Unknown `product.code`	Extra fields in `product`
`false` (default)	`404 product_not_found`	One-off listing overrides. Your stored product is not changed.
`true`	Product is created first	Saved onto the new product.

This is the important distinction. With create_product: false you can send a marketplace friendly title or description for this submission only, and your catalogue keeps its own values. With create_product: true the same fields become the product record, and the create validation from POST /products applies (title, soh, and retail_price or cost_price). A code that already exists returns 409 product_already_exists.

Catalogue scoping

Every API key is granted one or more catalogues, and a product is identified by code within a catalogue.

API key reaches	What to send	If you omit it
One catalogue	Nothing, it is inferred	Fine
More than one catalogue	`catalogue_id`	`400 catalogue_required`

A catalogue_id the key cannot reach returns 404 catalogue_not_found, never a cross tenant read.
The same code can exist in two catalogues you own, and those are two separate products.

Modes

`mode`	What happens	Listing history
`draft` (default)	Creates the marketplace draft and stops. You can review it in the seller portal.	`draft_submitted`
`qc`	Creates the draft and submits it for marketplace QC or publishing.	`submitted_to_qc`, later `qc_passed` or `failed_qc`

Use draft when you want a person to eyeball the listing in the seller portal before it goes to QC, and qc when you trust the enrichment and want it live with no further steps.

Duplicate protection

If the product already has a successful submission on this platform, Wherehouse matches the existing listing instead of creating a duplicate, and result comes back as existing_listing_matched or skipped. Set force: true to submit again anyway.

Requests

List a product that already exists in your catalogue, straight to QC:

{
  "catalogue_id": 6,
  "product": {
    "code": "APL-IPH-34"
  },
  "mode": "qc"
}

Create the product and list it in one call, on a specific seller account:

{
  "catalogue_id": 6,
  "create_product": true,
  "seller_id": "12345678",
  "mode": "qc",
  "product": {
    "code": "APL-IPH-34",
    "title": "iPhone 15 Pro 256GB Blue Titanium",
    "soh": 12,
    "retail_price": 24999,
    "cost_price": 19999,
    "barcode": "0195949038543",
    "brand": "Apple",
    "category": "Smartphone",
    "main_image": "https://cdn.example.com/apl-iph-34/main.jpg",
    "weight_g": 187,
    "length_cm": 14.67,
    "width_cm": 7.08,
    "height_cm": 0.83
  }
}

Override the title and description for this listing only, and pin the marketplace category:

{
  "catalogue_id": 6,
  "product": {
    "code": "APL-IPH-34",
    "title": "Apple iPhone 15 Pro 256GB Blue Titanium Dual SIM 5G",
    "description": "Marketplace friendly copy that stays out of your own catalogue."
  },
  "category_path": "Cellphones & Wearables/Cellphones/Smartphones",
  "attribute_level": "optional",
  "mode": "qc"
}

Skip the AI attribute fill by supplying the marketplace attributes yourself:

{
  "catalogue_id": 6,
  "product": {
    "code": "APL-IPH-34"
  },
  "category_path": "Cellphones & Wearables/Cellphones/Smartphones",
  "core_fields": [
    {
      "key": "brand",
      "value": "Apple"
    },
    {
      "key": "country_of_origin",
      "value": "China"
    }
  ],
  "filled_data": [
    {
      "key": "Attribute.operating_system",
      "value": "iOS"
    },
    {
      "key": "Attribute.screen_size",
      "value": "6.1"
    },
    {
      "key": "Attribute.storage_capacity",
      "value": "256GB"
    }
  ],
  "mode": "qc"
}

Send your HTTP requests with an

Authorization

header that contains the word Basic followed by a space and a base64-encoded string username:password

Example:

Authorization: Basic *****************

application/json

The marketplace accepted the submission. QC is asynchronous, so poll GET /product-listings for the outcome.

Bodyapplication/json

Example

{
    "success": true,
    "platform": "takealot",
    "product": {
        "id": 1776790,
        "code": "APL-IPH-34",
        "catalogue": 6
    },
    "created_product": false,
    "draft_id": "b7c1f2e4-9a54-4f2f-9f7e-6d4d5c8a1b20",
    "listing_id": null,
    "stage": "submit",
    "request_id": "b7c1f2e4-9a54-4f2f-9f7e-6d4d5c8a1b20",
    "result": "submitted_to_qc",
    "tokens": 4820
}

/product-listings/{platform}

Platforms

Picking the seller account

New product or existing product

Catalogue scoping

Modes

Duplicate protection

Requests

Request

Request Code Samples

Responses

/product-listings/{platform}

Platforms#

Picking the seller account#

New product or existing product#

Catalogue scoping#

Modes#

Duplicate protection#

Requests#

Request

Request Code Samples

Responses

Platforms

Picking the seller account

New product or existing product

Catalogue scoping

Modes

Duplicate protection

Requests