Orders API

Uploading and managing orders in Big Block for structured fulfillment tracking.

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.

Info

Using the Orders API is entirely optional. The platform is fully functional without it — you can light devices directly without associating them with Orders, Shipments, or Items.

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"
}

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()

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()

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()

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)

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)

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)

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)

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