Product API best practices
This document describes best practices for using the product-related APIs of LinkedMall API V2.0.
Overview
The LinkedMall API provides distributors with a series of product-related APIs and messages, allowing you to implement features such as product synchronization and queries by calling the APIs and consuming product messages.
This document outlines best practices for using these APIs to improve system stability and reliability. It clarifies correct usage through four typical use cases and highlights key considerations to prevent common errors.
When designing your system and calling APIs, you must consider the Queries Per Second (QPS) limits for each API. For more information, see LinkedMall API V2.0 QPS Limits.
Use cases
Use case 1: Product synchronization and write-back
Description
Product synchronization transfers product information from one system to another and writes back the results. This process is typically used for initial data setup or for periodic updates between systems.
Typical business scenarios
Scenario | Description | Related APIs | Related messages |
Initial full product sync (product initialization) | After a distributor completes onboarding and shop setup, the channel provider provisions products for them. After provisioning, the distributor can call the query distribution pool product list API to fetch all products page by page. Note
| None | |
Incremental product sync during normal operations (periodic updates) | After integrating with Kafka, promptly consume the product created message to retrieve new products. | None | |
Product information updates during normal operations (periodic updates) | After integrating with Kafka, consume various product messages in a timely manner to update product information and statuses. | None | Various product messages |
Paginated product query | If you build your own product management backend and need to query products by page, call the query distribution pool product list API to fetch product information for a specific page. | None |
Important considerations
Ensure that all parameters are complete and accurate when calling the API to avoid missing data due to parameter errors.
Consume all types of product messages promptly to receive incremental product updates and status changes.
Use case 2: Synchronizing products with the search API
Description
Use this method to dynamically fetch product data based on specific search criteria.
The LinkedMall distributor console provides features for product filtering, product removal, and product addition. You can also perform these actions in the console. For more information, see the Product Selection documentation.
If you build your own product management backend and need to integrate these features, refer to the scenarios described below.
The product removal and product addition features are currently available only to allowlisted distributors (onboarded on or after January 1, 2025). Distributors who are not allowlisted (onboarded before January 1, 2025) can ignore these features and the product removal/addition status fieldinGroup. For more information, contact a LinkedMall technical support engineer.
Typical business scenarios
Scenario | Description | Related APIs | Related messages |
Filter or search for specific products | The search distribution pool products API provides filtering and search capabilities consistent with the product management module in the distributor console. If you have a self-built product management backend, you can call this API to filter or search for products that meet the specified input criteria. Note For paginated product queries that do not involve filtering or searching by condition, use the query distribution pool product list API. | None | |
Perform product removal or addition after filtering or searching |
Note If you perform removal or addition operations in the LinkedMall distributor console, you must promptly consume the product removal message and product addition message to synchronize the status. |
Important considerations
The accuracy of search criteria is critical to the results. Ensure that your search parameters are appropriate and complete.
Currently, the product removal and addition features and their related messages are only available to allowlisted distributors (onboarded on or after January 1, 2025). See the table below.
Feature
Allowlisted distributors
Non-allowlisted distributors
Optimized product message delivery strategy
Follows the new strategy (see the next table)
All messages are sent and must be consumed
Product removal and product addition APIs
Must integrate with APIs or use the console
Operations have no effect
Product removal and product addition messages
Must be consumed promptly
Must be ignored
Product Stock Status: The
inGroupFieldMust be monitored or processed
Must be ignored
The LinkedMall system uses different message delivery strategies for added products versus removed products. See the table below for details.
ImportantThe product removal and product addition features are currently available only to certain allowlisted distributors (onboarded on or after January 1, 2025). For non-allowlisted distributors (onboarded before January 1, 2025), all product-related messages are sent, and you can ignore the table below. For more information, contact a LinkedMall technical support engineer.
Message
Sent for removed products?
Sent for added products?
Yes
Yes
Yes
Yes
No
Yes
Yes
Yes
Yes
Yes
Yes
Yes
No
Yes
Yes
Yes
Yes
Yes
Yes
Yes
No
Yes
Yes
Yes
Use case 3: Displaying products in the shopping cart
Description
When a customer adds a product to their shopping cart, you must display its information accordingly.
Typical business scenarios
Scenario | Description | Related APIs | Related messages |
Display product information in the shopping cart | When a customer views their shopping cart, you must display the availability of products in the cart. To do this, call the batch query SKU sales information in distribution pool API to check the sales information for all SKUs in the cart. Note
| None |
Important considerations
Ensure the SKU IDs in the shopping cart are correct to avoid fetching incorrect product information.
To check product availability for a specific region based on the customer's shipping address, include the
divisionCodefield when you call the API.
Use case 4: Product display in detail pages and discovery
Description
Product details pages and discovery experiences recommend products based on user needs. To do this, you must query product details and sales information.
Typical business scenarios
Scenario | Description | Related APIs | Related messages |
Query product status in discovery experiences | In discovery experiences, such as a homepage feed, you typically need to get product availability status before loading products. You can call the query product sales information in distribution pool API to retrieve this information. | None | |
Displaying the product details page |
| query product details in distribution pool | Various product messages |
Important considerations
In discovery experiences, the accuracy of recommendations depends on complete product details and sales information. Ensure your API call parameters are correct.
To check if a product is available in a specific region, you must include the
divisionCodeparameter in your API call.
Product APIs and messages
For more information, see the Product API reference and Product message reference.
Key product fields and structures
Field or structure | Description | Found in | Related APIs or messages |
| SKU and product specification value alias. When the | query product details in distribution pool | |
| SKU Title. We recommend that distributors retrieve the | query product details in distribution pool | |
skuAlias | SKU notes. Use this as a supplementary description for the SKU. You can display it after the concatenated SKU title. | query product details in distribution pool | |
Product purchase limit rules. | - | query product details in distribution pool query distribution pool product list | |
Extended product properties. Includes extended attributes such as product purchase multiplier, brand logo, and product recommendation title. | - | query product details in distribution pool |