Multivendor: Product API

Vendors can manage their products by MPN with a simple HTTP API: get, add, update and delete products with an API key. The API works with the vendor's own products only.

API key

  1. The vendor opens My Account > My Vendor Account > Edit your vendor information, the Personal tab.
  2. Generate creates the API Key (or replaces the old one).

The administrator sees and can change the key in the Vendor tab of the customer. Requests with the key of a disabled vendor or a disabled customer account are rejected. See API keys.

Vendor profile, Personal tab with the API Key field
Vendor profile, Personal tab with the API Key field

Requests and responses

All requests go to the storefront index.php of your store. The key is sent in the query string as apikey; the data of POST requests is sent as form fields (multipart/form-data when you send images).

Operation Method Route
Get a product GET extension/ka_extensions/ka_multivendor/api/product&apikey=KEY&mpn=MPN
Add a product POST extension/ka_extensions/ka_multivendor/api/product/add&apikey=KEY
Update a product POST extension/ka_extensions/ka_multivendor/api/product/update&apikey=KEY
Delete a product POST extension/ka_extensions/ka_multivendor/api/product/delete&apikey=KEY

The full URL is https://www.example.com/index.php?route= + the route. Use HTTPS: the key is part of the URL.

Products are found by the MPN field, with an exact match, among the vendor's own products. Keep MPNs unique and always send mpn.

Every response is JSON. success is true or false; on errors message has the reason. The HTTP status is 200 also for errors, so check success.

message Reason
apikey is required No apikey in the URL.
apikey is not correct No vendor has this key.
vendor account is disabled The vendor profile is disabled (Vendor Status). A disabled customer account gives "apikey is not correct".
Invalid request type GET was used for add, update or delete, or POST for get.
MPN is empty Get, add, update or delete: no mpn or an empty one.
Product was not found Get or delete: no product of this vendor has this MPN.
Product already exists with the specified MPN ... Add: the MPN is already used by this vendor.
Product does not exist with the specified MPN Update: no product of this vendor has this MPN.
Missed product_description field Add or update without product_description.
Category is not allowed for vendors: ID Add or update: category_id is a category that is not open for vendors (Allow For Vendor on the category and its parent categories). The category the product already has is accepted.
The product limit reached Add: the vendor has reached the products limit.

Product fields

Field Meaning
mpn The product key. Required.
product_description[CODE][name], [description], [tag] Name, description (HTML) and tags for each language. CODE is the language code, for example en-gb. Required in add and update; send all languages each time.
price, special_price Price and the special price for the default customer group. An empty or missing special_price removes the special.
quantity, subtract, minimum Stock, stock subtraction (1 counts the stock, 0 means unlimited), minimum quantity.
status 1 enabled, 0 disabled. Products that are not approved stay disabled.
category_id The product category, one of the categories open for vendors. 0 removes the category.
manufacturer_id The manufacturer.
shipping, weight, weight_class_id, length, width, height, length_class_id Shipping data, as in the vendor product form.
product_attributes[LANGUAGE_ID][ATTRIBUTE_ID] Attribute texts. Note that the key is the numeric language ID here, not the code. A missing list removes the product attributes.
image The main image, as an uploaded file.
additional_images[] Additional images, as uploaded files. They replace the old additional images; their order is the upload order.

In an update, product fields that are not sent keep their values, except special_price and product_attributes (see above). Images and the category are kept when they are not sent.

Get a product

Command
curl "https://www.example.com/index.php?route=extension/ka_extensions/ka_multivendor/api/product&apikey=YOUR_API_KEY&mpn=TOMATO-01"

The response has product with the product record and its description in the store language, including vendor_approval (empty = draft, W = waiting for approval, A = approved).

Add a product

Command
curl -X POST "https://www.example.com/index.php?route=extension/ka_extensions/ka_multivendor/api/product/add&apikey=YOUR_API_KEY" \
  -F "mpn=TOMATO-01" \
  -F "product_description[en-gb][name]=Cherry tomatoes 500 g" \
  -F "product_description[en-gb][description]=<p>Fresh cherry tomatoes.</p>" \
  -F "price=3.50" -F "quantity=100" -F "subtract=1" -F "minimum=1" \
  -F "category_id=25" -F "status=1" \
  -F "image=@tomatoes.jpg" \
  -F "additional_images[]=@tomatoes-2.jpg"

A product added by the API is submitted for approval at once: the response has "approval": "W", and the product stays disabled until the administrator approves it. It does not become a draft. The products limit of the vendor applies.

Update a product

Command
curl -X POST "https://www.example.com/index.php?route=extension/ka_extensions/ka_multivendor/api/product/update&apikey=YOUR_API_KEY" \
  -F "mpn=TOMATO-01" \
  -F "product_description[en-gb][name]=Cherry tomatoes 500 g" \
  -F "product_description[en-gb][description]=<p>Fresh cherry tomatoes.</p>" \
  -F "price=3.20" -F "quantity=80"

An update works like Save in the vendor product form (see Saving and submitting for approval):

  • an approved product stays approved when only price, special price, quantity, stock subtraction, minimum, status, weight, dimensions or shipping change;
  • other changes send it back to Waiting for approval and disable it;
  • a waiting product stays waiting, a draft stays a draft.

The response has approval with the status after the update.

Delete a product

Command
curl -X POST "https://www.example.com/index.php?route=extension/ka_extensions/ka_multivendor/api/product/delete&apikey=YOUR_API_KEY" \
  -F "mpn=TOMATO-01"

The product is deleted completely, with its images list, reviews and SEO URL. This cannot be undone.

PHP example

PHP
<?php
$store  = 'https://www.example.com/index.php?route=';
$apikey = 'YOUR_API_KEY';

$ch = curl_init($store . 'extension/ka_extensions/ka_multivendor/api/product/update&apikey=' . urlencode($apikey));
curl_setopt_array($ch, [
    CURLOPT_POST           => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POSTFIELDS     => [
        'mpn'   => 'TOMATO-01',
        'price' => '3.20',
        'product_description[en-gb][name]'        => 'Cherry tomatoes 500 g',
        'product_description[en-gb][description]' => '<p>Fresh cherry tomatoes.</p>',
    ],
]);
$result = json_decode(curl_exec($ch), true);
curl_close($ch);

if (empty($result['success'])) {
    echo 'Error: ' . ($result['message'] ?? 'no response');
} else {
    echo 'Saved, approval status: ' . $result['approval'];
}

Other modules can add their own fields to the API; this page describes the fields of Multivendor itself.