Skip to main content

​
How it works

Two things identify a request:
  1. Your platform identifier, in the URL path (/api/v1/your_platform/deliveries). It tells us the delivery came through you.
  2. The merchant’s API key, in the Authorization header. It tells us whose delivery it is and which account to bill.
The key belongs to the merchant, not to you. You never hold a key of your own, and you are never billed for what your merchants book.

​
Getting a key

Merchants generate their own key in their UniHop dashboard and paste it into your app’s settings. There is nothing to request from us per merchant. You get your platform identifier at onboarding. Ask your account manager for it. Keys don’t expire, but a merchant can regenerate theirs at any time, which invalidates the old one immediately.

​
Example

​
When authentication fails

Every failure is a 401 with a machine-readable code:
A bad key and an unknown platform identifier return the same code, so the URL space can’t be enumerated. Retrying won’t fix a 401. Prompt the merchant to re-enter their key.

​
Rate limits

Requests are counted per merchant key, so one busy merchant can’t throttle the rest of your platform. Over the limit returns a 429 with a Retry-After header. Back off for that many seconds and retry. Planning a bulk import? Tell your account manager and we’ll raise the ceiling for the window.

​
Merchant attribution

The key already tells us which merchant an order belongs to, so you don’t need to send anything else to identify them. Use platform_payload for your own correlation: your order ID, your internal store ID, whatever you route on. We store the object untouched and return it on every read and webhook.