Introduction
The intent of this document is to provide a set of guidelines, from both a technical and a business perspective, to help Distributors get up and running with PromoStandards.
General Rollout Strategy
Most Distributors start with simpler API’s and work towards increased complexity on either the transaction side or the product data side - for example:
Transactional Path:
First: Inventory
Second: Order Status
Third: Order Ship Notify
Non-Transactional Path:
First: Media
Second: Product
These paths will give a good walkthrough of the easier API’s - they both ultimately wind up needing Price & Config before PO and then PO to actually submit PO’s. Price & Config is widely regarded as the most difficult of the API’s to integrate with.
Integration Considerations
Many of the topics below are not specifically about PromoStandards per se, but they are worth repeating here in a “PromoStandards Context” as they touch on challenges that have been encountered with PromoStandards integrations.
Call Velocity
It is important to not “over call” a supplier endpoint; an implementation that checks a suppliers order status API every minute for updates while the order is open will generally not provide a more meaningfully timely update than an hourly request and will create a lot of extra overhead on the endpoint and reduce the speed at which it performs for everyone using it. Many suppliers will also implement rate-limiting which will wind up rejecting API calls coming in “too frequently” (Suppliers who do this should document acceptable call frequency in their integration guides).
Product data refreshes are another area where call velocity becomes an issue - an integration might make a call to a Supplier’s Product API for getProductSellable followed by a series of getProduct calls for each product in getProductSellable. If the supplier has 1,000 products that the integration calls asynchronously (i.e. all at once), the result will often be either a) an incomplete set of product data because some of the calls fail or are rejected or b) a supplier’s server being overloaded. If the requests cannot be serialized (i.e. one at a time), then there should at least be a small delay added between each request (even a simple 1-2 second delay can make a big difference).
Retry Logic
In most cases, retry logic does not have to be very complicated - if the call fails, wait a couple seconds and retry. One notable exception would be retry logic on calls to the PO API - ideally, a Distributor integration would do the following:
Call the PO API to submit order
If the PO API call failed for a reason leaving it unclear as to whether it succeeded (i.e. request timed out), call the Order Status API with Query Type 1 to see if the PO submitted is reporting in the system
If the Order Status API says the PO is in the Supplier’s system, then no further action would be needed
If the Order Status API says the PO is not in the Supplier’s system, then the fail is probably a real fail and a resubmission should be OK
Caching Data Locally
Much of the non-transactional data requested via PromoStandards can be cached locally once received. Once it is saved locally, its much faster for everyone if a Distributor then references that local copy of the data instead of continually requesting it at runtime when it rarely changes.
Data | Domain | Normal Duration of Caching |
|---|---|---|
Inventory | Transactional | N/A |
Invoice | Transactional | N/A |
Order Status | Transactional | N/A |
Order Ship Notify | Transactional | N/A |
Purchase Order | Transactional | N/A |
Media | Non-Transactional | 1 Week |
Product | Non-Transactional | 1 Week |
Price & Config | Non-Transactional | 1 Week |
Audit Logs
From the outset, capturing queryable data around request and response is essential.
You will want to be able to report on the success/usage of your service. While number of transactions is only one part of the picture, being able to report on number of hits by service will be one part of your story of success. For order status, as an example, you can estimate cost savings based on number of order status requests with successful response. Every status retrieved electronically is a call that does not have to be made or an email that does not need to be sent.
You will be want to be able to troubleshoot issues and an audit log is essential for this. Capturing the entirety of your request in a dataset so that you can replicate it will be useful in troubleshooting errors.