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
- The vendor opens My Account > My Vendor Account > Edit your vendor information, the Personal tab.
- 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.
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
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
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
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
The product is deleted completely, with its images list, reviews and SEO URL. This cannot be undone.
PHP example
Other modules can add their own fields to the API; this page describes the fields of Multivendor itself.
