Build a shipping service

In this tutorial, we'll build a shipping service integration using a Swell shipping extension. The example returns rates from a simple handler, and the same patterns apply to integrating any shipping carrier or custom rate logic with Swell checkout.

The scope of the app includes the following:

→ Find the full source code for the shipping example app on GitHub.

To follow along, you'll need the Swell CLI and a Swell account. First, install the CLI and log in.

npm install -g @swell/cli

swell login

Next, clone the example app and push it to your test environment.

git clone git@github.com:swellstores/shipping-example-app.git

cd shipping-example-app

npm install

swell app push

The app declares a shipping extension in swell.json:

{
  "description": "A shipping service example app",
  "id": "shipping_example",
  "name": "Shipping Example",
  "type": "integration",
  "version": "1.0.0",
  "permissions": [],
  "extensions": [
    {
      "id": "example",
      "type": "shipping"
    }
  ]
}

The extension's id is referenced by the app's functions to associate them with the extension. A shipping extension may also specify a carrier id (defaulting to the extension id), along with carrier_logo_src and carrier_icon_src image assets to represent the carrier in the dashboard.

A real carrier integration needs API credentials, which the merchant provides through app settings:

{
  "label": "Shipping settings",
  "description": "Example shipping carrier configuration settings",
  "fields": [
    {
      "id": "api_key",
      "label": "API key",
      "type": "text"
    }
  ]
}

The example handler doesn't call an external API, but a real integration would read this value with req.swell.settings() and use it to authenticate with the carrier's rating API.

When Swell calculates shipping options for a cart or order — for example, when the customer enters their shipping address at checkout — the platform triggers the order.shipping event hook. The app handles it with a single function:

export const config: SwellConfig = {
  extension: "example",
  description: "Provide shipping rates from Example Shipping",
  model: {
    events: ["order.shipping"],
    conditions: {},
  },
};

export default async function (req: SwellRequest) {
  return {
    shipment_rating: {
      services: [
        {
          id: "example-standard",
          price: 10,
        },
      ],
    },
  };
}

The handler returns a shipment_rating object containing the services to offer, and the returned services become the shipping options the customer can select. Return multiple entries to offer several service levels, such as standard and express.

The handler receives the order data on req.data, including the items and shipping address. A real integration would pass these to the carrier's rating API — weights, dimensions, and destination — and map the carrier's response into the services array. If rates cannot be calculated, return errors in the shipment_rating object instead.

With the app pushed to your test environment:

To adapt this app to a real carrier, call the carrier's rating API from the handler using the credentials in app settings, and map its response into the services array. The same extension can also be combined with other app surfaces — for example, settings to let merchants toggle service levels, or notifications for shipping events. For the complete extension configuration and event reference, see the Extensions guide.

The shipping example app is meant as a reference for partners to learn and build from, but it is not ready for production. Review it carefully and test with your carrier's sandbox before using any of it in a live store.