In the following article, we will show in detail the recommended way to connect individual data streams within the API of connecting your company.
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 unchanged and final. Nevertheless, the connection can be tested first. Your account is in test mode only 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. The impact of not following the recommended practices can be limiting to the functioning of your company's API calls, with respect to the load on the MALL system. With this in mind, the platform operates MALL rate limiter, read more about it in the article here. Any SLA overruns caused by incorrect API implementation and rate limit overruns are borne by the partner.
Please note that the API MALL has the nature of a source of information at the moment of their need, it is not a database that would be used to store historized data. API calls of this nature may be restricted.
- Brands Guidelines
In the context of 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 webhook here.
In this article you will learn how to correctly establish individual methods and switch individual states within the API, we also recommend reading the article explaining in detail individual states, which the order may acquire and what they mean here.
Please also note that if you use MALL Delivery services, the process differs in picking the shipment and updating the status in later steps.
Important: Send any order status updates only in case of changes in 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 prepared by you 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. Call Get order detail for orders in status BLOCKED for booking goods. 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 an order whose status has changed OPEN or CANCELED.
4. Call Update order with confirmed = true for OPEN or CANCELED orders for which, according to the information from the webhook, the status has changed from BLOCKED to OPEN or CANCELED (this is the final state and it is no longer possible to reopen the order).
5. Call Get order detail on OPEN confirmed orders for importing 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 the address and the amount of cash on delivery is final at this point.
6. Call Update order orders from the state OPEN to SHIPPING for all orders for which you have begun the shipping process. If you have found that the order cannot be shipped, it is possible to change the order to the status at this point CANCELED.
7a. When using MALL Delivery, 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 a consignment to a transport company.
9a. When using MALL Delivery, call Update order to change order status from SHIPPING on SHIPPED (change of status to SHIPPED must always take place only after the consignment has been handed over to the transport company).
9b. If you do not use MALL Delivery, call Update order orders from SHIPPING on 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 based on the webhook notification of a change in the order GET order detail for orders in state DELIVERED / RETURNED / LOST, in order to tighten the final status of orders to your system.
10. If you are not using MALL DELIVERY, call Update order of SHIPPED on DELIVERED with the exact delivery date based on information from your carrier. If you have information from the carrier about the first attempt at delivery, it is also possible to add it, 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 on RETURNED.
SLA and customer experience: For both forms of connecting orders, it is desirable towards the customer, and it is also a final SLA, so that the sending of order statuses is based on the truth and is as up-to-date as possible. Improper implementation of sending status 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 a regular frequency, we recommend adjusting the frequency to the average number of orders. Only exceed the frequency once an hour for more than 100 orders per day. Use filter = basic when calling.
2. Based on List of unconfirmed orders call Get order detail for orders in status BLOCKED for booking goods. 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. Call Update order with confirmed = true for OPEN/CANCELED orders that have been registered by your system in the call.
4. Call Get order detail on OPEN confirmed orders for importing 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 the address and the amount of cash on delivery is final at this point.
5. Call Update order orders from the state OPEN to SHIPPING for all orders for which you have begun the shipping process. If you have found that the order cannot be shipped, it is possible to change the order to the status at this point CANCELED.
6a. When using MALL Delivery, 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: Before sending the order, we recommend checking the status of the order. In condition SHIPPING it is possible for the customer to cancel the order. Such an order will then be changed to the state by the system CANCELED. This change will also appear in the list Get list of unconfirmed orders and needs to be confirmed through step 3.
7. Delivery of the consignment to the transport company.
8a. When using MALL Delivery, call Update order to change order status from SHIPPING on SHIPPED (change of status to SHIPPED must always take place only after the consignment has been handed over to the transport company).
8b. If you do not use MALL Delivery, call Update order orders from SHIPPING on 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 calls when using MALL Delivery Get list of orders by status using a time filter for DELIVERED / RETURNED / LOST orders in order to tighten the final status of orders to your system.
9. If you do not use MALL Delivery, call Update order of SHIPPED on DELIVERED with the exact delivery date based on information from your carrier. If you have information from the carrier about the first attempt at delivery, it is also possible to add it, 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 on RETURNED.
Back validation of data: If there is a case where you need to get back order data, always call the individual orders whose data you need. If it is still necessary to call up the list of orders, use it time period filters and avoid calling the entire order history at once. Use self-billing for invoicing and billing purposes 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 study carefully 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 downloading offers from the web.
Products without variants create by calling Create new product, in case of an error with this call, we have prepared an article for you explaining the individual errors and a possible way to prevent these errors and correct them. You can find the article 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, you can use the sandbox account.
AT variant products use the method first Create new product to create the main product. Then into this product using the method Create a new variant add variations. 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
Use the appropriate UPDATE method when updating product data non-variant product or variants. Change the data only in case of their change or need for addition. Whenever you update a product, you must always send all the 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, so 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 to update availability described above. To change availability, use the bulk change product availability method through Batch updatede of product / variant availability. Please use this update option as much as possible, through a bulk update it is possible to update up to 1000 products / variants at once.
Back validation of data: 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 regular bulk or individual calls for product data is 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 all products from draft to live.
Deactivation and deletion of products
There are several methods you can use to download a product from the Web, depending on the reason you need to download the product.
- Temporary sale of a product that will be re-stocked - in this case, as part of the product availability update, it is sufficient to reduce the stock availability of the product to "0", it will not be possible to purchase it on the website, and customers will still be able to monitor whether the product reappears in the offer for some time.
- Temporary need to download the product from the web - again, by updating the product availability, it is possible to use the status field, where setting 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 product whose variant through the appropriate endpoint. MALL keeps historical sales data of your products, if you then upload the product under the same ID, the sales data will be paired again.
Important: Do not update any product that is inactive. Retransmitting an update for inactive products is highly undesirable and burdensome for the platform. Exceeding the limit can lead to system congestion, only partial acceptance of data, which can result in both a negative customer experience and a potential loss on the part of the partner.
Within our API, use two basic endpoints to retrieve category data. In the first one Category tree by country you get a category tree available for that country. By changing the country code in the call URL, you can then obtain information about other country category trees using the same API key.
The result of the API call is always some data essential for your integration.
- menu item ID (= "MenuItemId") - a unique category code that you can use by calling 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 include products in the given menuitemID, for details on the conditions of the categories, please read the detailed article here.
Web Impression Validation: The product you uploaded to a 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 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.
Web Impression Validation: A product that you have uploaded to a system that does not meet the Category Conditions may show a display error 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 parameters, it is always necessary to use the list of values, which you will find here, it is not possible to enter your own values in the parameters. Always add the parameter name to the product in the technical names, fields Value. Always enter the values in the name of the target country of sale, ie the values from the field "text". For numeric values, always use the unit listed in the field Unit. If the parameter does not contain the values you need, send the request to email@example.com.
Using a 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 100% matching, including capital letters.
For adding a tag use the relevant tab in the partner portal as instructed here.
Using a call Get all labels you will always 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