Delivery Integrations

YUMBI Gateway sits between the channel a customer orders from and the courier network that carries the food. A delivery provider integration connects your courier network to every brand and store on the platform through one contract, so a brand can switch providers, or run different providers per store, without either side changing anything.

This section is written for a delivery provider building and hosting that integration themselves, from scratch. Read it in order — each page assumes the one before it.

What you build

One HTTPS endpoint that we call, and one endpoint of ours that you call.

We post four event types to your endpoint. You reply with the result in the response body — there is no separate callback for these. Everything is distinguished by an event_type field in the request, so a single URL can serve all four.

sequenceDiagram
    participant Channel as Ordering Channel
    participant Gateway as YUMBI Gateway
    participant You as Your endpoint

    Channel->>Gateway: customer is at checkout
    Gateway->>You: delivery_provider.quote_request
    You-->>Gateway: 200 fee, ETA, expiration

    Channel->>Gateway: order placed
    Gateway->>You: delivery_provider.dispatch
    You-->>Gateway: 200 provider_delivery_id, pin_code

    loop until terminal
        You->>Gateway: POST /api/v1/deliveries/{order_guid}/status_update
        Gateway->>Channel: forwarded to the channel
    end

    opt customer or store cancels
        Gateway->>You: delivery_provider.cancellation_request
        You-->>Gateway: 200
    end

The ordering channel never talks to you and never learns which provider carried its order. You never learn which channel the order came from. Everything crosses through the Gateway.

The four events we send you

Only the first three are mandatory. status_request is needed only if you cannot push status updates to us; see Status Request.

The one call you make to us

POST https://gateway.yumbi.com/api/v1/deliveries/{order_guid}/status_update

Every status change, and optionally every driver-position ping. See Pushing Status Updates.

Which direction is authenticated how

The single most common integration mistake is getting this backwards:

Inbound calls to the Gateway are OAuth only. The X-HMAC headers we sign our outbound webhooks with are not accepted on the way in — a correctly signed request carrying no bearer token is a 401. Full detail in Authentication.

You host the integration

You implement this contract on your own infrastructure. YUMBI Gateway does not build or run a translation layer against your API — the endpoint is yours, and the contract on these pages is the whole of it.

Two consequences worth knowing up front:

You identify stores by your own identifier. Every quote, dispatch and cancellation carries provider_store_id — the id you gave us for that store during onboarding. external_store_id, YUMBI Gateway's own store identifier, is the fallback. See Onboarding.

You never receive YUMBI Gateway's internal identifiers. brand_id and brand_guid appear in the payload schema but are always null for you. They exist for YUMBI Gateway's internal use and are not sent outside. Nothing you build should depend on them.

Reference values

Build and test against staging first. The two environments have separate credentials — your staging client id, client secret and API key will not work in production, and neither will the reverse. Make the base URLs and the token endpoint configurable rather than compiling them in.

All money is in cents, as integers. All timestamps are ISO 8601 with an explicit offset. Coordinates are decimal degrees; note that several fields serialise as decimal strings rather than JSON numbers, and are marked as such where they appear.