Skip to content
Tutorials Center
My learning

Topics

Lesson 20 of 33 ยท Payments, Shipping and Integrations

Fulfillment, Shipping and Tax Providers

Learn Medusa shipping and tax: fulfillment sets, service zones, shipping profiles and options, calculated rates, custom fulfillment providers, tax regions and rates.

After a customer pays, two questions remain: how does the parcel get there and how much tax is in the price. Medusa answers the first with the Fulfillment Module and the second with the Tax Module. Both follow the same pattern as payments: the module owns the records and rules, and a provider handles anything that depends on an outside system, such as a carrier's rate API or a tax service.

This lesson walks through the fulfillment model (sets, zones, profiles, options), the difference between flat and calculated shipping prices, how a custom fulfillment provider fits in, and how tax regions, rates and providers work. The real Medusa code needs a running server, so it is read-only. The runnable stand-ins are plain Node and reproduce the calculations. For the general ideas see Shipping Rates and Delivery Options, Fulfillment, Shipping and Returns and Taxes: VAT, Sales Tax and Rounding.

The fulfillment model

Four ideas explain where shipping options come from:

  • Stock location: where goods leave from (from the Stock Location Module, see Inventory, Stock Locations and Sales Channels).
  • Fulfillment set: a group of options attached to a stock location, either of type shipping (parcels leave the location) or pickup (the customer collects).
  • Service zone: inside a fulfillment set, a geographic area that the location serves, defined by geo zones such as countries or provinces. A shipping option belongs to exactly one service zone.
  • Shipping profile: a label for kinds of goods that need the same shipping rules, for example "default", "heavy" or "digital". Products are assigned a profile, and an option only applies to products in its profile.

A shipping option ties them together: it lives in a service zone, requires a shipping profile, uses a fulfillment provider and has a price type, either flat (a fixed amount, possibly with rules) or calculated (the provider computes the price from the cart).

flowchart TD
    SL["Stock location<br/>Berlin warehouse"] --> FS["Fulfillment set<br/>type: shipping"]
    FS --> SZ["Service zone<br/>Germany, Austria"]
    SZ --> SO["Shipping option<br/>Standard, flat 4.90"]
    SO --> SP["Shipping profile<br/>default"]
    SO --> FP["Fulfillment provider<br/>manual or custom"]

An option is valid only for the zone it sits in, the profile of the products, and the provider that can fulfill it.

When a cart has an address, the Store API lists the shipping options whose zone covers that address and whose profile matches every item in the cart. If one item is "heavy" and another is "default", the cart needs an option for each profile, which is how mixed carts get several shipping methods. You can see the flow in Building the Checkout Flow.

The manual provider and flat prices

Out of the box, Medusa ships a manual fulfillment provider (provider ID manual_manual). It calculates nothing and talks to no carrier: it lets you define options such as "Standard" and "Express" with fixed prices, and a staff member ships orders by hand and marks them fulfilled. Many small shops never need more.

