MerchantPro API Overview
The MerchantPro API is a REST API. In order to use the API resources you need a VIP account, HTTPS certificate installed and you will need to activate your API key on the API Access page. See the sections below for more information on how to use it.
Collection format (resource list)
Convention
API endpoints require HTTP method and a path. Example:
GET /api/v2/products HTTP/1.1Prefix the path to your domain URL (including the https protocol) to get the final URL. For example if your domain is example.com the final URL of the endpoint will be:
https://www.example.com/api/v2/products
The curly brackets, {} , in URLs indicate a value that needs to be replaced:
GET /api/v2/products/{id} HTTP/1.1All JSON properties of the API, URLs, as well as parameters in the URL are case sensitive.
Version
The MerchantPro API uses a versioning system to accommodate upgrades and ensure compatibility with current variants.
The current publicly available version is v2, as indicated by the path prefix /api/v2/.
Login
In order to access the MerchantPro API you will need to log in using basic authentication based on the API Key and Api Secret. Authenticating an API request involves sending an authorization header. To log in you must follow the steps below:
- Combine API Key and Api Secret in the following form key:password
- Apply base64_encode to the resulting string, ex a2V5OnNlY3JldA==
- Include the basic HTTP authorization header
Authorization: Basic {base64-encoded-string}Authorization: Basic a2V5OnBhc3M=Invalid credential authentication will return 401 Unauthorized, and repeated attempts will return 403 Forbidden.
Sending data
Accessing the API is available on the domain of your store, based on HTTPS. All data is being sent in JSON format.
You need to send the header Accept: application/json to confirm that your application is expecting a response in JSON format from the API.
It is necessary to send POST or PUT requests accompanied by the header Content-Type: application/json and the sent content must be in valid JSON format.
Answer format
The API responds with content in JSON format, represented by strings, numbers, objects, arrays, Boolean values or nulls.
The MerchantPro API will return HTTP codes 200 and 300 for successful responses, and for errors will return HTTP codes 400 and 500.
In general the API response can contain the following:
- Error (accompanied by code and error message)
- Data in individual resource format
- Data in collection format (resource list)
Individual resources
When you access an individual resource, an extended set of data will be returned (all attributes specific to that resource). In addition, the secondary resources that belong to this resource will be included in a list (variants of a product or all images of the product).
Collection format (resource list)
When you access a resource list a summary set of each individual resource will be returned. In the vast majority of cases, the list contains enough information to use it in another application without the need for an individual call for each resource.
HTTP Methods
Here is a summary of the HTTP methods you can use and the purpose of each:
| Method | Purpose | Example |
|---|---|---|
| GET | Used for data extraction | GET / products or GET / products / 123 |
| POST | Used to create new resources | POST / products |
| PUT | Used to update existing resources with partial data | PUT / products / 123 |
| DELETE | Used to delete resources | DELETE / products / 123 |
Filter parameters
Certain endpoints, especially those of the collection type, allow specific parameters in order to filter search results.
Metadata
Information about the total number of resources that meet the filtering criteria is provided in the metadata, along with the necessary information about the existence of additional resources and their access URLs (where applicable).
"meta": {
"count": {
"total": 8219,
"current": 20,
"start": 0,
"limit": 20
},
"links": {
"prev": null,
"current": "/api/v2/products",
"next": "/api/v2/products?start=20&limit=20"
},
"has_more": true
}Pagination
The pagination of certain collection-type resource takes place automatically. By default, most endpoints return 20 records per page. You can change the number of entries per page using the limit parameter (ex limit=50), but you cannot exceed 100 entries per page in most cases.
When the answer exceeds the limit per page, you can navigate to successive pages using the start parameter (ex start=20)
The answer includes the next and previous attributes to facilitate navigation.
"meta": {
...
"links": {
"prev": "/api/v2/products",
"current": "/api/v2/products?start=20&limit=20",
"next": "/api/v2/products?start=40&limit=20"
}
}It stops successive pages navigation when the next attribute is null.
HTTP status codes
The HTTP status codes that the API returns are important and allow you to better interpret the response received. Below you will find a summary of them:
| Code | Meaning |
|---|---|
| 200 | Found and returned |
| 201 | Resource created |
| 204 | Resource deleted |
| 400 | Bad Request |
| 401 | Unauthorized |
| 403 | Forbidden |
| 404 | Resource not found |
| 405 | Method not allowed |
| 429 | Too many requests |
| 500 | Internal Server Error |
Error responses
The error responses are also in JSON format and have the following form:
{
"error": {
"name": "unauthorized",
"message": "Authentication required"
}
}The error code and related message are MerchantPro specific names for the error representation.
Side Loading
In case of collections, it is possible to upload additional data as part of the same request. For example, a request to /products will normally return the data in a structure similar to the one below:
{
"data": [
{
"id": 7,
"name": "Smartwatch GARMIN Vivoactive",
...
},
{
"id": 8,
"name": "Samsung Galaxy Smartwatch",
...
}
]
}In order to be able to extract certain additional information that would not normally be found in this response (such as images or product variants) it would be necessary to make another request to /products /7
Using side-loading, you can force the loading of additional data in the same request. For this you will need to append the parameter include with a list of additional variables (separated by comma) that you want to append.
Example:
... /products?include=variants ... /orders?include=products
The response will include the requested data in exactly the same structure in which it would be included if it were requested through a request to an individual resource.
{
"data": [
{
"id": 7,
"name": "Smartwatch GARMIN Vivoactive",
"variants": [
...
],
...
},
{
"id": 8,
"name": "Samsung Galaxy Smartwatch",
"variants": [
...
],
...
}
]
}Limits of an API Key
To maintain optimal API performance, MerchantPro imposes a number of global request limits per minute and/or hour. When these limits are exceeded, requests will begin to fail with an HTTP status code 429 You have exceeded your request quota for this API. You can increase the limit on requests by contacting us at support@merchantpro.bg .
