API overview

MerchantPro allows you to integrate your store with various third-party solutions through a REST API. Develop your online business by integrating with various third-party solutions such as marketplaces, ERP systems, WMS, invoicing or accounting software and many others.

Add an API User

1. Login to the MerchantPro dashboard.
2. Navigate to the API Users tab from the Settings -> API and webhooks page.
3. Click on the Add API user button.
4. Fill in the required internal name to something descriptive for your API User.
5. Choose the permissions.
6. Click on the Save button.

After saving, two important values will be generated:

• API User is the public key used to identify your application.
• API Secret is the private credential that must be kept secure and used for authenticating your API requests.

These credentials must be used for making API requests to MerchantPro, ensuring proper authentication and authorization. Ensure that your API Secret remains confidential and is not shared publicly.

Convention

API endpoints are described with an HTTP method and a path.

GET /api/v2/products HTTP/1.1

Prefix the path with the URL of your domain (including the https protocol) to get the final URL. For example, if your domain is example.com, then the final URL of the endpoint will be: https://www.example.com/api/v2/products Brackets, {}, in URLs indicate a value that must be replaced:

GET /api/v2/products/{id} HTTP/1.1

All JSON properties of the API, URLs and URL parameters are case sensitive.

Version

The MerchantPro API uses a versioning system to accommodate upgrades ensuring compatibility with current versions. The current, publicly available version is v2, as indicated by the path prefix /api/v2/.

Login

In order to access the MerchantPro API, you can authenticate using your API User and API Secret in two ways: by sending the information in Basic Auth or in HTTP headers.

Authentication using Basic Auth

In this method, the combination of API User and API Secret is encoded using Base64 and sent in the Authorization header of the HTTP request.

1. Concatenate the API User and API Secret separated by a colon :.
2. Encode the result in Base64.
3. Add the encoded result to the Authorization header with the prefix Basic.

Authorization: Basic {base64-encoded-string}

Authentication using HTTP Headers

In this method, the API User and API Secret are combined and sent in a single HTTP request header called x-api-key. The value of the header is the MD5 hash of the concatenated API User and API Secret.

API_USERNAME="your-api-username"
API_SECRET="your-api-secret"
X_API_KEY=$(echo -n "${API_USERNAME}${API_SECRET}" | md5sum | cut -d ' ' -f1)

curl -X GET "https://www.example.com/api/v2/products" \
	-H "x-api-key: $X_API_KEY"

info

Authentication with invalid credentials will return 401 Unauthorized, and repeted retries will return 403 Forbidden.

Send data

Accessing the API is done on the domain of your store, based on HTTPS. All data sent is in JSON format. It is necessary to send the header Accept: application/json to confirm that your application expects 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.

Response data

The API responds with content in JSON format, represented by strings, numbers, objects, arrays, boolean or null values. The MerchantPro API will return HTTP codes 200 and 300 in case of successful responses, and in case of errors it will return HTTP codes 400 and 500. In general, the API response can contain the following:

• Error (accompanied by error code and message)
• Data in individual resource format
• Data in collection format (resource list)

Individual Resources

When accessing an individual resource, an extended set of data will be returned (all attributes specific to that resource). Additionally, any secondary resources belonging to this resource will be included in the list (e.g., variations of a product or all images of the product).

Collection Format (List of Resources)

When accessing a list of resources, a summary set of each individual resource will be returned. In most cases, the list contains sufficient information to be used within another application without requiring an individual call to each resource.

HTTP Verbs

Here is a summary of the HTTP verbs you can use and the purpose of each

Verb	Description	Example
GET	Data retrieval	GET /products or GET /products/123
POST	Creating new resource	POST /products
PATCH	Apply partial modifications to a resource	PATCH /products/123
DELETE	Remove a resource	DELETE /products/123

Filtering Parameters

Certain endpoints, especially those that return collections, allow you to use specific parameters to filter the search results.

Filtering types

String filter

The string filter object allows searching a string field in different ways. Here is a list of possible types:

// Field matches provided value
"abc"

// Field matches provided list of values
{"in": ["abc", "def"]}

// Field is not equal with provided value
{"neq": "abc"}

// Field starts with value
{"starts_with": "abc"}

// Field contains word
{"match_words": "abc"}

// Field is empty (null or empty string)
{"isempty": true}

// Field is not empty
{"isempty": false}

// Field is null
{"isnull": true}

// Field is not null
{"isnull": false}

Bool filter

Boolean type (1 / 0 or true / false)

