Overview

Cartly's checkout shipping-rate step merges rates from three sources: configured shipping zones, hook-driven connectors (see the Webhooks guide), and native ShippingRateProvider implementations. A native provider is the recommended path for a first-party or deeply-integrated carrier connector that needs live rates, pickup-point/parcel-locker options, and shipment creation from the order page, rather than a generic outbound-hook shape.

The ShippingRateProvider Interface

A native provider implements a small interface that, given the cart contents and destination address, returns a list of candidate rates for the connected carrier — including any pickup-point or parcel-locker options the carrier supports. Rates returned by a provider are merged into the same rate list shown to the shopper alongside zone and hook rates, so a shopper never sees a duplicated or inconsistent set of options. Each provider is registered against the connector it belongs to, and only runs for shops where that connector is installed and active.

A provider is also the extension point responsible for shipment creation: given a placed order, it creates the shipment with the carrier and returns a printable waybill reference. Delivery status updates for a shipment created this way flow back into Cartly through the connector's existing webhook handling, and are reflected on the order automatically.

The order.shipping_line Snapshot

When an order is placed, the shipping option the shopper selected — whichever source it came from — is persisted as an immutable shipping_line snapshot on the order. This snapshot captures at minimum:

• carrier — the connector/carrier the rate came from
• method — the rate's display name shown to the shopper (e.g. a specific service tier)
• delivery kind — door delivery, pickup point, or parcel locker
• pickup-point code — the selected location's carrier-specific identifier, when the shopper chose a pickup point or parcel locker

Because the snapshot is captured at order placement, it stays accurate even if the shop's shipping configuration changes later — a zone is renamed, a connector is reconfigured, or rates change. Downstream consumers (order export, packing slips, the admin order-detail page) always read the snapshot, never the live configuration.

Contact Phone Requirement

A contact phone number is now required on the shipping address for every checkout, regardless of which shipping-rate source is used. Native providers can rely on the phone number being present when creating a carrier shipment — it does not need to be validated again in provider code.