Carrier reference

Every carrier is a Single DocType whose controller extends both Document and ShippingProviderBase:

from frappe.model.document import Document

from bwh_shipping.base_class import ShippingProviderBase


class AcmeCourierShippingSettings(Document, ShippingProviderBase): ...

Rules for every method

• Weights are in kilograms, dimensions in centimetres, and money in major units of the currency named alongside it. Convert to whatever the carrier wants with bwh_shipping.units.
• Statuses are ladder statuses, already mapped from the carrier's wording: Draft, Ready To Ship, Pickup Scheduled, In Transit, Out For Delivery, Undelivered, RTO, Delivered, Cancelled, Lost.
• To report failure, throw with frappe.throw. get_rates is the exception: return [] there.

get_rates

def get_rates(
	self,
	origin: dict,
	destination: dict,
	parcels: list[dict],
	cod: bool = False,
	declared_value: float = 0.0,
) -> list[dict]

Quotes every service that can carry the consignment. It's called once per carrier at checkout, and only when the carrier has an origin (its Pickup Address, unless the checkout passes one).

Parameters

Returns a list of:

Return [] when you can't quote, for example when the carrier doesn't serve the route. Checkout then prices the service from its Shipping Rule or Backup Charge. If you raise instead, the error is logged and checkout still renders.

create_shipment

def create_shipment(self, shipment: dict) -> dict

Books one consignment and buys its label. Called by ShippingRequest.book().

The shipment dict

Returns

After it returns, the request's status becomes Ready To Ship.

Throw when the carrier refuses the booking. If part of the booking already exists at the carrier, raise PartialBookingError instead (see Helpers).

cancel_shipment

def cancel_shipment(self, order_ref: str, shipment_ref: str | None = None, awb: str | None = None) -> dict

Cancels a booking. It's only offered while the request is Draft, Ready To Ship or Pickup Scheduled.

Returns {"status", "message"}. status is the carrier's own wording. The request becomes Cancelled either way, so throw if the carrier refuses.

get_tracking

def get_tracking(self, awb: str, shipment_ref: str | None = None, tracking_ref: str | None = None) -> dict

Reads the current status from the carrier. Called by ShippingRequest.sync_status().

Returns

The status only changes if the new one is higher on the ladder. Scans are added whether or not the status moves. Repeats are skipped by event_id, or by timestamp, status and message.

handle_webhook

def handle_webhook(self, payload: bytes, headers: dict) -> dict

Verifies a delivery to the webhook endpoint and says what it means.

Returns

See Webhooks and security.

Optional methods

Implement only what the carrier really supports. supports(capability) returns True when your class overrides the method. Desk actions for a capability you don't support fail with a clear message.

get_provider_name() is optional too. It returns a display name, and defaults to the class name.

Address

{
	"contact_name": "Ada Lovelace",
	"company_name": "Lovelace Labs",  # the Address title
	"line1": "1 MG Road",
	"line2": None,
	"city": "Bengaluru",
	"state": "Karnataka",
	"pincode": "560001",
	"country": "India",  # the Frappe Country name, not an ISO code
	"phone": "+919800000000",
	"email": "ada@example.com",
}

Convert country to an ISO code yourself if the carrier needs one. Build this dict from an ERPNext Address with get_address_payload(address_name) from bwh_shipping.bwh_shipping.utils.

Parcel

{"length": 30, "width": 20, "height": 10, "weight": 1.2, "count": 1}  # cm, cm, cm, kg

Helpers

bwh_shipping.units

bwh_shipping.status: SHIPMENT_STATUSES, can_advance(current, new), is_terminal(status).

bwh_shipping.exceptions.PartialBookingError(message, booking=None): raise it when a staged booking fails part-way, with booking={"order_ref": ..., "shipment_ref": ...}. BWH Shipping saves those references, and the Book Shipment button becomes Resume Booking, which calls your resume_booking.