- v1.0.0-latest-prod
The ShipEngine integration enables using ShipEngine for shipping rates during checkout and for printing shipping labels for orders in the admin.
|
Important
|
Weight must be set on products for accurate rate quotes. |
Implements both FulfillmentPricingProvider and ShippingLabelProvider. This class serves as the bridge between the general Shipping Service logic and the specific ShipEngine logic.
Methods in this interface represent REST API operations that ShipEngine supports. The general format of each method is:
Convert Shipping Service DTO into a ShipEngine DTO
Build a ShipEngineRequest with the ShipEngine URI, DTO, and response type
Send that ShipEngineRequest object to the #callShipEngineAPI method to perform the REST call and return the result.
There are methods implemented in DefaultShipEngineService that are not used currently. They are available to any client customizations that might use them. The pattern should also facilitate quickly implementing any additional ShipEngine functionality that is not yet present.
ShipEngineAutoConfiguration - All ShipEngine related configuration and beans are referenced or configured here.
ShipEngineProperties - Set fields such as ShipEngine API key, tax codes for shipping charges, and default FROM address.
POJOs for requests and responses of the ShipEngine REST API are in the shipengine.domain package.
It is possible to use ShipEngine to create shipping labels for fulfillments. Here is the process when ShipEngineFulfillmentPricingProvider#provideShippingLabel is called:
It first looks up ShipmentDetails for the OrderFulfillment.
If there are ShipmentDetails, then an existing label is fetched from ShipEngine.
If there are no existing ShipmentDetails and the purchase boolean is true, then the label provider will call the ShipEngine purchase label endpoint.
This operation creates charges on your ShipEngine account.
Once a label is purchased, the label id is saved to the ShipmentDetails.
Once purchased, the same label can be retrieved in the future without charging the account again. The shipping label button on the admin order screen will say "Reprint Shipping Label" if the label has already been purchased.
The ShipEngineFulfillmentPricingProvider only needs a few ShipEngine endpoints for shipping rates and labels. Here are the mappings of FulfillmentPricingProvider methods to ShipEngine endpoints for the ShipEngineFulfillmentPricingProvider and DefaultShipEngineService.
| FulfillmentPricingProvider method | ShipEngineService method | ShipEngine REST API endpoint |
|---|---|---|
providePricedFulfillmentOptions |
getRates |
/rates |
calculateCostForFulfillmentGroup |
retrieveRate |
/rates |
estimateCostForFulfillmentGroup |
retrieveRate |
/rates |
provideShippingLabel |
retrieveLabel, purchaseLabelFromRate, purchaseLabel |
GET/labels, /labels/rates, POST/labels |
There are more ShipEngine functions available in the DefaultShipEngineService than what are used in the default checkout flow. Here is a list of all ShipEngine endpoints that have a corresponding method in DefaultShipEngineService.
| ShipEngine Endpoint | Request Type | DefaultShipEngineService method |
|---|---|---|
/v1/rates/estimate |
POST |
getEstimate |
/v1/rates |
POST |
getRates |
/v1/rates/{rateId} |
GET |
retrieveRate |
/v1/rates/bulk |
POST |
getBulkRates |
/v1/shipments/{shipmentId}/rates |
GET |
retrieveRateForShipment |
/v1/labels |
POST |
purchaseLabel |
/v1/labels/rates/{rateId} |
POST |
purchaseLabelFromRate |
/v1/carriers |
GET |
getCarriers |
/v1/labels/{labelId} |
GET |
retrieveLabel |