Orders API

Manage structured fulfillment in Big Block and give pickers a prebuilt interface on an Android handheld scanner.

Overview

Orders provide a structured way to manage and track shipments, ensuring that items are accurately accounted for from creation to fulfillment. By associating shipments with an order number, businesses can streamline logistics, improve traceability, and reduce errors in inventory handling.

Recommended for order-based picking

If your work begins with orders, shipments, and items, start with the Orders API. It works with Voodoo's prebuilt Android picking app, which can turn a potentially inexpensive handheld scanner into the picker's interface without requiring you to build a GUI from scratch. Direct device commands remain useful for ad hoc lights and custom workflows.

Android Picking App

Upload work through the Orders API, then use the Android app's ready-made picking interface on a handheld scanner. This provides a practical path from order data to an operator workflow while keeping Big Block responsible for the order and fulfillment state.

Start with the introduction, then watch the detailed walkthrough to see more of the picker experience.

Android App for Picking — Introduction

Voodoo Robotics CEO Trevor Blumenau introduces the Android app for picking with Big Block.

Watch on YouTube

Android App for Picking — Details

See more of the Android picking app's features and prebuilt operator interface.

Watch on YouTube

Endpoint Reference

Base URL: https://your-server/api/

Method	Endpoint	Description
GET	`/orders/`	List all orders
POST	`/orders/`	Create a new order (with or without shipments)
GET	`/orders/{order_number}/`	Retrieve a specific order by order number
POST	`/orders/{order_number}/launch/`	Turn on all devices associated with an order
POST	`/orders/{order_number}/abort/`	Turn off all devices associated with an order
DELETE	`/orders/{order_number}/`	Delete an order by order number

OpenAPI Specification

OAS 3.0

This API is fully OpenAPI Specification (OAS 3.0) compliant. The machine-readable spec unlocks powerful integrations:

Postman: use Import → Link and paste the spec URL — all endpoints, parameters, and example bodies load automatically.
AI coding tools (GitHub Copilot, Cursor, ChatGPT, etc.): paste the spec URL and they generate accurate, working client code with correct field names and auth headers.
SDK generators: produce typed clients in any language with tools like openapi-generator or fern.

Spec URL:

https://bblock-demo.voodoorobotics.com/orders/openapi.json

Setup

import requests
import json

BASE_URL = "http://localhost:8000/api"

headers = {
    "API_KEY": "YOUR_API_KEY_HERE",
    "Content-Type": "application/json"
}

# Set your base URL and API key
BASE_URL="http://localhost:8000/api"
API_KEY="YOUR_API_KEY_HERE"

1) List All Orders

def list_orders():
    url = f"{BASE_URL}/orders/"
    response = requests.get(url, headers=headers)
    if response.status_code == 200:
        orders = response.json()
        print("List of Orders:", json.dumps(orders, indent=2))
    else:
        print("Failed to list orders. Status code:", response.status_code)
        print("Response:", response.text)

list_orders()

curl -X GET "$BASE_URL/orders/" \
  -H "API_KEY: $API_KEY"

2) Create a New Order

2a) With Shipments

If you provide shipments data, each shipment can contain an array of items. For each item, ordered_quantity is required.quantity_fulfilled defaults to 0.description, UPC, and warehouse_location can be omitted. Provide at least one of name, SKU, or UPC. Use deviceid to associate a device, or set it to null.

def create_order_with_shipments():
    url = f"{BASE_URL}/orders/"
    new_order = {
        "order_number": "SO-12345",
        "shipments": [
            {
                "shipment_number": "SHIP-001",
                "items": [
                    {
                        "name": "Widget A",
                        "description": "A sample widget",
                        "SKU": "SKU-A",
                        "UPC": "UPC-A",
                        "ordered_quantity": 10,
                        "quantity_fulfilled": 0,
                        "warehouse_location": "Aisle 3",
                        "deviceid": None
                    },
                    {
                        "name": "Widget B",
                        "description": "Another sample widget",
                        "SKU": "SKU-B",
                        "UPC": "UPC-B",
                        "ordered_quantity": 5,
                        "quantity_fulfilled": 0,
                        "warehouse_location": "Aisle 4",
                        "deviceid": None
                    }
                ]
            }
        ]
    }
    response = requests.post(url, headers=headers, data=json.dumps(new_order))
    if response.status_code == 201:
        created_order = response.json()
        print("Created Order:", json.dumps(created_order, indent=2))
        return created_order
    else:
        print("Failed to create order. Status code:", response.status_code)
        return None

created_order = create_order_with_shipments()

curl -X POST "$BASE_URL/orders/" \
  -H "API_KEY: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "order_number": "SO-12345",
    "shipments": [{
      "shipment_number": "SHIP-001",
      "items": [
        {
          "name": "Widget A",
          "description": "A sample widget",
          "SKU": "SKU-A",
          "UPC": "UPC-A",
          "ordered_quantity": 10,
          "quantity_fulfilled": 0,
          "warehouse_location": "Aisle 3",
          "deviceid": null
        },
        {
          "name": "Widget B",
          "description": "Another sample widget",
          "SKU": "SKU-B",
          "UPC": "UPC-B",
          "ordered_quantity": 5,
          "quantity_fulfilled": 0,
          "warehouse_location": "Aisle 4",
          "deviceid": null
        }
      ]
    }]
  }'

