/buy-label

Purchase a shipping label for a paid order via the bound shipping partner (EasyPost).

Permissions

Admin-only. Caller must hold a role listed in BotConfig.adminRoleIds.

Usage

/buy-label order:<orderId> service:<token>

Option	Required	Description
order	yes	The order id (Mongo _id or display order number) to buy a label for. The shipment record is looked up by orderId.
service	no	Carrier_service token (e.g. usps_priority, fedex_ground, ups_ground). When omitted, the cheapest available rate is purchased. Pass an unknown value to forward verbatim to EasyPost.

Behavior

1. Resolves the shipment for the order.
2. Calls purchaseLabel on the shipment service. If a label already exists (idempotent path) the cached tracking + label URL is returned without re-purchasing.
3. Persists trackingNumber, labelUrl, carrier, and shippingCostCents from the EasyPost response.
4. Transitions shipment status to label_created.
5. Emits shipment.label-created on the event bus.

Replies

• Success: Label purchased for order \<id>` via <carrier>. Tracking: `<number>`. Label: <url>`
• No shipment found: No shipment found for order \<id>`.`
• Permission denied: Permission denied: you must have an admin role to use \/buy-label`.`
• Partner not configured: Shipping partner is not configured on this server. Set \EASYPOST_API_KEY` or use `/ship` with a manual tracking number.`
• Other failures: Failed to buy label: <message> — usually surfacing a 4xx from EasyPost (invalid postal code, missing carrier credentials, etc.)

Related

• /ship — manual mark-shipped path; always available regardless of partner config.
• Shipping management — full admin guide.
• shipment reference — service contract.