> ## Documentation Index
> Fetch the complete documentation index at: https://urbnbox.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](https://urbnbox.mintlify.site/guides/pickup-point-shipments.md)**
>
> 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](https://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](https://urbnbox.mintlify.site/quickstart.md)**
>
> Make your first request as a vendor.

> [!NOTE]
>
> 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 [support@urbnbox.io](mailto:support@urbnbox.io).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.