In the following article, we will show in detail the recommended way to connect individual data streams within your company's API connection.
Test environment: There is only one environment for testing and real sales, the production environment. The API key you get after registration is therefore immutable and final. Even so, the connection can be tested first. Your account is only in test mode until it is activated. However, the final display of your offer on the website will only take place after approval by the onboarding department, please contact your onboarding specialist for more information.
It is very important to follow the following recommendations. The impact of not following the recommended practices can be limiting to the operation of your company's API calls, given the burden on the MALL system. With this in mind, the platform operates MALL rate limiter. You can read more about it in the article here. Any SLA overruns caused by incorrect API implementation and rate limit overruns are the responsibility of the partner.
Please note that the API MALL is a source of current information and it is not a database that would be used to store historicized data. API calls of this nature may be restricted.
You use the client ID, or "API key", to authorize all API calls within the MALL connection. The API key has a combination of characters that are unique to each account and needs to be attached to each individual API call. If you have multiple accounts on MALL, the key will be unique for each account. The API key can be found in the MALL Partner Portal in the "Company Profile" section under the "Information" tab.
Content
Orders
When working with endpoints for orders, it is important to pay particular attention to the sequence of steps. This is divided into two basic options depending on whether you use webhook for obtaining information about changes in orders. You can read more about the webhook here.
In this article, you will learn how to properly bind each method and switch each state within the API, we also recommend reading the article explaining in detail the individual states that an order can take and what they mean from here.
Please note that if you use MALL Delivery services, the process differs in the later steps of shipping the order and updating the status.
Important: Only send order status updates in case of changes in the orders. Repeatedly sending the same information is highly undesirable and burdensome for the platform.
Sequence of order calls using webhook
First, you need to turn on the webhook and insert the URL you prepared into the appropriate tab in the partner portal in the Partner menu, then you can see the individual outgoing notifications in the log.
1. You receive a notification from the webbook with the order number that has changed.
2. Use the API call Get order detail for orders in status BLOCKED for booking goods. These are orders for which you have received the first notification. Please only receive information about the goods. Only receive financial information for orders in status OPEN. Reservation of goods is not mandatory, but it is highly recommended for goods with high saleability and the associated risk of selling out.
3. You receive a webhook notification for orders that have been changed to status OPEN or CANCELLED.
4. Use the API call Update order with confirmed = true for OPEN or CANCELLED orders that have been changed according to information from the webhook. Possible status change from BLOCKED to OPEN or CANCELLED (this is the final state and it is no longer possible to reopen the order).
5. Use the API call Get order detail for orders from the step 4., for CANCELLED orders cancel the reservation. For OPEN orders, use the call on confirmed orders to import the final data into your system. At this point, it is no longer possible to intervene from any side of the order, so all information such as address and COD amount is final at this point.
6. Use the API call Update order for orders changing from status OPEN to SHIPPING which are in the shipping process. If you have found that the order cannot be shipped, it is possible to change the order status to CANCELLED.
7a. When using MALL Delivery, use the API call Generate labels for selected MDP orders for printing labels for MALL Delivery orders.
7b. If you do not use MALL Delivery, you must meet the shipping requirements set by your carrier.
8. Delivery of the consignment to the delivery courier.
9a. When using MALL Delivery, use the API call Update order to change order status from SHIPPING for SHIPPED (change of status to SHIPPED must always take place after the package has been handed over to the delivery courier).
9b. If you do not use MALL Delivery, use the API call Update order for orders changing from SHIPPING for SHIPPED, including tracking URL and carrier shipment number. All information must be sent in one call to meet the criteria of Quality of Service - Tracking rate.
Optional: When using MALL Delivery, you can use a API call GET order detail based on the webhook notification of a change in the order for orders in status DELIVERED/RETURNED/LOST in order to finalize the final status of orders in your system.
10. If you are not using MALL DELIVERY, use the API call Update order for orders changing from SHIPPED for DELIVERED with an exact delivery date based on information from your carrier. If you have information from the carrier about the first delivery attempt, this can also be added, but this information is optional. The update must be sent in one call. If the order could not be delivered and was returned to the sender, change the status of the order from SHIPPED for RETURNED.
SLA and customer experience: It is important for both forms of connecting orders that the setting of order statuses is based on the actuality and is as up-to-date as possible. This is important for the satisfaction of the customer and it is also a final SLA. Incorrect implementation of status posting can lead to a negative customer experience and cancellation of orders.
Sequence of order calls without using a webhook
1. Call Get list of unconfirmed orders with regular frequency, we recommend to adjust the frequency to the average number of orders. Only exceed the frequency of 1x per hour if there are more than 100 orders per day. When calling, use filter=basic.
2. Based on the List of unconfirmed orders call Get order detail for orders in status BLOCKED to reserve the goods. Only take over the information about the goods. Only obtain financial information for orders in status OPEN. Reservation of goods is not mandatory, but it is highly recommended for goods with high saleability and the associated risk of selling out.
3. Use the API call Update order with confirmed = true or OPEN/CANCELLED orders that have been registered by your system in the call.
4. Use the API call Get order detail for OPEN confirmed orders to import the final data into your system. At this point, it is no longer possible to intervene in the order from any side, all information such as address and amount of cash on delivery are final at this point.
5. Use the API call Update order for orders changing from status OPEN to SHIPPING which are in the shipping process. If you have found that the order cannot be shipped, it is possible to change the order status to CANCELLED.
6a. When using MALL Delivery, use the API call Generate labels for selected MDP orders for printing labels for MALL Delivery orders.
6b. If you do not use MALL Delivery, you must meet the shipping requirements set by your carrier.
Recommendation: We recommend checking the status of your order before sending it. In SHIPPING status, the order can be cancelled by the customer. Such an order will then be changed by the system to the CANCELLED status. This change will then also appear in the list Get list of unconfirmed orders and needs to be confirmed via step 3.
7. Delivery of the consignment to the transport company.
8a. When using MALL Delivery, use the API call Update order to change order status from SHIPPING for SHIPPED (change of status to SHIPPED must always take place after the package has been handed over to the delivery courier).
8b. If you do not use MALL Delivery, use the API call Update order for orders changing from SHIPPING for SHIPPED, including tracking URL and carrier shipment number. All information must be sent in one call, to meet the criteria of quality of service - Tracking rate.
Optional: You can use the Get list of orders by status calls when using MALL Delivery. Use the time filter for DELIVERED/RETURNED/LOST orders in order to finalize the final status of orders in your system.
9. If you do not use MALL Delivery, use the API call Update order for orders changing from SHIPPED for DELIVERED with an exact delivery date based on information from your carrier. If you have information from the carrier about the first delivery attempt, this can also be added, but this information is optional. The update must be sent in one call. If the order could not be delivered and was returned to the sender, change the status of the order from SHIPPED for RETURNED.
Backward data validation: In case you need to retrieve order data, always call the individual orders whose data you need. If it is still necessary to call up the order list, use the time period filters and avoid calling up your entire order history at once. For billing and invoicing purposes when using MALL Self-Billing, use relevant endpoints.
Products
For products, you need to focus on two types of calls, creating products and updating them.
Creating products and variants
If you are using product creation please always pay attention to our product content conditions, details can be found here. Then carefully examine product display conditions in individual categories in the article here to prevent the need for subsequent product repairs through further calls.
Important: If your products have variants, always create variant products based on the parameters available in the category. Submitting variant products as individual listings is undesirable and may lead to the offer being pulled from the site.
Products without variants are created by the API call Create new product, If you get an error with this call, we have prepared an article explaining the individual errors and how to prevent and correct them. The article can be found under the link here. The call structure is mandatory except for the elements where it is explicitly stated in the documentation. The product created in this way can then be found in the list of products in the portal and also on the web in the product listing, where you can see it using your sandbox account.
For variant products, first use the Create new product to create the main product. Then add variants to that product using the Create new variant method. Variants need to be distinguished using variant parameters. You can use up to two of the parameters available in a given category. Variants assigned to the main product are then always displayed on the product detail with the corresponding parameter as an optional variable by the customer.
For products fill priority with 1. The system automatically ranks products using an algorithm that works on the basis of the number of clicks, traffic and sales of a given product.
This is an obsolete element that still needs to be filled in but is not taken into account at all. We are currently working on removing it.
For products it is important to indicate EAN (GTIN), has a precisely defined shape - 13 numeric characters. EAN has a major impact on the matching of products on Google Ads, Heureka and Zboží.cz and therefore the ability to reach many more customers with your products.
If your EAN has 14 numeric characters, enter it as 13 digits without the 0 at the beginning. If you have a shorter 8-digit EAN, add as many 0's to the beginning as there are missing 13 characters (5).
Product updates
For products, we divide the update into several types.
- Product data update (labels, images, parameters, ...)
- Price update
- Availability update
Important: Send any product updates only in the event of changes. Repeatedly sending the same information is highly undesirable and burdensome for the platform.
Product data update
When updating product data, use the appropriate UPDATE method invariant product or variant. Only change the data if it changes or if you need to add it. When making any product update, you should always send all elements, not just those that have changed.
Price update
To update the price, do not use the product or variant update method described above. To change the price, a separate call is available through which you can send the change, both for non-variant product, as for variants. When updating the price by more than 30%, the price change must be confirmed through a force token. See our documentation for more information on this feature here.
Availability update
Do not use the product or variant update method described above to update availability. To change availability, use the method to bulk change product availability via Batchupdate of product/variant availability. Please use this update option as much as possible, up to 1000 products/variants can be updated at a time via bulk update.
If changes to units are required, it is possible to use the method for updating stock availability of write it in the or variants.
Backward data validation: If there is a case where you need to get product data back, call them only when necessary and only through the appropriate endpoint for price or availability. Any periodic bulk or individual calls for product data is highly undesirable and burdensome to our system and may result in limiting your connection to MALL.
Batch endpoints
Within the MALL API, some actions can be performed by bulk changes. Using batch endpoints will significantly reduce the usage of your API call limit within the rate limiter, so it is recommended to use these as much as possible.
Available batch endpoints are:
- Batch availability update – As described above for the availability update, this is a bulk update of the availability of products and variants. This method allows you to update up to 1000 changes in one call.
- Active selected products – Mass change of selected products from draft to live.
- Activate products – Mass change of all products from draft to live.
Deactivation and deletion of products
There are several methods you can use to hide a product from the Web, depending on the reason you need to remove the product.
- The product is temporary sold out and will be re-stocked – in this case, as part of the product availability update, it is enough to reduce the stock availability of the product to "0", it will then not be possible to buy the product on the website, but the customers will still be able to monitor the product to see when it will be available again.
- Temporary need to remove the product from the web – again, by updating the product availability, it is possible to use the status field, where the setting of the value "N" makes the product or variant "inactive".
- Product deletion – if you know that the product or variant will not be in stock for more than 2 months, we recommend you delete the product or variant delete through the respective endpoint. MALL maintains historized sales data for your products, if you upload a product under the same ID, the sales data will be paired again.
Important: Do not update any product that is inactive. Repetedly sending updates for inactive products is highly undesirable and burdensome for the platform. When the limit is exceeded, the system can become overwhelmed with will only accept partial data, which can result in a negative customer experience as well as in a potential loss on the partner's end.
Category
Within our API, use two basic endpoints to retrieve category data. In the first one Category tree by country you will get the category tree available for the country. By changing the country code in the call URL, you can then get information about category trees for other countries using the same API key.
The result of the API call is always a few pieces of data that are essential for your integration.
- menu item ID (="menuItemId") - a unique category code that you can use to call Category Detail get a list of all parameters and values, the call is described below.
- Product Type ID (="productTypeId") - the technical category code needed to classify the product, this code can match across multiple menuitemIDs.
- Menu Constraints (="menuCosntraints") - Mandatory parameters with values needed to assign products to a given menuitemID, for details on category conditions please read the detailed article here.
Validation of the web display: The product you uploaded to the system that does not meet Menu Constraints, may show an error when displayed and will not be available to customers.
Through API calls Category detail then you will get a list of data. The first part contains the display conditions for the category.
- SAP ID (="sapId") - the technical category code, this is the same code that was given in the previous call as Product Type ID, this is the technical category code needed to classify the product.
- Category Conditions (="categoryConditions") - here you will find the same data as in Menu Constraints in the previous call. To classify a product in any category, these conditions must always be entered correctly.
Validation of the web display: A product you have uploaded to the system that does not meet the Category Conditions may show an error when displayed and will not be available to customers.
- Other parameters (="otherParameters"): Here you will find all other parameters with values that can be used and added to your products. For the parameters you should always use the list of values you find here, entering your own values into the parameters is not possible. Always add the name of the parameters to the product in the technical names, field "value". Always enter the values in the name of the target country of sale, i.e. the values from the field "text". For numeric values, always use the unit specified in the "unit". If the parameter does not contain the values you need, send us a request via Help Centre.
Brands
By using the call Get all brands you get a complete list of available brands across all countries. The list is not unique to each country, so you can use it to connect to any of the MALL Partner markets. Always add data from the "brand_id" field to products in a 100% match, including capital letters.
For adding a brand use the relevant tab in the partner portal as instructed here.
Labels
By using the call Get all labels you will always get a complete list of the labels in our database. The labels are used for marketing campaigns and other internal processes. The use of these labels is not allowed without prior approval from your sales representative at MALL.
- FDEL - free shipping
- SALE - sale
- NEW - new
English 
Čeština 
Slovenščina 
Magyar