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. The scopes you pick (read, write, reporting, admin) are recorded on the key and are not yet enforced on the OpenBoxes data API. There, what a key can do is governed by the OpenBoxes permissions of the user who created it. One exception is live: managing webhooks with an API key requires the admin scope, and a key without it is refused with 403. See Authentication for the full details.

For reporting, the Reporting API on https://api.openboxes.cloud returns the Reports page's figures (stock on hand, stock value, expiring lots, open purchase orders and activity) as flat datasets in JSON or CSV, from our daily check. It is often a simpler source for a dashboard or a data warehouse than paging the data API, and it has its own allowance of 600 requests an hour. Give its key the reporting scope.

Tip: Only the account owner can create API keys, and on the data API a key acts as the OpenBoxes user of the person who created it. Create one key per integration, give it the narrowest scopes that integration needs (reporting for a reporting tool), set an expiry where you can, and revoke the key when the integration is retired. One key per integration means revoking one never breaks another.

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 Warehouses, depots, facilities (created and edited in the OpenBoxes UI)
/api/v1/stockMovements GET, POST Inbound and outbound stock movements; line items go to /{id}/updateItems and status to /{id}/status
/api/v1/purchaseOrders GET Read purchase orders (they are created, edited and received in the OpenBoxes UI)
/api/v1/putaways GET, POST Putaways; both take location.id. Build a POST from the entries the GET returns
/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. This table is a summary of the core entities, not the full list. The API documentation is authoritative, and anything it does not document is something we have not verified on a hosted instance.

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 (or with an API key that carries the admin scope, against https://api.openboxes.cloud/api/v1/webhooks; see Webhooks) and subscribe to the events you need. The event types delivering today:

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

The events from the OpenBoxes instance (orders, shipments, stock adjustments) are delivered on every plan: Shared, Dedicated and Enterprise.

Stock-level changes, low-stock alerts, expiry warnings, and billing or data-import events are not available; poll the REST API for those. A daily below-minimum / nearing-expiry stock alert by email is available today, opt-in, included on every plan, on Shared and Dedicated instances alike: once a day, shortly after 7am in your instance's timezone, covering only products that have a minimum level set at that location, and always stating the true total when it shows fewer rows than exist. PagerDuty, Slack and Microsoft Teams destinations are available too, for stock-outs only among the stock alerts (they can also carry temperature alerts, in beta): an incident opens in PagerDuty, or a message is posted to a Slack channel or a Teams channel, when a product with a minimum set runs out of stock at a location, and below-minimum and nearing-expiry never go to any of them as alerts (a Slack or Teams channel ticked for the weekly summary gets only their counts, once a week). See PagerDuty alerts, Slack alerts and Microsoft Teams alerts. A weekly summary by email is available today too, opt-in for each person; see Stock alerts. Meanwhile, 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. Each of these talks to the API you already have. There is no OpenBoxes Lift app, node or connector published for any of them today.

Native Zapier and n8n connectors are coming soon: we are building them, they are not available yet, and we do not publish a date. Register interest under Apps in the Integrations tab of your customer portal.

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. A daily email alert is built in (see Stock alerts), but it compares quantity on hand against the minimum level only; reorder points are not used by it. Build this workflow if you need reorder-point logic, or if you want the summary in Slack, which we do not send yet.

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. One key per integration: Do not embed personal credentials in integration scripts. The account owner creates a separate API key for each integration, with the narrowest scopes it needs, and keeps it in a secrets store rather than in the script.

  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: During a maintenance window the API answers 503 with a Retry-After header: wait that long and retry. A 504 is different: check whether the write landed before resubmitting it. See Maintenance Windows for what each response means.

  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
Below-minimum alerts to email OpenBoxes --> Email Built in: turn on Stock alerts in the portal under Integrations > Destinations. Minimum levels only; reorder points are not used
Reorder-point alerts to email OpenBoxes --> Email Not built in: a scheduled script or n8n workflow that reads reorder levels from the API
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 Your own app --> OpenBoxes Your app posts scanned data to the stock movement API. Our own handheld scanning app is in beta: Look up, receiving, picking and shipping on every plan
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 discuss custom integration needs as part of an Enterprise agreement; contact sales@openboxes.cloud. Custom integration work is not included in any plan today; we will say honestly whether we can help and what it would take.

Guides

From the blog