Shipping Bridge v26.3+

Maho's Shipping Bridge module lets you delegate shipping rate calculation to any external API. Instead of writing a custom carrier module, you configure a single API endpoint URL and Maho sends the full cart and address data as a JSON POST request, then renders whatever shipping methods the API returns.

Overview

Traditional carrier integrations require a dedicated module for every shipping provider. Shipping Bridge replaces that pattern with a single, generic connector:

• One module, any provider: Point it at a microservice, a serverless function, a third-party TMS, or your own ERP
• Zero code required: Everything is configured in the admin panel
• Rich payload: The API receives cart items, totals, shipping address, customer data, and any additional product attributes you select
• Flexible authentication: None, Bearer token, or custom header
• Multi-store support: Configuration is scoped per website

Use Cases

Third-party Shipping API

Connect to any shipping provider that offers a rate calculation API. Build a thin middleware that translates Maho's payload into the provider's format and returns the results.

Custom Business Rules

Deploy a serverless function (AWS Lambda, Cloudflare Workers, etc.) that implements your specific shipping logic -- zone-based pricing, weight tiers, customer group discounts, product category rules, or any combination.

ERP / WMS Integration

Point the endpoint at your ERP or warehouse management system to get real-time rates based on actual inventory locations and carrier contracts.

Multi-carrier Aggregation

Build a single endpoint that queries multiple carriers (UPS, FedEx, DHL) in parallel and returns the combined results as a unified list of methods.

How It Works

flowchart TD
    A[Customer enters checkout] --> B[Maho collects rates from all active carriers]
    B --> C[Shipping Bridge sends a POST request to your configured API endpoint]
    C --> D[Your API returns JSON with shipping methods]
    D --> E[Methods appear in checkout alongside other carriers]

Configuration

Navigate to System > Configuration > Sales > Shipping Methods > Shipping Bridge.

Settings Reference

Authentication Types

• None -- No authentication header is sent
• Bearer Token -- Sends Authorization: Bearer <token> header
• Custom Header -- Sends a custom header, e.g. X-Api-Key: <token>. The header name must contain only letters, numbers, and hyphens.

Additional Product Attributes

By default each cart item includes sku, name, qty, weight, price, and row_total. If your API needs more data (e.g. color, manufacturer, shipping_class), select those attributes in the Additional Product Attributes multiselect. They will be appended to each item in the request payload.

For select and multiselect attributes, both the raw value and the admin label are sent:

{
  "color": {
    "value": "25",
    "label": "Red"
  }
}

For all other attribute types the raw value is sent directly.

API Contract

Request

Maho sends an HTTP POST with Content-Type: application/json.

{
  "cart": {
    "items": [
      {
        "sku": "shirt-red-m",
        "name": "Classic T-Shirt",
        "qty": 2,
        "weight": 0.5,
        "price": 29.99,
        "row_total": 59.98,
        "color": { "value": "25", "label": "Red" },
        "size": { "value": "168", "label": "M" }
      }
    ],
    "totals": {
      "subtotal": 59.98,
      "weight": 1.0,
      "qty": 2
    }
  },
  "shipping_address": {
    "firstname": "John",
    "lastname": "Doe",
    "street": "123 Main St",
    "city": "Portland",
    "region": "Oregon",
    "region_code": "OR",
    "postcode": "97201",
    "country_id": "US"
  },
  "currency": "USD",
  "store_id": 1,
  "customer": {
    "customer_id": 42,
    "email": "[email protected]",
    "group_id": 1,
    "group_code": "General",
    "is_guest": false
  }
}

Request Fields

cart.items[]

cart.totals

shipping_address

customer

Response

Your API must return JSON with a methods array. Each method needs code, title, and price. Optional fields: cost, description, logo.

{
  "methods": [
    {
      "code": "standard",
      "title": "Standard Shipping (5-7 days)",
      "price": 5.99,
      "cost": 3.50,
      "description": "Delivered by USPS",
      "logo": "https://example.com/usps-logo.svg"
    },
    {
      "code": "express",
      "title": "Express Shipping (1-2 days)",
      "price": 14.99,
      "cost": 10.00
    }
  ]
}

Response Fields

Error Handling

• Non-2xx status codes: No shipping methods are shown; an error is logged
• Invalid JSON: Logged as an error; no methods shown
• Missing methods array: Logged as an error; no methods shown
• Individual method missing required fields: That method is skipped with a warning; other valid methods still appear

Return an empty methods array if no shipping options are available:

{
  "methods": []
}

Configurable Product Handling

For configurable products, the request payload includes:

• The configurable product's name and price
• The selected simple product's SKU
• Super attributes (the attributes used to configure the product, e.g. color, size) are always included automatically, resolved from the selected child product
• Additional attributes are resolved from the child product first, falling back to the parent if the child doesn't have a value

Ship-Separately Items

When a bundle or grouped product is configured to ship items separately, each child item is sent as its own entry in the items array with the combined quantity (parent qty * child qty).

Debug Mode

When Debug Mode is enabled, full request and response payloads are logged to var/log/shipping_bridge.log. This is useful during initial integration but should be disabled in production to avoid logging sensitive customer data.

Example log entries:

Shipping Bridge Request:
URL: https://api.example.com/rates
{"cart":{"items":[...],"totals":{...}},"shipping_address":{...},...}

Shipping Bridge Response:
{"methods":[{"code":"standard","title":"Standard","price":5.99}]}