Orders API — VenHub Developer Docs

ℹ️

Third-party app integration via the VenCart API is in development and will be available shortly. If you're building or integrating a consumer-facing app and are interested in connecting to VenHub hubs, contact us.

ℹ️

The Orders API uses cursor-based pagination. Each page returns a next_cursor value. Pass that cursor as the cursor parameter in your next request. When has_more is false, you've reached the end.

GET /hubs/all_orders_paginated

Get paginated order history for a hub. Supports optional search filtering and cursor-based pagination for reliably paging through large datasets.

Version 1

URL https://tina-api.venhub.com/api/v1/owners/hubs/all_orders_paginated/

Auth API Key or Firebase

Required Scope orders:read

Example Request

cURL

curl -X GET \
  "https://tina-api.venhub.com/api/v1/owners/hubs/all_orders_paginated/?hub_id=123&limit=20&cursor=500" \
  --header "X-API-Key: vh_abc123..."

Query Parameters

Parameter	Type	Required	Default	Description
`hub_id`	Integer	Required	—	Hub ID to retrieve orders for
`limit`	Integer	Optional	`20`	Orders per page. Range: 1–100
`cursor`	Integer	Optional	`null`	Last order ID from the previous page. Omit for first page.
`search`	String	Optional	`null`	Filter orders by search term

Response

JSON — 200 OK

{
  "data": [
    {
      "id": 500,
      "user_id": 123,
      "total_price_original": 1299,
      "total_price_discounted": 999,
      "payment_status": "completed",
      "processing_status": 3,
      "created_at": "2026-02-05T14:30:00Z",
      "order_items": [
        {
          "productUPC": "012345678901",
          "name": "Organic Apple",
          "qty": 3,
          "dropped": true,
          "qty_dropped": 3,
          "refunded_quantity": 0,
          "price": 299,
          "image_url": "https://storage.example.com/products/apple.jpg"
        }
      ]
    }
  ],
  "next_cursor": 480,
  "has_more": true
}

Pagination Example

To fetch all orders, loop until has_more is false:

Pseudo-code

let cursor = null
let allOrders = []

do {
  const url = cursor
    ? `/all_orders_paginated/?hub_id=123&cursor=${cursor}`
    : "/all_orders_paginated/?hub_id=123"

  const res = await fetch(url, headers)
  allOrders.push(...res.data)
  cursor = res.next_cursor
} while (res.has_more)

Errors

Error Code	Description
hub_access_denied	API key does not have access to the specified hub
invalid_cursor	The provided cursor value is invalid or does not correspond to a known order

POST /orders/{order_id}/refund

Process a full refund for an entire order, sent back to the customer's bank account.

Version 1

URL https://tina-api.venhub.com/api/v1/owners/orders/{order_id}/refund

Auth API Key or Firebase

Required Scope orders:write

Example Request

cURL

curl -X POST \
  "https://tina-api.venhub.com/api/v1/owners/orders/500/refund" \
  --header "X-API-Key: vh_abc123..." \
  --header "Content-Type: application/json" \
  --data '{"destination": "Bank Account"}'

Parameters

Parameter	Type	Location	Required	Description
`order_id`	Integer	Path	Required	The order to refund
`destination`	String	Body	Optional	Refund destination. Currently only `"Bank Account"` — returned to the original payment method. A legacy alias `refund_destination` is also accepted for this field.
`amount`	Integer	Body	Optional	Specific amount to refund in cents. Defaults to the full remaining refundable amount.

Response

JSON — 200 OK

{
  "success": true,
  "order_id": 500,
  "new_status": "refunded"
}

Errors

Error Code	Description
order_not_found	The specified order does not exist or you lack access
already_refunded	Order has already been fully refunded
refund_failed	Payment processor rejected the refund — retry or contact support

POST /orders/{order_id}/items/{product_id}/refund

Refund a specific line item within an order. Use this to issue partial refunds when only one product in a multi-item order needs to be returned.

Version 1

URL https://tina-api.venhub.com/api/v1/owners/orders/{order_id}/items/{product_id}/refund

Auth API Key or Firebase

Required Scope orders:write

Example Request

cURL

curl -X POST \
  "https://tina-api.venhub.com/api/v1/owners/orders/500/items/456/refund" \
  --header "X-API-Key: vh_abc123..." \
  --header "Content-Type: application/json" \
  --data '{"destination": "Bank Account", "quantity": 1}'

Parameters

Parameter	Type	Location	Required	Description
`order_id`	Integer	Path	Required	The parent order ID
`product_id`	Integer	Path	Required	Product UPC to refund
`destination`	String	Body	Optional	Currently only `"Bank Account"`. A legacy alias `refund_destination` is also accepted.
`quantity`	Integer	Body	Optional	Number of items to refund. Default: `1`

Response

JSON — 200 OK

{
  "success": true,
  "new_status": "partially_refunded",
  "refunded_amount": 598,
  "updated_tax": 45
}

Errors

Error Code	Description
order_not_found	The specified order does not exist
product_not_in_order	Product UPC not found in the order
insufficient_quantity	Cannot refund more items than were purchased