Ship from your store with the Obana API

Get started

Quickstart

Five steps from zero to a working key. Each store you run (website, Shopify shop, mobile app) gets its own key, so you can see and control their shipments separately.

1. 1

   Sign in to Obana

   Sign in or create a free account.
2. 2

   Open Stores & API

   In your dashboard, go to Stores & API.
3. 3

   Add a store and copy its key

   Click Add store. Your key (obk_live_…) is shown once — we only keep a hashed copy. Lost it? Rotate the key to get a new one; the old key stops working straight away.
4. 4

   Add a webhook URL (optional)

   Give the store a public https:// address and press Send test event to check it arrives. See Webhooks.
5. 5

   Test your key

   Call GET /stores/me. A 200 with your store’s name means you’re connected.

Get started

Authentication

Send your store key as a bearer token in the Authorization header of every call that needs one.

What a store key can do

Store keys are made for integrations and only open these calls:

• Get quotes — POST /routes/quote
• Create shipments — POST /shipments
• List your store’s shipments — GET /stores/me/shipments
• Track and cancel your store’s shipments — /shipments/track/…, /shipments/cancel/…
• Check the key — GET /stores/me

Any other route answers 403. So does a key whose store is paused — un-pause the store in your dashboard to switch it back on. A missing key gets 401.

Get started

Responses & errors

Successful calls answer { "status": "success", "data": … }. Failed calls answer { "status": "error", "message": "…" } with a plain-English message you can show your team. Shipment calls (/shipments…) use "success": true or false instead of status, so check the HTTP status code first.

200 / 201

It worked. 201 means a shipment was created.

400

Something in the request is missing or wrong. Read message, and errors when present — it lists every field to fix.

401

No key was sent.

403

The key is invalid, its store is paused, or store keys can’t use this route.

404

Not found — or it belongs to another store.

429

Too many requests. Wait for the number of seconds in the Retry-After header, then try again.

5xx

Something went wrong on our side. Retry with backoff (for example after 1 s, 2 s, 4 s).

There are no 409 conflicts: sending an order_id you’ve already used returns the existing shipment instead (see Create a shipment).

Shipments

Get a quote

Show buyers real delivery prices before they pay. Every option on the route comes back, with the cheapest and fastest marked for you.

No key is needed, so it’s fine to proxy it for your checkout. Limit: 20 quotes per 10 minutes per IP address. Identical quotes are cached for 30 minutes.

A route we don’t cover yet answers 404 with No routes available for this shipment.

Shipments

Create a shipment

Book a delivery for an order. Call it when the order is paid; we price it, assign the carrier and start tracking.

Save shipment_reference (for tracking) and shipment_id (for cancelling) against your order, and share tracking_url with your customer. The fee charged comes back straight away as shipping_fee (with currency), and also when you list shipments and in webhook events.

When it fails

Missing or invalid fields answer 400 with "message": "Invalid payload" and an errors array naming each field. A route we don’t cover answers 400 with:

{
  "success": false,
  "message": "We don't deliver on this route yet. Contact us to add it."
}

Shipments

List your shipments

Everything your store has shipped, newest first. Filter by customer, order number or status to answer the questions your team gets every day.

pagination gives total, page, pages and limit.

Recipe: all shipments for one of your customers

curl "https://obana-logistics-t6qg.onrender.com/stores/me/shipments?customer_id=cus_8812" \
  -H "Authorization: Bearer $OBANA_API_KEY"

Recipe: find a shipment by your order number

curl "https://obana-logistics-t6qg.onrender.com/stores/me/shipments?order_id=SO-1042" \
  -H "Authorization: Bearer $OBANA_API_KEY"

Recipe: everything in transit right now

curl "https://obana-logistics-t6qg.onrender.com/stores/me/shipments?status=in_transit&limit=100" \
  -H "Authorization: Bearer $OBANA_API_KEY"

Shipments

Track a shipment

Get one shipment in full: addresses, items, current status and its tracking_events, newest first.

A store key only sees its own store’s shipments — anything else answers 404.

Shipments

Cancel a shipment

Cancel an order’s delivery before we collect it. Use the numeric shipment_id from the create response (id in lists), not the reference.

Only shipments still pending can be cancelled. Later statuses answer 400, e.g. Shipment cannot be cancelled in picked_up status — contact support instead.

Shipments

Shipment statuses

A shipment moves through these statuses. Each change triggers a shipment.updated webhook.

pending

Created and waiting to be confirmed. This is the only status you can cancel from.

confirmed

