---
title: Shipping gateways and providers
slug: commerce-connect-15/docs/shipping-gateways-and-providers
docTags: 
createdAt: 2026-07-30T20:34:43.000Z
---

A shipping gateway is the .NET class that calculates shipping rates. A shipping provider is the configured Commerce Connect entity that wraps a gateway and exposes it to shipping methods.

Optimizely Commerce Connect includes two shipping gateway providers by default:

- **Generic Gateway** – Flat shipping rate.
- **Weight/Jurisdiction Gateway** – Base price plus an additional fee that depends on weight and shipping location.

Add your own shipping gateway and provider when neither built-in option fits. Under **Shipping Providers**, **Shipping Gateway** identifies the class you select (**Generic Gateway** or **Weight/Jurisdiction Gateway**).

Classes in this topic are available in the following namespaces:

- `Mediachase.Commerce.Orders` – Contains `IShippingGateway` and `IShippingPlugin`.
- `Mediachase.Commerce.Catalog.Data` – Contains `CurrencyAdmin`.
- `Mediachase.Commerce.Orders.Dto` – Contains `ShippingMethodDto`.

For details about shipping methods, see [Shipping methods](docId:6kPd_5vCUJupERmB36Kqu).

## Shipping gateways

Select a **Shipping Gateway** from the **Shipping Provider** view in Commerce Connect Admin. Configure the gateway values on the **Shipping Methods** page.

- **Shipping Jurisdictions** – Defines region-specific shipping rate values. Used only when you select the **Weight/Jurisdiction Gateway** — for example, *California*.
- **Shipping Jurisdiction Groups** – A group of jurisdictions, such as *Southwest region*. Required when configuring shipping method parameters.

## Shipping providers

Shipping provider classes retrieve shipping prices from one or more shipping services, such as USPS, UPS, or FedEx. A provider typically represents one service (for example, USPS), but it can also represent a shipping scenario such as overnight delivery, price-by-weight, or ground shipping. The provider can compare prices across services to find the lowest rate for a customer location.

## Key classes and files

- `IShippingGateway` – Interface that a shipping gateway must implement.
- `IShippingPlugin` – Same functionality as `IShippingGateway`, but uses the abstraction API instead of the concrete classes.
- `WeightJurisdictionGateway` – Example implementation.
- `GenericGateway` – Example implementation.
- `CurrencyAdmin` – Provides lookup for currency codes.
- `ShippingMethodDto` – DTO for shipping method configuration information.
- `JurisdictionManager` – Provides methods to retrieve jurisdictions.

:::hint{type="info"}
**Note**
Use `IShippingPlugin` for new gateways. `IShippingGateway` is retained for backward compatibility.
:::

## Create shipping options

To provide shipping options during checkout, add shipping methods, each of which uses a shipping provider. The procedure has two parts: implement the shipping plugin, then register the gateway and method in Commerce Connect Admin.

### Implement the shipping plugin

1. Create a separate project in the solution to store custom business logic for your application.
2. In that project, create a class that implements `IShippingPlugin`. The interface defines one method, `GetRate`, which returns the shipping rate for an `IShipment` from the cart. `GetRate` is where you call the shipping service or rate provider that determines the cost.

:::hint{type="info"}
**Note**
Remember to register the class with the service container as a service of `IShippingPlugin`.
:::

The method signature is:

```csharp
public ShippingRate GetRate(Guid methodId, IShipment shipment, ref string message);
```

The return value is a `ShippingRate` instance, which exposes the following properties:

- `Id` – The associated shipping method ID. This value is passed to the method as the first parameter.
- `Money` – The price for the shipping service. The currency must be one of the currencies configured for the application. To retrieve currency information from the database, use `CurrencyAdmin`.
- `Name` – The name of the shipping method associated with the shipping method ID.

The following example retrieves the shipping method ID:

```csharp
// Look up shipping method.
ShippingMethodDto methods = ShippingManager.GetShippingMethods(Thread.CurrentThread.CurrentCulture.Name);
// methodId was passed into GetRate as one of the method parameters.
ShippingMethodDto.ShippingMethodRow row = methods.ShippingMethod.FindByShippingMethodId(methodId);

string name;
if (row != null)
{
    name = row.Name;
}
else
{
    name = "";
}
```

### Register the gateway and method in Commerce Connect Admin

1. Copy the DLLs from the shipping gateway project to the `bin` folders of Commerce Manager and the public website.
2. Go to **Commerce** > **Administration** > **Shipping** > **Shipping Providers**.
3. Click **Create**.
4. Enter a name for the gateway and a system keyword. The keyword must be unique.
5. Select the gateway that implements `IShippingPlugin` (the class you created earlier).
6. Click **Save**.
7. Go to **Shipping** > **Shipping Methods**.
8. Click **Create**.
9. Fill in the shipping method fields, including the provider you created earlier. To make the shipping method available, set **IsActive** to **Yes**.
10. Click **Save**.

## Access shipping provider information

`ShippingManager` lets you retrieve the case rows that apply to the current scenario. Call this code from `GetRate`, or from a method that `GetRate` calls.

The following example retrieves shipping provider information:

```csharp
// methodId is passed into GetRate.
DataTable casesTable = ShippingManager.GetShippingMethodCases(
    methodId,
    shippingAddress.CountryCode,
    shippingAddress.State,
    shippingAddress.PostalCode,
    shippingAddress.RegionCode,
    null,
    shippingAddress.City,
    weight);
```

For an example of using this `DataTable`, see the `GetRate` implementation in `WeightJurisdictionGateway.cs`.

## Packages

Create packages and associate them with shipping providers. Define a generic package size, associate it with a product, and then map it to a provider-specific package. For example, a generic *LARGE* package can map to a 25 kg Large FedEx box and a USPS Large Flat Rate box.

To associate a package with a shipping provider, open the provider in Commerce Manager, go to the **Packages** tab, and click **Add Item**. To associate a package with a SKU, change the `Package` property on the SKU's **Pricing/Inventory** tab.

To retrieve package information for a shipping provider, use `ShippingMethodDto`. It contains two typed data tables with the package information:

- `ShippingPackage` – Contains the relationship between shipping providers and packages.
- `Package` – Contains the package information.

The following example retrieves package information for a shipping provider:

```csharp
ShippingMethodDto shippingMethods = ShippingManager.GetShippingMethods("en-us");

foreach (System.Data.DataRow row in shippingMethods.ShippingOption.Rows)
{
    // A shipping option is a shipping provider.
    ShippingMethodDto.ShippingOptionRow shippingProviderRow = (ShippingMethodDto.ShippingOptionRow)row;

    // Access the packages associated with the shipping provider.
    ShippingMethodDto.ShippingPackageRow[] packageRows = shippingProviderRow.GetShippingPackageRows();

    // Access each package's name and ID:
    // packageRows[0].ShippingPackageId
    // packageRows[0].PackageName

    // Retrieve the individual package row with additional information.
    ShippingMethodDto method = ShippingManager.GetShippingPackage(packageRows[0].PackageId);

    // GetShippingPackage populates the Package table with the applicable shipping package.
    if (method.Package.Rows.Count > 0)
    {
        ShippingMethodDto.PackageRow packageRow = (ShippingMethodDto.PackageRow)method.Package.Rows[0];

        // Retrieve the package properties:
        // packageRow.Length
        // packageRow.Height
        // packageRow.Width
        // packageRow.Description
    }
}
```