/product-listings

Every listing submission made for the catalogues your API key can reach, newest first. This is the API version of the Listing History view.

Filters

All filters are optional and combine with AND. Filters that resolve to nothing (an unknown product_code or batch_uid) return an empty list with total: 0 rather than an error.

Scoping and safety

Results are always scoped to the catalogues your API key can reach. Any catalogue, product or id filter you send is ignored.

Reading the results

Wherehouse writes one row per product, per platform, per attempt, so a SKU submitted three times has three rows. For a current state view add most_recent_only=true.

result values:

Value	Meaning
`draft_submitted`	Draft created on the marketplace, not yet sent for QC.
`submitted_to_qc`	Sent to marketplace QC, waiting for a verdict.
`qc_passed`	QC passed. The listing is live or going live.
`published`	Published directly by the marketplace.
`failed_qc`	The marketplace rejected the listing. `error` says why.
`failed`	Wherehouse could not submit. `error` says why.
`skipped`	Wherehouse chose not to submit, for example an image mismatch.
`existing_listing_matched`	The product was already on the marketplace and was linked instead of duplicated.

platform_order_gmv and platform_order_sales_count attribute sales on that marketplace back to the submission, so you can tell which listings actually earned. Both are 0 until orders come in.

Sorting

Only three sort columns are supported: created_at, platform_order_gmv and platform_order_sales_count, each with :asc or :desc. Anything else falls back to created_at:desc.

Examples

Everything that failed QC on Takealot this month:

GET /v1/product-listings?platform=takealot&result=failed_qc&submitted_from=2026-07-01

Current listing state per product and marketplace:

GET /v1/product-listings?most_recent_only=true&_limit=100

Best earning listings first:

GET /v1/product-listings?_sort=platform_order_gmv:desc&result=success

Everything for one SKU, oldest first, as an audit trail:

GET /v1/product-listings?product_code=APL-IPH-34&_sort=created_at:asc

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

Request Code Samples

Shell

JavaScript

Java

Swift

PHP

Python

HTTP

Objective-C

Ruby

OCaml

Dart

Responses

🟢200Success

application/json

Listing submissions matching the filters.

Bodyapplication/json

Example

{
    "meta": {
        "total": 3,
        "limit": 25,
        "start": 0
    },
    "product_listings": [
        {
            "batch": {
                "uid": "9f1c7a52-63d4-4a19-8d0e-2f7b5c8e41aa"
            },
            "created_at": "2026-07-28T10:41:12.004Z",
            "error": null,
            "id": 774120,
            "listing_brand": "Apple",
            "listing_id": "PLID99887766",
            "listing_request_id": "b7c1f2e4-9a54-4f2f-9f7e-6d4d5c8a1b20",
            "listing_vertical": "Smartphones",
            "platform": {
                "id": 1,
                "uid": "takealot",
                "name": "Takealot"
            },
            "platform_order_gmv": 46998,
            "platform_order_sales_count": 2,
            "product": {
                "id": 1776790,
                "code": "APL-IPH-34",
                "title": "iPhone 15 Pro 256GB Blue Titanium",
                "catalogue": 6
            },
            "result": "qc_passed",
            "updated_at": "2026-07-28T13:02:44.881Z"
        },
        {
            "created_at": "2026-07-27T08:15:33.219Z",
            "error": "Takealot rejected the listing because the main image has a white background requirement. Replace the image and submit again.",
            "id": 774098,
            "listing_brand": "Apple",
            "listing_id": null,
            "listing_request_id": "2c8b1f77-4d31-4d5a-9d55-1f2a0b6c7e33",
            "listing_vertical": "Smartphones",
            "platform": {
                "id": 1,
                "uid": "takealot",
                "name": "Takealot"
            },
            "platform_order_gmv": 0,
            "platform_order_sales_count": 0,
            "product": {
                "id": 1776790,
                "code": "APL-IPH-34",
                "title": "iPhone 15 Pro 256GB Blue Titanium",
                "catalogue": 6
            },
            "result": "failed_qc",
            "updated_at": "2026-07-27T11:47:02.556Z"
        },
        {
            "created_at": "2026-07-26T14:03:51.771Z",
            "error": null,
            "id": 774031,
            "listing_brand": "Apple",
            "listing_id": "MAK-0099123",
            "listing_request_id": "a1d4e9b2-77c6-4b0f-b3aa-58e0c1d9f204",
            "listing_vertical": "Cellphones",
            "platform": {
                "id": 4,
                "uid": "makro",
                "name": "Makro"
            },
            "platform_order_gmv": 0,
            "platform_order_sales_count": 0,
            "product": {
                "id": 1776775,
                "code": "APL-IPH-33",
                "title": "iPhone 13 Pro Max",
                "catalogue": 6
            },
            "result": "existing_listing_matched",
            "updated_at": "2026-07-26T14:03:51.771Z"
        }
    ]
}

🟠400Invalid platform

🟠401Unauthorized

🟠405Not allowed

🟠429Rate limited

Filters#

Scoping and safety#

Reading the results#

Sorting#

Examples#