Accepted by Obana — a pickup is being arranged.

picked_up

Collected from your pickup address.

dispatched

Sent out on its journey to the customer.

in_transit

On the way to the delivery address.

delivered

Handed over to the customer. Done.

failed

The delivery couldn’t be completed. Check the tracking events or contact support.

cancelled

Cancelled before pickup. Nothing will be delivered.

returned

Sent back to the pickup address.

Platforms

Thaja

Thaja stores connect to Obana Logistics from the dashboard — there is nothing to build. You paste your Obana store key once, and Thaja does the quoting and the booking for you.

Connect your store

1. 1

   Create a key in Obana

   Obana dashboard → Stores & API → create a store for this shop → copy the key. One key per shop, so each shop's shipments stay separate and you can revoke one without touching the others.

2. 2

   Paste it into Thaja

   Thaja dashboard → Settings → Integrations → Obana Logistics → Connect. Paste the key and save. Thaja checks it with Obana before saving, so a mistyped key fails there and then rather than at a customer's checkout weeks later.

3. 3

   Turn on prices at checkout

   Connecting does not change your checkout on its own — that is deliberate, so nothing moves under your customers without you asking. Use Turn on at checkout when you are ready.

What your customer sees

At checkout

The delivery options Obana runs on that lane, priced from the parcel's weight and where it is going — not a flat rate that is wrong in both directions.

After they pay

A tracking link, and a WhatsApp message when the parcel moves.

While it travels

Package Created, In Transit, Fulfilled — the same three words you see.

What Thaja does on your behalf

Nothing here is yours to build, but it is worth knowing what your store is doing with your key. These are the same public endpoints any platform uses.

POST /routes/quote
{
  "origin":      { "city": "Ikeja",   "state": "Lagos", "country_code": "NG" },
  "destination": { "city": "Ughelli", "state": "Delta", "country_code": "NG" },
  "weight_kg": 2,
  "declared_value": 50000
}

No key needed for a quote, so a price can be shown before anyone commits to anything. It returns every service on the lane, cheapest first.

POST /shipments
Authorization: Bearer <your store key>
{
  "order_id": "TJ-1024",
  "transport_mode": "road",
  "service_level": "Standard",
  "pickup_address":   { ... your location ... },
  "delivery_address": { ... your customer ... },
  "items": [{ "name": "Shirt", "quantity": 1, "weight": 0.5, "value": 200000 }]
}

If something looks wrong

No prices at checkout

Check that Turn on at checkout is on. Connecting alone does not change checkout.

"We don't deliver from … to … yet"

Obana quotes lanes it runs. The reply carries code: route_unavailable and names the lane, so it can be shown to a shopper as it stands or sent to us to be priced.

A shipment was refused

Almost always a missing delivery phone number. A courier cannot collect without one.

The key stopped working

Rotating a key in Obana does not update Thaja. Paste the new one and save again.

Platforms

Shopify

There is no Obana app in the Shopify app store yet. You connect the two with a small piece of your own code — a serverless function is enough — and it takes about an hour.

The flow

1. Shopify → you

An orders/paid webhook fires when a customer pays.

2. You → Obana

Book the shipment with the order's address and line items.

3. You → Shopify

Write the Obana tracking number onto the fulfilment, so the customer sees it in Shopify's own emails.

4. Obana → you

Status webhooks as the parcel moves, which you can mirror onto the order.

1. 1

   Create a store key

   In your Obana dashboard, Stores & API → create a store for the Shopify shop → copy the key. One key per shop, so you can see each shop's shipments separately and revoke one without touching the others.

2. 2

   Subscribe to orders/paid

   In Shopify admin: Settings → Notifications → Webhooks → Create webhook. Event Order payment, format JSON, pointed at your own endpoint.

   Verify Shopify's HMAC header before trusting the body — anyone can post to a public URL.

3. 3

   Show the price before checkout (optional)

   Quote the lane from your backend and return it to the cart, so the customer sees the real delivery price rather than a flat rate:

   Quote a laneCopy

   curl -X POST https://logistics.obana.africa/routes/quote \
     -H "Content-Type: application/json" \
     -d '{
       "origin":      { "city": "Ikeja",   "state": "Lagos", "country_code": "NG" },
       "destination": { "city": "Ughelli", "state": "Delta", "country_code": "NG" },
       "weight_kg": 2,
       "declared_value": 50000
     }'

   This one needs no key, so it is safe to call from a serverless function without secrets. It returns every service on the lane, cheapest first.

