Important
Vendors are available only in Multi-Vendor.
Multi-Vendor allows you to run an online shopping mall, where multiple independent vendors can sell their products.
To get a list of vendors, send a GET request to /api/vendors/
:
GET /api/vendors/
This request returns the list vendors with their details.
Note
The number of the returned vendors depends on Multi-Vendor settings and can be altered by adding pagination parameters to the URL.
Add these parameters to the path to specify what vendors will be returned in the response and how they will be organized:
Parameter | Default value | Description |
---|---|---|
page | 1 | The response to GET /api/vendors is a page with a limited number of vendors. This parameter determines the number of the page that will be sent in the response. |
items_per_page | 10 | Determines the number of vendors on a page. |
sort_by | name |
Determines the parameter by which the vendors are sorted in the response. Available parameters are name , timestamp , email , status . |
sort_order | desc |
Determines the sorting order:
asc —ascendingdesc —descending |
Searches only for the vendors with the specified email address. | ||
timestamp | Searches only for the vendors created at the specified time. | |
status | Searches only for the vendors with the specified status.
N —newA —activeP —pendingD —disabled |
|
company | Searches only for the vendor with the specified name. |
Examples:
GET /api/vendors/?page=2&items_per_page=2
Response is an array with the information about 2 vendors from the 2nd page of the list of vendors.
GET /api/vendors/?email=vendor@example.com
Response is an array the information about the vendor with the specified email.
Let’s make a test request:
GET /api/vendors/
If the request is successful, you’ll receive HTTP/1.1 200 OK. The response is JSON with the following data:
{
"vendors": [
{
"company_id": "2",
"lang_code": "en",
"email": "[email protected]",
"company": "ACME Corp",
"timestamp": "1269610461",
"status": "A",
"seo_name": "acme-corp",
"seo_path": "",
"average_rating": null,
"company_thread_ids": "2_0"
},
{
"company_id": "1",
"lang_code": "en",
"email": "[email protected]",
"company": "Simtech",
"timestamp": "1269610461",
"status": "A",
"seo_name": "simtech",
"seo_path": "",
"average_rating": null,
"company_thread_ids": "1_0"
}
],
"params": [0]
}
To get the details of a specific vendor, send a GET request to /api/vendors/<company_id>/
. For example:
GET /api/vendors/1
The vendor exists: HTTP/1.1 200 OK and JSON with the vendor details:
{
"company_id": "1",
"lang_code": "en",
"email": "[email protected]",
"company": "Simtech",
"timestamp": "1269610461",
"status": "A",
"seo_name": "simtech",
"seo_path": "",
"average_rating": null,
"company_thread_ids": "1_0"
}
The vendor doesn’t exist: HTTP/1.1 404 Not Found.
The fields below represent various vendor details.
Note
The CS-Cart/Multi-Vendor REST API always accepts and returns data as strings and arrays/objects. The Values column in the table merely shows what kind of data you can expect in the fields.
Field | Values | Description |
---|---|---|
company_id | integer | A unique identifier of the vendor. |
lang_code | string | The language code, for example, en . |
string | The email address of the vendor. | |
company | string | The name of the vendor. |
timestamp | integer | The UNIX time when the vendor was created. |
status | string | |
seo_name | string | The SEO name of the vendor’s microstore.
Note: This field is added by the SEO add-on.
|
average_rating | float | |
company_thread_ids | string | The thread ID to which the reviews about the vendor are linked. It appears as
<company_id>_<thread_id> , for example 2_27.Note: This field is added by the Comments and Reviews add-on. The add-on creates this field via the hook every time the
fn_get_companies function is executed. The add-on also adds grouping by this field. |
Send a POST request to /api/vendors/
:
POST /api/vendors/
Pass the following fields with vendor details in the HTTP request body in accordance with the Content-Type
. Required fields are marked with *.
Note
Some of the fields below are not returned by GET requests, but can be used in POST or PUT requests nonetheless.
company*—the name of the vendor.
storefront*—this field is required by REST API, but it doesn’t serve any purpose in Multi-Vendor. Pass any value here, for example, api
:
{
...
"storefront": "api",
...
}
Important
The storefront field must have a unique value for each vendor you create via REST API.
company_description—the description of the vendor. You can use HTML code here.
status—the status of the vendor:
N
—newA
—active (the default status)P
—pendingD
—disabledlang_code—a two-letter language code, for example, en
.
email*—vendor’s email address.
phone*—vendor’s phone number
url—vendor’s website.
fax—vendor’s fax number.
address*—vendor’s address.
city*—vendor’s city.
country*—vendor’s country. Must be specified as the code (for example, US
).
Hint
You can find those codes under Administration → Shipping & taxes → Countries.
state*—vendor’s state. Can be specified as a code.
Hint
You can find those codes under Administration → Shipping & taxes → States.
zipcode*—vendor’s zip code.
pre_moderation—if you set it to Y
, any new products from the vendor will require approval by the store administrator.
pre_moderation_edit—if you set it to Y
, any updates of product information by the vendor will require approval by the store administrator.
pre_moderation_edit_vendors—if you set it to Y
, any updates of the vendor’s profile will require prior approval by the store administrator.
Note
The pre_moderation fields will apply only if you configure the Vendor Data Premoderation add-on accordingly.
categories—the list of categories where the vendor is allowed to create products, separated by commas. If you leave it empty or don’t specify this parameter, the vendor will be able to create products in any category.
shippings—the shipping methods available to the vendor. For example, if you want to allow the vendor to use shipping methods with shipping IDs 3 and 4, this is how the object will look like:
{
...
"shippings": {
"1": "3",
"2": "4"
},
...
}
Important
This object includes only the shipping methods created by the store administrator, not by a vendor’s administrator.
commission—the size of the commission taken from vendor on every sale. It uses xx.xx format.
commission_type—the type of the commission taken from the vendor:
A
—the commission is a certain amount specified in the store’s primary currency.P
—the commission is a percentage taken from the vendor’s sales.Note
Starting with Multi-Vendor 4.3.6, commission and commission_type are part of the Vendor Commission add-on.
terms—the text of vendor’s terms and conditions. You can use HTML code here.
Note
This field is added by the Vendor’s Terms and Conditions add-on.
{
"company": "New Vendor",
"company_description": "<p>This is the description of the new vendor.</p>",
"storefront": "example.com",
"status": "N",
"lang_code": "en",
"email": "[email protected]",
"phone": "555555555",
"url": "http://example.com",
"fax": "+555555555",
"address": "Boston street",
"city": "Boston",
"state": "MA",
"country": "US",
"zipcode": "02125",
"pre_moderation": "Y",
"pre_moderation_edit": "Y",
"pre_moderation_edit_vendors": "N",
"categories": "253,252",
"shippings": {
"1": "1",
"2": "3"
},
"commission": "10.55",
"commission_type": "A",
"terms": "<p>These are the terms and conditions you must accept before you can buy products from New Vendor.</p>"
}
The vendor has been created successfully: HTTP/1.1 201 Created and the ID of the vendor:
{
"store_id": 2
}
The vendor couldn’t be created: HTTP/1.1 400 Bad Request.
To update an existing vendor, send the PUT request to /api/vendors/<company_id>/
. For example:
PUT /api/vendors/2/
Pass the fields with the vendor details in the HTTP request body in accordance with the passed Content-Type
. None of the fields are required.
{
"company": "Example",
"email": "[email protected]",
"shippings": {
"1": "1"
},
"commission": "0",
"commission_type": "A"
}
This request:
shipping_id=1
available to the vendor.The vendor has been updated successfully: HTTP/1.1 200 OK
and the company ID:
{
"store_id": "2"
}
The vendor couldn’t be updated: HTTP/1.1 400 Bad Request.
The vendor doesn’t exist: HTTP/1.1 404 Not Found.
To delete a vendor, send the DELETE request to /api/vendors/<company_id>/
. For example:
DELETE /api/vendors/2
This request will delete a vendor with company_id=2
.
Questions & Feedback
Have any questions that weren't answered here? Need help with solving a problem in your online store? Want to report a bug in our software? Find out how to contact us.