/products

Create a product in one of the catalogues your API key can reach.

code is your SKU and is the identity of the product. It is unique per catalogue and cannot be changed afterwards.

Required fields

Field	Rule
`code`	Required. Unique within the catalogue.
`title`	Required.
`soh`	Required. Send `0` when there is no stock yet.
`retail_price` or `cost_price`	At least one is required.

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.

Product already exists

Posting a code that already exists in the target catalogue returns 409 product_already_exists and changes nothing. This endpoint never silently overwrites. To change an existing product use PUT /products/{code}, and to add the same SKU to a second catalogue post it again with the other catalogue_id.

Notes

id, catalogue, created_at and updated_at are ignored if you send them.

Unknown fields are ignored rather than rejected, so a typo in a field name is silently dropped. Read the response back to confirm what was stored.

The response is the full product, including inventory and the platforms marketplace cache, which is null for a product that has not been listed yet.

Minimal request

{
  "code": "APL-IPH-34",
  "title": "iPhone 15 Pro 256GB Blue Titanium",
  "soh": 12,
  "retail_price": 24999
}

Variant request

Variants of one product share a parent_code, and each variant is its own product with its own code.

{
  "catalogue_id": 6,
  "code": "APL-IPH-34-512",
  "title": "iPhone 15 Pro 512GB Blue Titanium",
  "soh": 4,
  "retail_price": 28999,
  "cost_price": 23499,
  "type": "variant",
  "parent_code": "APL-IPH-15PRO",
  "parent_title": "iPhone 15 Pro",
  "variant_option_1_name": "Colour",
  "variant_option_1_value": "Blue Titanium",
  "variant_option_2_name": "Storage",
  "variant_option_2_value": "512GB"
}

Request

Authorization

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

Query Params

Body Params application/jsonRequired

Example

{
    "catalogue_id": 6,
    "code": "APL-IPH-34",
    "title": "iPhone 15 Pro 256GB Blue Titanium",
    "soh": 12,
    "retail_price": 24999,
    "cost_price": 19999,
    "wholesale_price": 22499,
    "currency_code": "ZAR",
    "barcode": "0195949038543",
    "brand": "Apple",
    "category": "Smartphone",
    "type": "variant",
    "description": "6.1-inch Super Retina XDR display with ProMotion. A17 Pro chip. 48MP main camera with 5x telephoto. Titanium design.",
    "rich_description": "<p><strong>iPhone 15 Pro</strong> in Blue Titanium.</p><ul><li>A17 Pro chip</li><li>48MP main camera</li></ul>",
    "excerpt": "Titanium iPhone 15 Pro with the A17 Pro chip and a 48MP camera.",
    "main_image": "https://cdn.example.com/apl-iph-34/main.jpg",
    "images": [
        {
            "src": "https://cdn.example.com/apl-iph-34/front.jpg"
        },
        {
            "src": "https://cdn.example.com/apl-iph-34/back.jpg"
        }
    ],
    "colour": "Blue Titanium",
    "size": "256GB",
    "material": "Titanium",
    "model_number": "A3101",
    "package_contents": "iPhone 15 Pro, USB-C cable, documentation",
    "length_cm": 14.67,
    "width_cm": 7.08,
    "height_cm": 0.83,
    "weight_g": 187,
    "parent_code": "APL-IPH-15PRO",
    "parent_title": "iPhone 15 Pro",
    "variant_option_1_name": "Colour",
    "variant_option_1_value": "Blue Titanium",
    "variant_option_2_name": "Storage",
    "variant_option_2_value": "256GB",
    "tags": "smartphone,apple,5g",
    "archived": false,
    "draft": false
}

Request Code Samples

Shell

JavaScript

Java

Swift

PHP

Python

HTTP

Objective-C

Ruby

OCaml

Dart

Responses

🟢200Created

application/json

The product as stored. Keys are returned alphabetically.

Bodyapplication/json

Example

{
    "archived": false,
    "average_rating": null,
    "barcode": "0195949038543",
    "brand": "Apple",
    "catalogue": {
        "created_at": "2021-11-03T07:56:42.668Z",
        "id": 6,
        "name": "Apple Devices",
        "order_count": 10000,
        "product_count": 34,
        "uid": "demo-catalogue",
        "updated_at": "2025-02-20T11:04:42.308Z"
    },
    "category": "Smartphone",
    "code": "APL-IPH-34",
    "colour": "Blue Titanium",
    "cost_price": 19999,
    "created_at": "2026-07-28T09:12:04.118Z",
    "currency_code": "ZAR",
    "custom_attributes": null,
    "description": "6.1-inch Super Retina XDR display with ProMotion. A17 Pro chip. 48MP main camera with 5x telephoto. Titanium design.",
    "draft": false,
    "excerpt": "Titanium iPhone 15 Pro with the A17 Pro chip and a 48MP camera.",
    "fee_estimates": null,
    "height_cm": 0.83,
    "id": 1776790,
    "images": [
        {
            "src": "https://cdn.example.com/apl-iph-34/front.jpg"
        },
        {
            "src": "https://cdn.example.com/apl-iph-34/back.jpg"
        }
    ],
    "is_composite": false,
    "length_cm": 14.67,
    "main_image": "https://cdn.example.com/apl-iph-34/main.jpg",
    "material": "Titanium",
    "model_number": "A3101",
    "package_contents": "iPhone 15 Pro, USB-C cable, documentation",
    "parent_code": "APL-IPH-15PRO",
    "parent_title": "iPhone 15 Pro",
    "platforms": null,
    "retail_price": 24999,
    "rich_description": "<p><strong>iPhone 15 Pro</strong> in Blue Titanium.</p><ul><li>A17 Pro chip</li><li>48MP main camera</li></ul>",
    "sale_price": null,
    "size": "256GB",
    "soh": 12,
    "tags": "smartphone,apple,5g",
    "title": "iPhone 15 Pro 256GB Blue Titanium",
    "total_reviews": null,
    "total_sales_count": null,
    "total_sales_count_30_days": null,
    "total_sales_value": null,
    "total_sales_value_30_days": null,
    "type": "variant",
    "updated_at": "2026-07-28T09:12:04.118Z",
    "variant_option_1_name": "Colour",
    "variant_option_1_value": "Blue Titanium",
    "variant_option_2_name": "Storage",
    "variant_option_2_value": "256GB",
    "variant_option_3_name": null,
    "variant_option_3_value": null,
    "weight_g": 187,
    "wholesale_price": 22499,
    "width_cm": 7.08,
    "inventory": {
        "our_warehouse": 12,
        "takealot_jhb_dc": null,
        "takealot_cpt_dc": null,
        "takealot_dbn_dc": null,
        "amazon_dc": null
    }
}

🟠400Validation error

🟠401Unauthorized

🟠404Catalogue not found

🟠405Not allowed

🟠409Product already exists

🟠429Rate limited

Required fields#

Catalogue scoping#

Product already exists#

Notes#

Minimal request#

Variant request#