A sample walkthrough — no real API calls, just a preview of connecting your first hub.
This is a simulated walkthrough — no real API key is generated and no real endpoints are called. It's here to show you the shape of the first step: generating a key scoped to your integration, then making one call to confirm the connection works.
You can only generate an API key from TINA, the VenHub dashboard —
grant it only the scopes this integration needs — here that's hubs:read,
inventory:read, inventory:write, orders:read
and controls:write.
{
"api_key": "vh_test_9f3k7d2a1e0c",
"scopes": ["hubs:read", "inventory:read", "inventory:write", "orders:read", "controls:write"],
"created_at": "2026-07-16T09:12:00Z"
}
Attach the key to a request and call GET /hubs — if it comes back
with your hub, you're connected.
curl -X GET \ "https://tina-api.venhub.com/api/v1/owners/hubs" \ --header "X-API-Key: vh_test_9f3k7d2a1e0c"
[
{
"id": 123,
"name": "Downtown Location",
"street_address_1": "123 Main St",
"street_address_2": null,
"city": "San Francisco",
"state": "CA",
"hub_status": "active"
}
]
Keep VenHub's record of what's on the shelf in sync with reality, then take the customer through checkout. Choose VenHub's Stripe integration and it's provided for you, or bring your own payment processor and build that integration yourself. Either way, once payment is verified, you let VenHub know and the transaction continues from there.
Pull the shelf state for the hub so your app knows what's actually available to sell.
curl -X GET \ "https://tina-api.venhub.com/api/v1/owners/hub_inventory/?hub_id=123" \ --header "X-API-Key: vh_test_9f3k7d2a1e0c"
[
{ "id": 456, "name": "Organic Apple", "quantity": 25, "original_price": 299, "discounted_price": 299, "cabinet": 1, "shelf": 2, "row": 3 }
]
A restock just came in. Push the new count so the hub's record matches the shelf.
curl -X PUT \ "https://tina-api.venhub.com/api/v1/owners/hubs/product/456/update_quantity" \ --header "X-API-Key: vh_test_9f3k7d2a1e0c" \ --header "Content-Type: application/json" \ --data '{"quantity": 40}'
{
"data": { "id": 456, "name": "Organic Apple", "quantity": 40, "original_price": 299, "discounted_price": 299, "cabinet": 1, "shelf": 2, "row": 3 }
}
A customer taps "Organic Apple — $2.99" in your app. Use VenHub's Stripe integration and it's provided for you — or bring your own payment processor and build that integration yourself. VenHub never touches card data or checks payment status itself: once the charge is verified, you let VenHub know so the transaction can continue.
open_bin call does, continuing the transaction.{
"payment_status": "succeeded",
"amount": 299,
"currency": "usd",
"item": "Organic Apple",
"charge_id": "ch_3P9kQ2A1e0c"
}
You've verified payment on your own side — this call is how you let VenHub know and continue the transaction. It sends a live command to the hardware, then verify VenHub logged the sale and adjusted inventory on its own.
Only call this once you've verified payment yourself — VenHub doesn't check payment status, so this is the "yes, it's paid for" signal that continues the transaction and sends a live command to the hardware.
curl -X POST \ "https://tina-api.venhub.com/api/v1/owners/controls/open_bin?bin=1&hub=123" \ --header "X-API-Key: vh_test_9f3k7d2a1e0c"
{
"success": true,
"status_code": 200,
"response_data": null
}
VenHub records the sale and decrements inventory automatically the moment the bin opens against a completed payment. Check the order history to see it land.
curl -X GET \ "https://tina-api.venhub.com/api/v1/owners/hubs/all_orders_paginated/?hub_id=123&limit=1" \ --header "X-API-Key: vh_test_9f3k7d2a1e0c"
{
"data": [
{
"id": 501,
"total_price_original": 299,
"total_price_discounted": 299,
"payment_status": "completed",
"created_at": "2026-07-16T09:14:22Z",
"order_items": [
{ "productUPC": "012345678901", "name": "Organic Apple", "qty": 1, "dropped": true, "qty_dropped": 1, "refunded_quantity": 0, "price": 299 }
]
}
],
"has_more": false
}
Connect once, keep inventory in sync, take payment through VenHub's Stripe integration or your own build, tell VenHub once it's verified, then dispense and let VenHub log the rest. Six calls, start to finish.
VenHub is exposed to third-party apps — a customer can run through the entire order workflow, from finding a hub to picking up their item, without ever leaving the retailer's own app. Here's what that flow looks like end to end.
This is what the retailer's own app does before the customer ever sees a product — geolocation and cart browsing happen entirely in the app; connecting the customer to VenHub, the hub lookup, and the inventory pull all go through VenHub.
Behind the scenes, VenHub automatically turns each of your app's customers into a VenHub member — no VH+ sign-up, no separate account for them to create. This is what lets them transact and use VenHub through your app.
Customer connected.
The app's own geolocation narrows down a candidate hub; VenHub confirms it exists and that this key can access it.
curl -X GET \ "https://tina-api.venhub.com/api/v1/owners/hubs" \ --header "X-API-Key: vh_test_9f3k7d2a1e0c"
[
{ "id": 123, "name": "Downtown Location", "street_address_1": "123 Main St", "city": "San Francisco", "state": "CA", "hub_status": "active" }
]
The app displays this directly to the customer, and calls it again every time the app is opened or refreshed — that's what keeps stock counts, out-of-stock items, and disabled products accurate. Once loaded, the customer browses and adds items to their cart entirely inside the app — no further VenHub call for that part.
curl -X GET \ "https://tina-api.venhub.com/api/v1/owners/hub_inventory/?hub_id=123" \ --header "X-API-Key: vh_test_9f3k7d2a1e0c"
[
{ "id": 456, "name": "Organic Apple", "quantity": 25, "original_price": 299, "discounted_price": 299, "cabinet": 1, "shelf": 2, "row": 3 }
]
If the app wants to surface deals while the customer browses, it can pull the hub's currently active promotions.
curl -X GET \ "https://tina-api.venhub.com/api/v1/deals/active/123" \ --header "X-API-Key: vh_test_9f3k7d2a1e0c"
[
{ "id": 1, "name": "Buy 2 Get 1 Free", "display_text": "Buy any 2 snacks, get 1 free!", "priority": 1 }
]
Checkout and payment happen entirely in the app — through the retailer's own processor or Stripe, never through VenHub. Once payment succeeds, the app sends the order to VenHub.
The customer pays in the app. VenHub never touches card data or checks payment status — this step happens entirely outside VenHub.
{
"payment_status": "succeeded",
"amount": 299,
"currency": "usd",
"item": "Organic Apple"
}
Once payment succeeds, the app hands the order to VenHub — hub ID, the retailer's
own user ID, and the product JSON — via request_place_order_to_vensmart.
{
"order_id": 501,
"hub_id": 123,
"status": "received"
}
VenHub routes the order to the correct hub internally once it's received — there's no separate operator call for that. When the customer arrives, the app checks the bin holding their item and opens it for pickup.
Confirm the bin holding the order is ready before opening it for the customer.
curl -X GET \ "https://tina-api.venhub.com/api/v1/owners/controls/get_bin_status?bin=1&hub=123" \ --header "X-API-Key: vh_test_9f3k7d2a1e0c"
{
"status": "ok",
"result": { "success": true, "status_code": 200, "response_data": null }
}
Customer's at the hub — open the specific bin holding their item so they can collect it.
curl -X POST \ "https://tina-api.venhub.com/api/v1/owners/controls/open_bin?bin=1&hub=123" \ --header "X-API-Key: vh_test_9f3k7d2a1e0c"
{
"success": true,
"status_code": 200,
"response_data": null
}
Find a hub, browse live inventory, pay in-app, hand the order to VenHub, then route and unlock for pickup — all inside the retailer's own app experience.