2b) Without Explicit Shipments

If you omit shipments but provideitems, the server automatically creates a "dummy" shipment with the shipment_number set to the order number.

def create_order_with_items_only():
    url = f"{BASE_URL}/orders/"
    new_order = {
        "order_number": "SO-6789",
        "items": [
            {
                "name": "Widget C",
                "description": "Single widget example",
                "SKU": "SKU-C",
                "UPC": "UPC-C",
                "ordered_quantity": 2,
                "quantity_fulfilled": 0,
                "warehouse_location": "Aisle 1",
                "deviceid": None
            }
        ]
    }
    response = requests.post(url, headers=headers, data=json.dumps(new_order))
    if response.status_code == 201:
        created_order = response.json()
        print("Created Order:", json.dumps(created_order, indent=2))
        return created_order
    else:
        print("Failed to create order. Status code:", response.status_code)
        return None

created_order_items_only = create_order_with_items_only()

curl -X POST "$BASE_URL/orders/" \
  -H "API_KEY: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "order_number": "SO-6789",
    "items": [{
      "name": "Widget C",
      "description": "Single widget example",
      "SKU": "SKU-C",
      "UPC": "UPC-C",
      "ordered_quantity": 2,
      "quantity_fulfilled": 0,
      "warehouse_location": "Aisle 1",
      "deviceid": null
    }]
  }'

3) Retrieve a Single Order

Orders may include an internal id in responses, but order detail and delete operations are addressed by order_number.

def get_order(order_number):
    url = f"{BASE_URL}/orders/{order_number}/"
    response = requests.get(url, headers=headers)
    if response.status_code == 200:
        order_data = response.json()
        print(f"Order {order_number} details:", json.dumps(order_data, indent=2))
        return order_data
    else:
        print(f"Failed to retrieve order {order_number}. Status code:", response.status_code)
        return None

# Usage:
if created_order:
    order_number = created_order["order_number"]
    get_order(order_number)

curl -X GET "$BASE_URL/orders/SO-12345/" \
  -H "API_KEY: $API_KEY"

4) Launch an Order

Launching an order sends commands to all devices associated with that order.

def launch_order(order_number):
    url = f"{BASE_URL}/orders/{order_number}/launch/"
    response = requests.post(url, headers=headers)
    if response.status_code == 200:
        print(f"Order {order_number} launched successfully.")
        print("Response:", json.dumps(response.json(), indent=2))
    else:
        print(f"Failed to launch order {order_number}. Status code:", response.status_code)
        print("Response:", response.text)

# Usage:
if created_order:
    order_number = created_order["order_number"]
    launch_order(order_number)

curl -X POST "$BASE_URL/orders/SO-12345/launch/" \
  -H "API_KEY: $API_KEY"

5) Abort an Order

Aborting an order turns off all devices associated with that order.

def abort_order(order_number):
    url = f"{BASE_URL}/orders/{order_number}/abort/"
    response = requests.post(url, headers=headers)
    if response.status_code == 200:
        print(f"Order {order_number} aborted successfully.")
        print("Response:", json.dumps(response.json(), indent=2))
    else:
        print(f"Failed to abort order {order_number}. Status code:", response.status_code)
        print("Response:", response.text)

# Usage:
if created_order:
    order_number = created_order["order_number"]
    abort_order(order_number)

curl -X POST "$BASE_URL/orders/SO-12345/abort/" \
  -H "API_KEY: $API_KEY"

6) Delete an Order

def delete_order(order_number):
    url = f"{BASE_URL}/orders/{order_number}/"
    response = requests.delete(url, headers=headers)
    if response.status_code == 204:
        print(f"Order {order_number} deleted successfully.")
    else:
        print(f"Failed to delete order {order_number}. Status code:", response.status_code)

# Usage:
if created_order:
    order_number = created_order["order_number"]
    delete_order(order_number)

curl -X DELETE "$BASE_URL/orders/SO-12345/" \
  -H "API_KEY: $API_KEY"

Order Data Model

Orders follow a hierarchical structure:

Order

├─ order_number (external lookup key)

├─ id (internal server-generated identifier)

└─ shipments[]

Shipment

├─ shipment_number (string)

└─ items[]

Item

├─ name (string)

├─ description (string)

├─ SKU (string)

├─ UPC (string)

├─ ordered_quantity (int)

├─ quantity_fulfilled (int)

├─ warehouse_location (string)

└─ deviceid (string | null)

Sequence API

Create and manage step-based pick sequences

REST API Overview

Core device endpoints and examples

Location Alias API

Device location management approaches

Authentication

Auth methods and security