4. 4

   Book the shipment when the order is paid

   Your webhook handlerCopy

   // Shopify sends the paid order; you send Obana a shipment.
   const order = req.body;
   
   const shipment = await fetch("https://logistics.obana.africa/shipments", {
     method: "POST",
     headers: {
       "Content-Type": "application/json",
       Authorization: `Bearer ${process.env.OBANA_STORE_KEY}`,
     },
     body: JSON.stringify({
       order_id: order.name,                    // "#1024" — your reference in Obana
       transport_mode: "road",
       service_level: "Standard",
       pickup_address:   YOUR_WAREHOUSE,
       delivery_address: {
         first_name: order.shipping_address.first_name,
         last_name:  order.shipping_address.last_name,
         phone:      order.shipping_address.phone,   // required: a courier must be able to call
         email:      order.email,
         line1:      order.shipping_address.address1,
         city:       order.shipping_address.city,
         state:      order.shipping_address.province,
         country:    order.shipping_address.country,
       },
       items: order.line_items.map((li) => ({
         name: li.title,
         quantity: li.quantity,
         weight: (li.grams || 500) / 1000,      // Obana prices in kilograms
         value: Number(li.price),
       })),
     }),
   }).then((r) => r.json());

5. 5

   Write the tracking number back to Shopify

   Back to ShopifyCopy

   await shopify.fulfillment.create(order.id, {
     tracking_number:  shipment.data.shipment_reference,
     tracking_url:     shipment.data.tracking_url,
     tracking_company: "Obana Logistics",
     notify_customer:  true,
   });

Zoho

Connect Zoho to Obana Logistics

Obana Logistics connects to Zoho Inventory and Zoho Books directly. Someone in ops flags a sales order, a shipment is booked, the price comes back onto the order, and the customer is notified — without anyone retyping an address.

There are two ways to set it up, and which one you use is decided by your catalogue rather than by preference.

Your items are goods

Use Zoho's own shipment records. Zoho creates a package and a shipment order, Obana carries the parcel, and both systems hold the same documents. See Goods: the direct route.

Your items are services

Zoho will not put a service item in a package, and a shipment order cannot exist without one. The lifecycle lives on the sales order instead. See Services: the custom-field route.

Zoho

Custom fields to create

Both routes use the same fields on Sales Orders. Create them once, in Zoho Inventory under Settings → Preferences → Sales Order → Field Customisation. The API names must match exactly — Obana reads them by name.

Zoho

Goods: the direct route

When your items are goods, Zoho can hold the shipment itself. A package is created against the sales order, a shipment order is raised against the package, and Obana carries the parcel. Both systems end up holding the same documents, so a reconciliation is a comparison rather than an investigation.

1. 1

   Create the custom fields

   As above. Obana reads and writes them by API name.

2. 2

   Add a workflow rule that books the shipment

   Zoho Inventory → Settings → Automation → Workflow Rules → New. Module Sales Orders, executed when a field is updated, on cf_shipment_status.

   Condition: cf_shipment_status is Package Created. Action: a webhook.

3. 3

   Point the webhook at Obana

   Method POST. URL, with your own secret:

   Webhook URLCopy

   https://logistics.obana.africa/zoho/shipment-trigger?salesorder_id=${SALESORDER.SALESORDER_ID}&secret=YOUR_WEBHOOK_SECRET

   The salesorder_id parameter is required. Obana fetches the order from Zoho with it — the webhook body itself is not relied upon, because Zoho sends XML and its placeholders do not always resolve.

4. 4

   Let Obana write back

   Obana books the shipment, creates the package and shipment order in Zoho, and writes cf_shipment_id, cf_tracking_url, cf_carrier_name and the shipping charge onto the order. Nothing further to configure.

5. 5

   Add rules for the later stages

   Two more rules on the same field, pointing at the status endpoint, so a status changed in Zoho reaches Obana:

   Webhook URLCopy

   https://logistics.obana.africa/zoho/shipment-status?salesorder_id=${SALESORDER.SALESORDER_ID}&status=${SALESORDER.CF_SHIPMENT_STATUS}&secret=YOUR_WEBHOOK_SECRET

   One rule for In Transit, one for Fulfilled. Both use the same URL.

Zoho

Services: the custom-field route

Zoho refuses to put a service item in a package — error 36140 — and a shipment order cannot exist without a package. A marketplace whose catalogue is services therefore has no Zoho shipment record to move through statuses.

The sales order's own fields become the lifecycle. It is the same flow as above and the same endpoints; the difference is that Zoho holds no package, and cf_shipment_status is the only record of where the parcel is.

