Shipping Rates

About

Payload shops running `@payloadcms/plugin-ecommerce` get a shipping address field on orders and nothing else. This plugin fills the gap before checkout: it adds a `shipping-zones` collection to the admin panel, a `shipping` group on carts and orders to record the chosen method, and a `POST /api/shipping-rates/quote` endpoint that prices delivery to a given address. A zone matches by country (a named country, or the wildcard `*` for everywhere) and optionally by postcode patterns. Four pattern forms are supported: numeric ranges like `1000...1999`, prefix wildcards like `SW1*`, a catch-all `*`, and exact matches. When several zones cover one address, exactly one wins. The winner is chosen by explicit priority first, then by specificity (a postcode match beats a country match, a named country beats the wildcard), then by the lower zone id. The result is deterministic for the same cart and address. Each zone holds any number of methods. Five types are available: `flat` charges a fixed amount, `free_over` charges nothing once the subtotal clears a threshold, `weight_bands` and `price_bands` charge the band the cart weight or subtotal falls into, and `local_pickup` charges a flat amount that is normally zero. Bands use inclusive `from` and exclusive `to` boundaries with no upper bound when `to` is omitted, and they are sorted before evaluation so entry order never changes the answer. Every amount is an integer in minor units, the same units the official ecommerce plugin uses for prices. A method that cannot be costed is withdrawn with a reason rather than quoted at zero, and when no zone covers the address the endpoint returns `available: false` with `reason: 'no_matching_zone'`. The plugin ships with no runtime dependencies and no admin components, which keeps it stable across minor Payload releases. It requires Payload 3.88 or newer and the official ecommerce plugin at the same version, and a `weightUnit` option (g, kg, lb, oz) controls how weight band boundaries are interpreted.

Package info

Package name

payload-shipping-rates

Latest version

1.0.0

Unpacked size

50 kB

License

MIT

Weekly downloads

139

Last publish

Aug 21, 2026