Onboarding

Integrating is mostly a data exchange. This page is the checklist for both sides.

What we need from you

Credentials and endpoints

	Notes
Webhook endpoint URL	One HTTPS URL is enough for all four events. Give us separate URLs per event only if you want them. The path is part of the HMAC signing string, so tell us the exact URL.
Staging endpoint URL	A non-production endpoint we can test against before go-live.
Inbound signing secret	Only if the status updates you push to us are signed with your own secret — tell us how you sign and we will validate it.

Capabilities

	Why we ask
Push or poll?	Push is strongly preferred. Tell us if you have no outbound webhook capability, or if it is partial — for example if you can push lifecycle statuses but can only be polled for driver position.
Do you re-send failed webhooks?	If you push once and never retry, we queue inbound updates with retries on our side so an unreachable Gateway does not lose one permanently.
Your full status vocabulary	Every status your platform can emit, and what each one means, so we can agree the mapping onto the canonical lifecycle. Include the ones that carry no lifecycle meaning.
Do you model pickup and dropoff as separate legs?	It changes the mapping — the same status means different things per leg.
Supported payment collection types	Which of `cash_on_delivery`, `card_on_delivery` and `pay_in_store` your API can instruct a driver to collect. See Payment Methods.
Driver location reporting	Whether you can supply live driver position, and at what frequency.
PIN and signature support	Whether you issue a handover PIN, and whether you can require a signature.
Do you re-dispatch?	Whether a failed delivery can get a new delivery id on your side. If so we treat the new id as a fresh attempt and allow the status to reset.
Quoting	Whether you have a pricing API. If not, the delivery fee stays whatever the brand charges and we skip the quote call entirely.
Quote validity	How long your prices hold, so `expiration` is set sensibly.
Rate limits	Both directions — what you can accept, and what we should not exceed.
Cancellation window and fees	When you will stop accepting cancellations, and what you charge. Fees are commercial, not part of the API.
Service area	Countries, cities and any radius limits, so brands know where you can be offered.
Timezone	The timezone your API expects and returns. We send ISO 8601 with explicit offsets; some providers need local time.

Per-store data

This is the part most often forgotten, and nothing works without it.

	Notes
Your store identifier, per store	We store it against each store and send it as `provider_store_id` on every quote, dispatch and cancellation. If your platform has no per-store concept, say so and we will use `external_store_id` instead.
Confirmation of store coordinates	We hold latitude, longitude and address for every store and send them as the pickup point. These are maintained by hand on our side and a bad row looks exactly like an integration bug — worth verifying against your own records at go-live.
Store-level account or contract references	Anything else your platform needs to attribute a delivery to the right merchant account.

What we give you

	Notes
API key	The shared secret you verify our outbound webhook signatures with. Delivered out of band; never sent in a request.
Client identifier	Arrives as `X-Client-ID` on every webhook we send. Constant for your integration.
OAuth client id and secret	For the status updates you push to us. Separate from the API key.
Your provider id	Arrives as `user_id` in every webhook envelope.
Gateway and auth base URLs	Staging is `https://gateway-za.yumbidemo.com` with its token endpoint at `https://flexible-diamond-18-staging.authkit.app/oauth2/token`; production is `https://gateway.yumbi.com` with `https://auth.yumbi.com/oauth2/token`.
A staging environment	Wired to your staging endpoint, for end-to-end testing before live traffic. Staging credentials are separate from production ones and are issued first.

How a store gets switched on

Configuration is two levels, and both are required:

The provider is enabled for a brand. A brand opts in to you as a delivery option.
The provider is linked to a store, together with your provider_store_id for it. A store can only be linked to a provider its brand has enabled.

A store links to one delivery provider. Switching a store between providers, or running different providers across a brand's estate, is a configuration change on our side with no code change on yours.

Testing before go-live

Work through this in staging, per store, before taking live traffic:

Support

When raising a delivery problem with us, quote the order_guid. Every webhook we send you and every response you return is recorded against the order, so we can show you exactly what crossed the wire in both directions. order_delivery_assignment_id identifies a specific dispatch attempt where an order has had more than one.