Commerce Shipping API Reference
Corecommerce
Overview
Section titled “Overview”The Shipping API calculates shipping rates and integrates with carriers. Implement IShippingPlugin for custom shipping providers. IShippingManagerFacade manages shipping methods and rates.
Namespace
Section titled “Namespace”Optimizely.Commerce.Order
Key interfaces
Section titled “Key interfaces”| Interface | Purpose |
|---|---|
IShippingPlugin | Custom shipping rate calculation |
IShippingManagerFacade | Manage shipping methods and gateways |
IShipment | Represents a shipment within an order |
IShippingPlugin
Section titled “IShippingPlugin”Implement this interface to create custom shipping rate providers.
GetRate(IMarket, Guid, IShipment, ref string)
Section titled “GetRate(IMarket, Guid, IShipment, ref string)”Calculates the shipping rate for a shipment.
Parameters
| Name | Type | Description |
|---|---|---|
market | IMarket | Current market |
shippingMethodId | Guid | Shipping method identifier |
shipment | IShipment | Shipment with line items and address |
message | ref string | Output message for errors or warnings |
Returns: ShippingRate — contains the calculated amount and currency
Implement a custom shipping plugin
public class FlatRateShippingPlugin : IShippingPlugin
{
public ShippingRate GetRate(
IMarket market,
Guid shippingMethodId,
IShipment shipment,
ref string message)
{
var totalWeight = shipment.LineItems.Sum(li => li.Quantity);
decimal rate = totalWeight > 10 ? 15.99m : 5.99m;
return new ShippingRate(
shippingMethodId,
"Flat Rate Shipping",
new Money(rate, market.DefaultCurrency));
}
}ShippingRate properties
Section titled “ShippingRate properties”| Property | Type | Description |
|---|---|---|
Id | Guid | Shipping method ID |
Name | string | Display name |
Money | Money | Rate amount and currency |
IShippingManagerFacade
Section titled “IShippingManagerFacade”GetShippingMethodsByMarket(MarketId, bool)
Section titled “GetShippingMethodsByMarket(MarketId, bool)”Returns available shipping methods for a market.
Parameters
| Name | Type | Description |
|---|---|---|
marketId | MarketId | Target market |
returnInactive | bool | Include inactive methods |
Returns: IEnumerable<ShippingMethodDto.ShippingMethodRow>
GetRate(IShipment, ShippingMethodDto.ShippingMethodRow, IMarket)
Section titled “GetRate(IShipment, ShippingMethodDto.ShippingMethodRow, IMarket)”Calculates the rate using the configured plugin.
Parameters
| Name | Type | Description |
|---|---|---|
shipment | IShipment | Shipment to rate |
method | ShippingMethodDto.ShippingMethodRow | Shipping method |
market | IMarket | Market context |
Returns: ShippingRate
Get available shipping rates
public class ShippingService
{
private readonly IShippingManagerFacade _shippingManager;
private readonly IMarketService _marketService;
public ShippingService(
IShippingManagerFacade shippingManager,
IMarketService marketService)
{
_shippingManager = shippingManager;
_marketService = marketService;
}
public IEnumerable<ShippingRate> GetRates(IShipment shipment, MarketId marketId)
{
var market = _marketService.GetMarket(marketId);
var methods = _shippingManager
.GetShippingMethodsByMarket(marketId, false);
return methods.Select(m =>
_shippingManager.GetRate(shipment, m, market));
}
}IShipment properties
Section titled “IShipment properties”| Property | Type | Description |
|---|---|---|
ShipmentId | int | Unique shipment identifier |
ShippingMethodId | Guid | Selected shipping method |
ShippingMethodName | string | Display name of the method |
ShippingAddress | IOrderAddress | Destination address |
LineItems | ICollection<ILineItem> | Items in this shipment |
ShipmentTrackingNumber | string | Carrier tracking number |
ShippingDiscount | decimal | Discount applied to shipping |
Status | string | Shipment status |
Registering a shipping plugin
Section titled “Registering a shipping plugin”Register in dependency injection
services.AddTransient<IShippingPlugin, FlatRateShippingPlugin>();Common exceptions
Section titled “Common exceptions”| Exception | Cause |
|---|---|
ShippingException | Rate calculation failed |
InvalidOperationException | Shipping method not found for market |
ArgumentNullException | Shipment or address is null |