Building Custom Integrations

OpenBoxes exposes a REST API that you can use to build integrations with any external system. Whether you need to connect an ERP, a reporting tool, or an in-house application, the API gives you programmatic access to your supply chain data.

REST API Basics#

The OpenBoxes REST API is available at your instance URL under the /api/v1 path:

https://yourorg.openboxes.cloud/api/v1/

Authentication#

API requests authenticate with an API key sent in the X-API-Key header. Create a key in the portal under API → Manage API keys (Create API Key), then include it on every request:

curl -H "X-API-Key: $OB_API_KEY" \
  https://yourorg.openboxes.cloud/api/v1/products

Keys are scoped to a single tenant and carry configurable scopes (read, write, reporting, admin). See Authentication for the full details.

Tip: Create the key under a dedicated service account rather than a personal account. This avoids disruption when staff members leave the organization, since a key acts as its owner's OpenBoxes user.

Available API Endpoints#

The OpenBoxes API covers the core supply chain entities:

Endpoint Methods Description
/api/v1/products GET, POST List, search, and create products (updates go through /api/v1/generic/product/{id})
/api/v1/locations GET, POST, PUT Warehouses, depots, facilities
/api/v1/stockMovements GET, POST Inbound and outbound stock movements (line-item and status changes use the movement's sub-endpoints)
/api/v1/purchaseOrders GET Read purchase orders (they are created in the OpenBoxes UI)
/api/v1/putaways GET, POST List, read, and create putaways
/api/v1/generic/inventoryItem GET, POST, PUT, DELETE Inventory items (product + lot) via the generic API

User accounts are managed in the OpenBoxes UI and the Lift portal, not through the API.

For a complete reference, see the API documentation.

Webhook Events#

Lift webhooks push signed events to your systems in near real time, so you do not need to poll for changes. Register an endpoint under Webhooks in the portal and subscribe to the events you need. The event types delivering today:

  • order.created, order.approved, order.received, order.cancelled, order.updated
  • shipment.created, shipment.shipped
  • inventory.stock_adjustment
  • tenant.provisioned, tenant.suspended, tenant.reactivated

Stock-level changes, low-stock alerts, expiry warnings, and billing or data-import events are not available — poll the REST API for those. See Webhooks for payloads, signature verification, retry policy, and per-plan caps.

Middleware Options#

You do not need to write code from scratch to build integrations. Several middleware platforms can orchestrate data flows between OpenBoxes and other systems:

n8n (Self-hosted or Cloud)#

n8n is an open-source workflow automation tool. It supports HTTP request nodes that can call the OpenBoxes API and connect to hundreds of other services.

Example workflow: Every morning, query OpenBoxes for items below reorder point, then post a summary to a Slack channel.

Zapier#

Zapier's webhook triggers and HTTP action steps can connect OpenBoxes to 5,000+ apps without writing code.

Example workflow: When a new purchase order is created in OpenBoxes (detected via polling), create a corresponding record in Google Sheets for finance review.

Custom Scripts#

For straightforward integrations, a cron job running a Python or Node.js script is often the simplest approach:

import os
import requests

# Authenticate every request with the API key header
session = requests.Session()
session.headers.update({"X-API-Key": os.environ["OB_API_KEY"]})

# Fetch low-stock products
response = session.get("https://yourorg.openboxes.cloud/api/v1/products", params={
    "max": 100
})
products = response.json().get("data", [])

Best Practices#

  1. Use a service account — Do not embed personal credentials in integration scripts. Create a dedicated user with the minimum permissions needed.

  2. Respect rate limits — Limits are hourly and per account (all keys share them): Shared allows 1,000 requests per hour; Dedicated allows 25,000. Add backoff logic when you receive 429 responses. See Rate Limits.

  3. Handle errors gracefully — The API may return 500 errors during maintenance windows. Implement retry logic with exponential backoff.

  4. Log sync activity — Keep a record of what was synced and when. This makes troubleshooting much easier when discrepancies appear.

  5. Start with read-only — Test your integration with GET requests before enabling writes (POST/PUT). Verify the data looks correct before automating changes.

  6. Use pagination — List endpoints page with max and offset query parameters; there is no next link. Increase offset by max on each request and stop when a page comes back short or empty. Note that some endpoints (for example /api/v1/locations) ignore max and return everything.

Example Use Cases#

Use Case Data Flow Approach
Reorder alerts to email OpenBoxes --> Email Cron script polls inventory levels, sends email via SMTP
ERP financial sync OpenBoxes --> ERP n8n workflow pushes PO data to ERP API on a schedule
BI dashboard OpenBoxes --> Warehouse Script extracts stock data nightly into a data warehouse
Mobile barcode scanning Mobile app --> OpenBoxes App posts scanned data to the stock movement API
Supplier portal Supplier --> OpenBoxes External form submits advance shipping notices via API

Getting Help#

If you need assistance designing or building a custom integration:

  • Community forum at community.openboxes.com — Ask questions and share solutions with other implementers.
  • Enterprise customers can scope custom integration needs as part of an Enterprise agreement — contact sales@openboxes.cloud.