Delivery (Biteship)

Delivery is Biteship. The backend fetches courier rates, creates a draft shipment, and tracks it; the storefront only shows the courier options the backend returns.

How this page was verified

Read on 2026-09-15 from the backend deliveries module.

Backend

The deliveries module owns the deliveries table (plus non-entity couriers / shipping-methods models). It is REST-only (not in the GraphQL include).

DeliveriesService (src/deliveries/services/deliveries.service.ts) is the Biteship client. Base URL DELIVERY_BITESHIP_BASE_URL, Bearer DELIVERY_BITESHIP_API_KEY. Origin (the warehouse) comes from DELIVERY_WAREHOUSE_ZIPCODE and the DELIVERY_ORIGIN_* vars; available couriers from DELIVERY_COURIER_AVAILABLE. Endpoints it calls:

• /v1/couriers, /v1/rates/couriers — courier options and prices (used by frontCouriers at checkout).
• /v1/draft_orders and /v1/draft_orders/:id/confirm — create and confirm the shipment.
• /v1/trackings/:id — tracking.

The draft is created during createOrder() (see Cart and checkout).

Tracking callback

webhook-deliveries.service.ts handleEvent maps Biteship tracking status to the delivery state shipped / delivered; when delivered it sets the order to completed (see Orders). The inbound route is webhooks/deliveries; in production the callback arrives through the webhook receiver → SNS.

Storefront

The customer picks a courier in checkout via frontCouriers(memberCartId) (name, code, service, price, duration) then frontUpdateCartCourier (src/modules/shipping/components/shipping-form.tsx, src/lib/shipping/). Biteship is never named in the frontend — the options are whatever the backend returns.

Gotchas

• Rates depend on the origin env. Wrong DELIVERY_ORIGIN_* or DELIVERY_WAREHOUSE_ZIPCODE gives wrong or empty courier options.
• In dev, Biteship is the simulator, which can force /v1/draft_orders to 500 — so an order that fails at the delivery step on dev may be the toggle.