Partners and vendors

Understand the difference between a Partner and a Vendor on the UrbnBox platform.

UrbnBox serves two types of business accounts. Choosing the right one determines which API you use, how you authenticate, and what you can do.

At a glance

	Partner	Vendor
Who they are	External platform or store (e.g. Shopify merchant, courier broker, marketplace)	Business with an UrbnBox dashboard account that sends deliveries
Integration model	Machine-to-machine API only	Dashboard (browser) + optional API
Credential	Secret API key (ub_live_…)	Dashboard login (email + password) + optional API key
Creates delivery orders via	Not applicable	Dashboard or POST /api/vendor/v1/orders
Creates pickup-point shipments via	POST /api/partner/v1/shipments	Dashboard or the Vendor API
Receives webhooks	Yes — configure endpoint in Admin → Partners	Yes — configure at /v/webhooks in the dashboard
Billed	Monthly invoice for logistics fees	Earnings settled per delivery via M-Pesa
Provisioned by	UrbnBox Admin	UrbnBox Admin

Partners

A partner is an external company or developer that sends parcels to UrbnBox from their own backend. Partners never log in to the UrbnBox portal. All interaction is server-to-server using a secret API key.

Typical partners:

• A Shopify or WooCommerce store using the UrbnBox shipping plugin
• A marketplace that handles its own checkout and offers pickup-point delivery
• A courier broker routing parcels between towns through UrbnBox
• A developer building a custom integration with the Partner API

Partners use the Partner API under /api/partner/v1/ and authenticate with X-API-Key. API keys are managed by UrbnBox Admin and returned once at creation — store them in your secret manager.

Send a pickup-point shipment

Create your first shipment as a partner.

Vendors

A vendor is a business registered directly on the UrbnBox platform. Vendors have a named account, log in to the portal at portal.urbnbox.io, and create and follow their delivery orders from the dashboard.

Typical vendors:

• A retailer that hands its customer deliveries to UrbnBox
• A wholesaler sending regular deliveries to shops and branches
• A small business owner creating delivery orders manually from the dashboard

Vendors can optionally generate an API key (from Integrations in the dashboard) to create orders from their own system. Vendor API keys authenticate against /api/vendor/v1/ endpoints.

Create a delivery order

Make your first request as a vendor.

Vendors are provisioned by UrbnBox Admin. There is no self-registration for vendor accounts.

Which should you use?

• You want UrbnBox riders to deliver your orders to customers → Vendor
• You run your own platform and hand parcels to UrbnBox to move between towns → Partner
• You are building a Shopify or WooCommerce plugin → Partner (the plugins authenticate as partners)

If you are unsure, contact [e-mail].