EasyPost Integration
Discover how Hotwax Commerce integrates with EasyPost, providing businesses of all sizes with a streamlined shipping solution.
Introduction
Hotwax Commerce integrates with EasyPost to empower businesses, ranging from small enterprises to large corporations, with a streamlined shipping solution. This integration enables users to leverage the full capabilities of EasyPost, including rate shopping across a diverse range of carriers and real-time package tracking.
Authentication
Authentication and identification to the EasyPost API are accomplished by utilizing an API Key in every request. This API Key serves as your Basic Auth username, and no password is required. The authentication process ensures secure communication with the EasyPost API, and it is imperative to note the following details:
Authentication Type: EasyPost employs API Key-based authentication for requests. Each request must include the API Key as the Basic Auth username. The absence of a valid API Key or the use of an incorrect key will result in authentication failure.
Security Protocol: EasyPost mandates that all communication with the API is secured using TLS v1.2. Transport Layer Security (TLS) ensures the confidentiality and integrity of data exchanged between Hotwax Commerce and EasyPost, providing a secure environment for API interactions.
HTTP Restrictions: Requests made over HTTP are not supported. It is crucial to utilize HTTPS for all communication with the EasyPost API. Any attempt to make requests over HTTP will result in failure.
By adhering to these authentication specifications, Hotwax Commerce ensures the secure and authenticated exchange of data with EasyPost. The API Key serves as the access credential, and the implementation of TLS v1.2 guarantees the confidentiality and integrity of the information transmitted during the integration process. Please refer to the following example to understand how to include the API Key in your requests:
Replace YOUR_API_KEY
with the actual API Key provided by EasyPost for your integration. This authentication mechanism ensures a seamless and secure connection between Hotwax Commerce and the EasyPost API for shipping label generation.
APIs used
HotWax integrates with EasyPost using three key APIs, each serving a distinct purpose in the shipping label generation process.
Create a Shipment API
Purpose:
Create Shipment API shares all detailed shipment information with EasyPost, including package dimensions, weight, origin, and destination. In return, the API offers competitive rates from multiple carriers. For added flexibility, users can specify preferred carriers and their corresponding credentials. The API also generates custom shipping labels with adjustable size and format options.
In case of international shipping:
Fulfilling international orders requires accurate customs information for generating shipping labels and obtaining customs documents. While HotWax stores product details, it lacks the essential HS Tariff number and Custom Signer information for customs purposes.
HotWax integrates with your ERP system, automatically fetching HS Tariff numbers for products during order fulfillment. This daily synchronization ensures readily available HS codes whenever new products are added. HotWax stores these retrieved HS Tariff numbers alongside existing Good identifications for each product.
Alongside, HS tariff number of the product, EasyPost also requires a custom_signer value during shipment creation to validate the request. HotWax retrieves the designated custom signer value assigned by retailer stored in system properties in OMS.
Once both HS Tariff numbers and custom signer information are available, HotWax constructs a streamlined create shipment API request to EasyPost and generate shipping label.
Method
POST
Request:
Response:
EasyPost
consistently structures its responses, maintaining a common format. Unique details specified in each request are appended to this structure, ensuring dynamic adaptability while preserving a standardized response format.
In response, Easy Post
shares three types of rates, and in our integration, we're utilizing the rates found in the rate
attribute for rate shopping. For further details about the rates, you can refer to this documentation provided by Easy Post.
Buy a Shipment API
Purpose:
The Buy a Shipment API is employed to share the rate ID of a specific shipment with EasyPost. This API facilitates the retrieval of a shipping label corresponding to the provided rate ID.
Method
POST
Endpoint:
Request:
Response:
EasyPost
consistently structures its responses, maintaining a common format. Unique details specified in each request are appended to this structure, ensuring dynamic adaptability while preserving a standardized response format.
In this response, HotWax relies on two vital fields: tracking_code
provides the tracking information for the shipment, while label_url
allows users to generate the shipping label in their desired format for printing.
Refund a Shipment API
Purpose:
The Refund a Shipment API is employed to void the shipping label generated for a specific shipment. This is useful in cases where a shipment needs to be canceled or rerouted.
Method
POST
Endpoint:
Request:
Response:
EasyPost
consistently structures its responses, maintaining a common format. Unique details specified in each request are appended to this structure, ensuring dynamic adaptability while preserving a standardized response format.
In this response, HotWax relies on a key field, specifically refund_status
. Based on the response, HotWax confirms whether the label is void or not.
These three APIs form the core of the integration, allowing HotWax to seamlessly create shipments, obtain rates, purchase shipping labels, and refund shipments as needed using EasyPost's extensive carrier network. Refer to the respective API documentation for detailed information on request and response parameters.
Error handling
Bad Request (HTTP 400)
Description: The request was malformed or missing required parameters.
Handling: Check your request parameters and ensure they comply with the API documentation.
Unauthorized (HTTP 401)
Description: The request lacks proper authentication credentials or the provided credentials are invalid.
Handling: Double-check your API key or authentication credentials.
Not Found (HTTP 404)
Description: The requested resource could not be found.
Handling: Review the API endpoint to ensure it is correct.
Server Error (HTTP 5xx)
Description: The server encountered an internal error.
Handling: Report the issue to the API provider. Retry the request later.
References
Last updated