1. 1

   Create the same custom fields

   Identical to the goods route. cf_shipment_status is not optional here — it is the only place the lifecycle can live.

2. 2

   One rule per stage, all on cf_shipment_status

   Package Created

   Books the shipment. Points at /zoho/shipment-trigger.

   In Transit

   Moves it. Points at /zoho/shipment-status.

   Fulfilled

   Closes it. Points at /zoho/shipment-status.

3. 3

   Set the weight on your items

   Obana prices on weight. Put it in the item's package_details.weight in Zoho. Items with no weight ship at a default, which is how a heavy item quietly moves at a light item's price — the shipment records which lines were defaulted so you can find them.

Zoho

When nothing happens

Zoho reports a webhook as delivered as soon as Obana answers, and Obana answers immediately so the rule does not time out. A delivered webhook therefore does not mean a shipment was created. These two endpoints tell you what actually happened.

What Zoho actually sent

curl "https://logistics.obana.africa/zoho/recent?limit=10"

The last few requests Zoho made, with the parameters it sent and the answer it got. This is where an unresolved placeholder shows up — a rule that sends the literal text ${SALESORDER.SALESORDER_ID} looks fine in Zoho and does nothing here.

Run it and see the error

curl -X POST "https://logistics.obana.africa/zoho/shipment-trigger?salesorder_id=SALESORDER_ID&wait=1&secret=YOUR_WEBHOOK_SECRET"

wait=1 runs the booking inline and returns the reason it failed instead of the usual immediate acknowledgement. Use it on an order that did not come through: it names the cause — a missing phone, an address with no city, an item Zoho will not package — in one call.

The usual causes

No phone number

A courier cannot collect without one. Obana looks at the shipping address, then the order's contact person, then the customer record.

No address on the order

Obana falls back to the customer record, so the address may be on the customer rather than missing.

No route for that lane

Obana quotes lanes it runs. The error names the lane so it can be priced.

Cannot package a service

Error 36140. Zoho checks the item master, not the sales-order line. Use the services route.

Webhooks

Receive events

Instead of polling, let us tell you when something happens. Set a public https:// URL on your store in Stores & API; we POST a JSON event to it.

shipment.created

A shipment was created for your store.

shipment.updated

A shipment’s status changed.

webhook.test

Sent when you press Send test event. Its data has a message and your store instead of a shipment.

data.shipment has the same fields as a shipment in List your shipments (without destination).

Headers

Obana-Event

The event name, e.g. shipment.updated.

Obana-Delivery

The delivery id. It stays the same when we retry the same event — quote it when you contact support.

Obana-Signature

t=<unix seconds>,v1=<signature>. Always verify it — see Verify signatures.

Replies and retries

Answer with any 2xx within 8 seconds — reply first, then do the slow work. If we get anything else (or no answer), we retry after 1 minute, 5 minutes, 30 minutes, 2 hours and 6 hours, then stop.

Webhooks

Verify signatures

Every event is signed with your store’s webhook secret (starts with whsec_, shown in Stores & API). Checking the signature proves the event came from Obana and wasn’t changed.

1. 1

   Read the raw body

   Use the exact bytes you received. Parsing the JSON and re-encoding it changes the bytes and breaks the check.
2. 2

   Split the header

   From Obana-Signature take t (unix seconds) and v1 (hex signature).
3. 3

   Compute the expected signature

   HMAC-SHA256 of <t>.<raw body> with your webhook secret, as hex.
4. 4

   Compare safely

   Use a constant-time comparison, and reject events whose t is more than 5 minutes old so an old event can’t be replayed.

Launch

Going live checklist

Run through this before real orders flow through your integration.

• Your key lives in a server environment variable — not in browser, theme or app code, and not in git.
• Every create call sends your order_id, so a retry can never book twice.
• You send customer.id, so you can pull up any customer’s shipments.
• Checkout shows the price from /routes/quote and passes the chosen quote_option_id; you quote again after expires_at.
• Errors are handled: 400 messages reach your team, 429 waits for Retry-After, 5xx retries with backoff.
• Your webhook URL is https://, verifies Obana-Signature, replies 2xx within 8 seconds and skips repeated event ids.
• You sent a test event from the dashboard and saw it arrive.
• Customers get the tracking_url in their order confirmation.
• You know where to rotate the key or pause the store if a key ever leaks.

Launch

Support

Stuck, or need a route we don’t cover yet? Email us with your store name and, if it’s about a shipment, its reference or the Obana-Delivery id of the webhook.