The default configuration registers it for you. Registering providers explicitly looks like this (read-only; option names follow the module's pattern, check your version):

TypeScript
import { defineConfig } from "@medusajs/framework/utils"

export default defineConfig({
  modules: [
    {
      resolve: "@medusajs/medusa/fulfillment",
      options: {
        providers: [
          {
            resolve: "@medusajs/medusa/fulfillment-manual",
            id: "manual",
          },
          {
            resolve: "./src/modules/acme-carrier",
            id: "acme",
            options: { apiKey: process.env.ACME_API_KEY },
          },
        ],
      },
    },
  ],
})

Shipping options are normally created in the Admin (Settings, Locations and Shipping), or from code with a workflow such as createShippingOptionsWorkflow. A flat option's price can also vary by cart total or by region through price rules, the same price-set mechanism described in Prices, Currencies and Regions: "free above 50.00" is just a rule on the option's price.

Custom fulfillment providers

A carrier integration extends AbstractFulfillmentProviderService. Its job is to answer the questions Medusa asks during checkout and fulfillment. A trimmed, read-only sketch:

TypeScript
import { AbstractFulfillmentProviderService } from "@medusajs/framework/utils"

class AcmeCarrierService extends AbstractFulfillmentProviderService {
  static identifier = "acme"

  async getFulfillmentOptions() {
    // the services this carrier offers; the Admin lists them when creating an option
    return [
      { id: "acme-standard" },
      { id: "acme-express" },
    ]
  }

  async validateFulfillmentData(optionData: Record<string, unknown>, data: Record<string, unknown>) {
    // check data supplied at checkout (for example a pickup point id)
    return data
  }

  async canCalculate() {
    return true // this carrier supports calculated prices
  }

  async calculatePrice(optionData: Record<string, unknown>, data: Record<string, unknown>, context: Record<string, any>) {
    // call the carrier's rate API using the cart's items and address
    return { calculated_amount: 1290, is_calculated_price_tax_inclusive: false }
  }

  async createFulfillment(data: Record<string, unknown>, items: any[], order: any, fulfillment: any) {
    // book the shipment, return tracking data
    return { data: { tracking_number: "ACME123" } }
  }

  async cancelFulfillment(data: Record<string, unknown>) {
    return {}
  }
}

export default AcmeCarrierService

Method names and argument shapes have shifted between Medusa 2 releases, so use your installed types as the reference. The important concepts are stable:

  • canCalculate and calculatePrice power calculated options. At checkout Medusa asks the provider for the price instead of reading a stored amount. Because a carrier call can be slow or fail, cache results sensibly and decide what to show when the carrier is down.
  • createFulfillment runs when staff fulfill an order. It books the label and returns data (tracking numbers) that Medusa stores on the fulfillment.
  • The provider receives data, not database access. Like every module, it stays isolated and returns plain results.

Stand-in 1: a shipping rate calculator by weight and zone

The first stand-in is not Medusa code. It shows what a calculatePrice implementation typically does: find the zone for the address, find the weight band, add a surcharge, and apply a free-shipping threshold. All amounts are integer cents.

Node.js Shipping rates by zone and weight band

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

The same function could sit behind calculatePrice. Note the design choices: weights are summed from line items, the first matching band wins, the world zone is the catch-all, and "free shipping" is a rule on top rather than a separate table.

Tax: regions, rates and providers

The Tax Module answers "how much tax is on this line item and shipping method?" Its records are:

  • Tax region: a country (optionally a province) where you collect tax. Regions can have a parent, so a country region holds the default and a province region overrides it.
  • Tax rate: a percentage with a name and a code, belonging to a region. A region has a default rate, and you can add rates with rules that target specific products, product types or shipping options (reduced rates for books or food, for example).
  • Tax provider: the code that computes tax lines. Medusa's default provider is a system provider that looks up the rates you configured in the Admin. You can register a custom provider that calls a service such as an external tax engine, by implementing a tax provider interface whose central method receives the line items, shipping methods and address and returns tax lines for each.

Whether prices already include tax is controlled by the price preferences covered in Prices, Currencies and Regions: the same 100.00 label can be net or gross, and the tax lines make the difference explicit. The general rules for rounding, inclusive versus exclusive prices and reverse charge live in Taxes: VAT, Sales Tax and Rounding.

Configuring a custom tax provider mirrors payments (read-only):

TypeScript
modules: [
  {
    resolve: "@medusajs/medusa/tax",
    options: {
      providers: [
        {
          resolve: "./src/modules/my-tax",
          id: "my-tax",
          options: { apiKey: process.env.TAX_API_KEY },
        },
      ],
    },
  },
]

After registering it, you pick the provider per tax region in the Admin. A region without a provider setting uses the system provider.

Stand-in 2: tax lines with a default rate and rules

This stand-in computes tax lines the way a region with a default rate and a rate with product rules would, for both tax-exclusive and tax-inclusive prices. Rounding happens per line, in integer cents.

Node.js Tax lines with default and reduced rates

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Compare the two blocks: with tax-exclusive prices the customer pays more than the label, and with tax-inclusive prices the total equals the label while the tax is extracted from it. The reduced book rate is chosen by a rule on product type, and the default rate catches everything else.

Rounding per line versus per order can differ by a cent. Decide on one rule, document it, and make sure that your tax provider and your accounting export agree. A custom tax provider is a good place to enforce it.

Common mistakes

  • No option for a profile. A product whose shipping profile has no option in the customer's zone cannot be checked out. Test one product per profile.
  • Zones that do not cover the address. If a country is missing from every service zone, the shopper sees no shipping options at all.
  • Missing tax region. Without a tax region for the destination, no tax lines are created. Decide whether that means zero tax or "not shippable" and set it up on purpose.
  • Assuming provider calls are always fast. A calculated rate calls out over the network on checkout; add timeouts and a fallback message.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What does a service zone define inside a fulfillment set?

    A service zone groups geo zones such as countries or provinces. A shipping option belongs to one service zone and is offered only for addresses inside it.
  2. 2. What is a shipping profile used for?

    Profiles such as default, heavy or digital are assigned to products. A shipping option requires a profile, so it is offered only when the cart items match.
  3. 3. Which flat-versus-calculated statement is correct?

    A flat option has a stored price (possibly with rules). A calculated option asks the fulfillment provider, via canCalculate and calculatePrice, for the price from the cart.
  4. 4. A 7% rate applies only to books while the region default is 19%. How is this set up?

    A tax region has a default rate, and extra rates with rules (for example on product type) override it for matching items.

Summary

  • Shipping options live in service zones inside fulfillment sets attached to stock locations, and require a shipping profile and a fulfillment provider.
  • The manual provider gives you flat, hand-fulfilled options; custom providers add calculated prices and label booking.
  • canCalculate and calculatePrice power calculated rates; createFulfillment books the shipment.
  • Tax regions hold default rates and rule-based rates; a tax provider turns line items and addresses into tax lines.
  • Keep amounts as integers and agree on one rounding rule.

Next, see how customers hear about all of this in Notifications, Email and File Providers.