Date filter

A Date Filter Object is an object used in API requests to apply constraints on date-based fields. It allows clients to filter resources by specifying one or more date conditions, such as equality, range, or comparison operators. Here is a list of possible types:

// Field matches provided value
2024-09-27

// Field is greater than provided value
{"gt": 2024-09-27}

// Field is greater than or equal with provided value
{"gte": 2024-09-27}

// Field is less than provided value
{"lt": 2024-09-27}

// Field is less than or equal with provided value
{"lte": 2024-09-27}

Numeric filter

The numeric filter object allows searching a numeric field in different ways. Here is a list of possible types:

// Field matches provided value
123

// Field matches provided list of values
{"in": [123, 456]}

// Field is not matching provided list of values
{"notin": [123, 456]}

// Field is greater than provided value
{"gt": 100}

// Field is greater than or equal with provided value
{"gte": 100}

// Field is less than provided value
{"lt": 100}

// Field is less than or equal with provided value
{"lte": 100}

Meta filter

The meta filter object allows searching a meta field for multiple values. Here is a list of possible types:

// Search meta_fields
{
	"field_abc": "ABC",
	"field_qwe": {"isempty": true},
}

Metadata

Information about the total number of resources that meet the filtering criteria is provided in the metadata, along with 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"
	}
}

Pagination

Pagination for certain collection resources occurs automatically. By default, most endpoints return 20 records per page. You can modify the number of records per page using the limit parameter (e.g., limit=50), but in most cases, you cannot exceed 100 records per page. When the response exceeds the page limit, you can navigate through successive pages using the start parameter (e.g., start=20). The response includes 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"
	}
}

Stop navigating successive pages when the next attribute is null.

HTTP Status Codes

HTTP status codes returned by the API are important as they help you better interpret the response received. Below is a summary of these codes:

Code	Description
200	Request successful
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

Error responses are also in JSON format and have the following structure:

{
	"error": {
		"name": "unauthorized",
		"message": "Authentication required"
	}
}

The error code and its associated message are specific identifiers used by MerchantPro to represent errors.

Side Loading

For collections, it is possible to load additional data as part of the same request. For example, normally a request to /products will return data in a structure similar to the one below:

{
	"data": [
		{
			"id": 6,
			"name": "Smartwatch GARMIN Vivoactive",
			...
		},
		{
			"id": 7,
			"name": "Samsung Galaxy Smartwatch",
			...
		}
	]
}

To extract additional information that wouldn't normally be found in this response (such as description or variants), you would need to make another request to /products. Using side-loading, you can force the loading of additional data in the same request. For this, you append the include parameter with a comma-separated list of additional variables you want to append.

Examples:

https://www.example.com/api/v2/products?include=description,variants

https://www.example.com/api/v2/orders?include=line_items

The response will include the requested data in exactly the same structure as if they were requested through an individual resource request.

{
	"data": [
		{
			"id": 6,
			"name": "Smartwatch GARMIN Vivoactive",
			"description": "The Garmin Vivoactive is a versatile smartwatch offering GPS, fitness tracking, heart rate monitoring, and customizable sport modes.",
			"variants": [
				...
			],
			...
		},
		{
			"id": 7,
			"name": "Samsung Galaxy Smartwatch",
			"description": "The Samsung Galaxy Smartwatch combines style and functionality with fitness tracking, heart rate monitoring, GPS, and smart notifications.",
			"variants": [
				...
			],
			...
		}
	]
}

API Rate Limits

To maintain optimal API performance, MerchantPro enforces global limits on requests per minute and/or hour. The limits vary based on the subscription plan of your shop.

Total number of requests

• Per second: 4
• Per minute: 80
• Per hour: 3,600
• Per day: 60,000

These limits pertain to the total number of requests, and additional usage restrictions may be enforced if your API requests take too long to process.

Handling Exceeded Limits

When these limits are exceeded, requests will fail with HTTP status code 429 You have exceeded your request quota for this API. If a very high number of simultaneous requests are made, it is possible that access could be completely blocked.

Best Practices

• When performing GET requests, specify only the fields you need; this will reduce payload size and improves overall performance.
• Avoid excessive updates; only perform updates when necessary changes have occurred.
• Optimize your API calls to ensure you are not exceeding the rate limits.
• Monitor constantly your rate limits to ensure you stay within the allowed thresholds and avoid disruptions.

By following these guidelines, you can help ensure that your API usage remains within the allowed limits and your access remains uninterrupted.