Best Practices
After you've successfully integrated with OrderDynamics OMS, there are several things you can do to have the best experience possible with our APIs.
We recommend:
Integration Requirements and Recommendations
API Integration Area to Consider
Customer Responsilibities
Design
Customers are responsible for the design, development, and testing of their side of the interfaces and should transform their data formats both to and from the Tecsys-provided interface formats.
Retry Mechanisms
Customers should implement incremental retry mechanisms on:
Connections.
Timeout exceptions.
Rate-limited exceptions.
The retry attempt limit is set to three attempts with a five-second delay. For more information on retry mechanisms, click here.
Rate Limits
Troubleshooting
Customers receiving an error should troubleshoot on their end to ensure everything is accurate. Then log the:
Request.
Response.
Error message.
Stack trace.
Contact Tecsys Customer care with this information. For more information on how to handle troubleshooting, see Troubleshooting Guide.
Reconciliation
Tecsys strongly recommends that any systems calling the OrderDynamics APIs should implement daily reconciliation logic to avoid missing data. It is the customer’s responsibility to manage data. For more information, see the Bulk API sections of this guide here.
Authorization
Any systems calling the OrderDynamics APIs should keep the authorization credentials secret.
Duplicates
Multiple API calls with duplicated information should not be submitted to OrderDynamics.
Azure Service Bus
External systems such as Middleware, ERP, and WMS systems that integrate with OrderDynamics need to subscribe to Azure Service Bus events and consume standard OrderDynamics APIs to retrieve order details.
General Best Practices for Specific APIs
The following are general best practices when using some of our APIs.
Images
When using our API to upload images, it's recommended that the image size be no more than 128KB per image. OrderDynamics supports JPEG, PNG, and GIF image formats.
You need to add a key to the content management system in you Azure storage account to upload images securely. To do this:
Log into your Azure storage account.
Navigate to Storage Accounts > Access Keys and generate an access key.
Add this key to your content management system settings.
You must have a access key for images to be uploaded correctly. If you do not add an access key, retrieving the images later return errors with our API and you may not see the image in Commerce Manager. This system will look for images in blob storage. If you have any images that are uploaded without an access key, these will need to be removed from storage. To remove any image use our Delete all Images Associated with Owner ID API to remove the image from storage.
Bulk APIs
We recommend, when using our Bulk Onhand Inventory API, that customers should send "Absolute" type only or "Delta" type only records as a part of 1 bulk API request. Sending both in the same request could lead to performance issues.
Although OrderDynamics does support "Delta" type updates, we recommend using "Absolute" type. "Delta" type only records can lead to inventory reconciliation issues. Requests can sometimes fail due to performance issues, down servers, or connectivity issues. This can cause mismatched inventory and improper updates. Using the "Absolute" type prevents this.
We support a file size limit of 30MB when bulk updating inventory. This is so you can send an average 100-150 thousand requests in a single API call.
When using our Bulk Status API it is recommended to return statuses of only failed operation details. You can do this by setting the parameter to "failed". This is to avoid data manipulation, sorting errors, and performance issues.
Rate Limiting
Rate limits are the specific number of API calls that can be made during a specific time duration. For example, you can limit your API to only 1000 calls per minute. Implementing rate limits helps with performance when making API calls. This helps avoid a burst of API calls at one time.
A visual representation of rate calls over 9 hours. The spike you see at 5PM is a burst of API calls.
The above example shows how at around 5PM the number of API requests spiked dramatically. This could cause the API responses to be extremely slow. Implementing a rate limit avoids this problem.
If you go over the rate limit, you receive an error message of 429 - Too Many Requests. (See HTTP Status Codes for more information).
To understand the best possible rate limit, keep track of the number of API calls made in a specific time period. To do this, you can implement a counter that keeps track of the number of API calls made, and when they were made.
Retry Mechanism
Implementing a retry mechanism helps ensure the batch of requests successfully reach our API gateway. API calls can fail for a number of reasons like: a faulty network connection, a site reloading after deployment, or too many requests being sent at one time.
A successful API request using the retry mechanism after a 50ms delay.
In the above example, the initial API request returned a server error. After waiting 50 milliseconds, the API automatically tried the request again and was successful.
When implementing the retry mechanism it's recommended setting the number of retries, the time between retries, and adding a final exit loop.
Threads
Threading allows for multiple API requests at the same time. This allows the API to run more efficiently and with fewer errors.
The number of threads you can open at once should be determined through performance testing. Run performance tests across all API methods and use the lowest common denominator as the optimum number of threads.
API Calls Increasing as Threads Increase
In the above example, you see that over a period of 15 minutes, the API calls that successfully completed increases as the number of threads increased. The more threads you have, the more performative your API will be.
Versioning
Each API endpoint is given a version, found in the URL. Below is an example of a URL from our API. The v1 in the URL signifies the version you are using:
https://api.qa1.orderdynamics.net/v1/customers
A new version is created when there are changes to the existing endpoint. This could be changing a parameter, renaming a field, or altering required fields. Keeping your API up-to-date with our most current version allows for the enhancements and bug fixes to be automatically implemented in your API.
There may be multiple versions of the same API endpoint in production at one time, and customers will be notified when a new version becomes available.
When a new version is made, the URL will reflect that change. The second version will have a v2, the third version will have a v3 and so on. To go along with the previous example, the new version of the Customers API will have a URL that looks like:
https://api.qa1.orderdynamics.net/v2/customers
A deprecation notice will be sent to merchants two releases before the v1 is removed from production.
Configurations
There are a few configurations settings you should implement to have the easiest possible experience using our APIs.
Information about Parameters
The following parameters must be set to TRUE in your OrderDynamics OMS configuration settings:
Parameter Name
Setting
Enable External Customer ID in Commerce Manager
Set to TRUE.
Enable External Address ID
Set to TRUE.
Allow Splitting of Existing Shipments
Set to TRUE.
Force Invoicing Before Shipments
Set to TRUE.
Enable External Order ID in Call Center
Set to EDITABLE.
Products API
When creating a product with our API, the following fields are required.
Required Parameters
Where to Create Them
Brand
You must choose an existing brand when creating a product. If you need to create a new brand, you need to create one using the OrderDynamics Commerce Manager application.
Manufacturer
You must choose an existing manufacturer when creating a product. If you need to create a new manufacturer, you need to create one using the OrderDynamics Commerce Manager application.
Website
When creating a product using the API, the default website is set to Call Center. If you need to create a new website or change the website to a different site, do this using the OrderDynamics Commerce Manager application.
Culture/Currency
When creating a product using the API, the default culture and currency is set to en-US and USD respectively. If you need to change this, you need to use the OrderDynamics Commerce Manager application to do so.
Order Orchestration API
When creating an order with our API, the following fields are required.
Required Parameters
Where to Create Them
Shipping Rate
You must choose an existing shipping rate when creating an order. If you need to create a new shipping rate, you need to create one using the OrderDynamics Commerce Manager application.
Tax Rate
You must choose an existing tax rate when creating an order. If you need to create a new tax rate, you need to create one using our Taxes API or by using the OrderDynamics Commerce Manager application.
Order Fulfillment API
When routing an order with our API, the following fields are required. It's important to note that legacy routing is not supported.
Required Parameters
Where to Create Them
Shipping Center
You must choose an existing shipping center when routing an order. If you need to create a new shipping center, you need to create one using our Shipping Center API or by using the OrderDynamics Commerce Manager application.
Inventory Location
You must choose an existing inventory location when routing an order. If you need to create a new inventory location, you need to create one using our Shipping Center API or by using the OrderDynamics Commerce Manager application.
Order Routing Rule
You must choose an existing order routing rule when routing an order. If you need to create a new order routing rule, you need to create one using the OrderDynamics Commerce Manager application.
