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 for real sales, and that is production. The API key you get after registration is therefore unchangeable and final. Nevertheless, the connection can be tested first. Your account is in test mode until it is activated. The final display of your offer on the website will take place only after the approval of the onboarding department. For more information contact your onboarding specialist.
It is very important to follow the following recommendations. Not following the recommended steps may result in a limited functioning of your company's API calls, given the burden on the MALL system. With this in mind, the platform operates with a 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.
- Brands Guidelines
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 webhooks 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 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 to reserve the item. These are orders for which you have received the first notification. Take over only 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. You receive a webhook notification for orders that have been changed to status OPEN or CANCELED.
4. Please call Update order with confirmed = true for OPEN or CANCELLED orders that have been changed according to the webhook information. It is possible to change the status from BLOCKED to OPEN or CANCELLED (this is the final status and the order cannot be reopened).
5. Use the API call Get order detail for orders from the step 4., for CANCELED 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 CANCELED.
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, it is necessary to meet the conditions for dispatch specified 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 to 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 to SHIPPED, including tracking URL and carrier shipment number. All information must be sent in one callto meet the criteria of Quality of Service - Tracking rate.
Optional: When using MALL Delivery, you can call GET order detail for orders in DELIVERED/RETURNED/LOST status, in order to finalize the final order status in your system.
10. If you are not using MALL DELIVERY, use the API call Update order for orders changing from SHIPPED to DELIVERED with the exact delivery date based on the information from your carrier. If you have information from the carrier about the first attempt of delivery, it is also possible to add it 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 to 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. Call Update order with confirmed = true for OPEN/CANCELLED orders that have been registered by your system in the call.
4. Call Get order detail on OPEN confirmed orders to import final data into your system. At this point, it is no longer possible to intervene from any side in the order, so all information such as address and COD amount is 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 CANCELED.
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, it is necessary to meet the conditions for dispatch specified 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 to 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 to 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 the Get list of orders by status call using a time filter for DELIVERED/RETURNED/LOST orders to pull the final order status into your system.
9. If you do not use MALL Delivery, please call Update order from SHIPPED to DELIVERED with the exact delivery date based on information from your carrier. If you have information from your carrier about the first delivery attempt, this can also be added, this information is optional. Update must be sent in one call. If the order failed to be delivered and was returned to the shipper, change the order status from SHIPPED to 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 the entire order history at once. For billing and invoicing purposes when using the self-billing service, use the relevant endpoints.
For products, you need to focus on two types of calls, creating products and updating them.
Creating products and variants
At 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 given category. Sending variant products as individual records is undesirable and can lead to the removal of your products from the web.
Products without variants are created by the API call Create new product. In case of an error with this call, we have prepared an article explaining the individual errors and a possible way to prevent these errors and correct them. You can find the article 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, 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.
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.
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.
Backward data validation: In case you need to retrieve product data, call only when necessary and only through the appropriate endpoint for price or availability. Regular bulk or individual calls for product data are highly undesirable and burdensome to our system and may lead to limitations in your connection to MALL.
Within the MALL API, some actions can be performed in bulk. By using batch endpoints, you will significantly reduce the use 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 product and variant availability. This method allows you to update up to 1000 changes in a single call.
- Active selected products - Bulk change of selected products from draft to live.
- Activate products - Bulk 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 through the appropriate endpoint. MALL keeps the history data of sales of your products, so if you upload the product later 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.
Within our API you can use two basic endpoints to retrieve category data. In the first one Category tree by country you get a category tree available for a specific country. By changing the country code in the call URL, you can obtain information about other countries category trees using the same API key.
The result of the API call is always made of several pieces of data essential for your integration.
- menu item ID (="menuItemId") - a unique category code which you can use to call Category Detail to 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 into the given menuitemID. Please read the detailed article on details of category conditions 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 you get a list of data. The first part contains the display conditions in the given category.
- SAP ID (= "SapId") - the technical code of the category, this is the same code that was given in the previous call as Product Type ID, this is the technical code of the category needed to classify the product.
- Category Conditions (= "CategoryConditions") - here you will find the same data as in Menu Constraints in the previous call. To place a product in any category, you must always enter these conditions 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 parameter name 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 FAQ.
By using the call Get all brands you will 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 the "brand_id" field to the products in the exact form, including capital letters.
For adding a brand use the relevant tab in the partner portal as instructed here.
By using the call Get all labels you will get a complete list of labels in our database. Labels are used for marketing campaigns and other internal processes. These labels may be used without the prior approval of your MALL sales representative.
- FDEL - free shipping
- SALE - sale
- NEW - new