Build the future of hospitality with BarBud.
A developer-first platform for managing high-volume bars. Sync inventory in real-time, automate shift reconciliation, and build custom loyalty experiences with a strongly-typed REST API.
Overview
The BarBud API provides a RESTful interface to the core operations engine of the BarBud platform. Everything revolves around the concept of a Tenant (a specific bar/venue).
At its core, the API is tenant-scoped. Your API key identifies your specific bar (or "Tenant"), ensuring that all data—from inventory items to customer records—is strictly isolated and secure. We adhere to RESTful principles, using standard HTTP verbs (GET, POST, PATCH, DELETE) and predictable JSON resource structures.
Developer-First Design
We prioritize developer experience. That means consistent error envelopes, detailed validation messages, and ISO 8601 timestamps throughout. Our specification fully complies with OpenAPI 3.1.1 standards.
System Model
- InventoryThe source of truth for products, stock, and pricing.
- Tabs & SalesLifecycle from open check to finalized revenue.
- PeopleBartenders, Customers, and Loyalty profiles.
Beginner's Guide
New to APIs? No problem. Think of the API as a universal remote control for your bar. Instead of clicking buttons on a screen, you send typed instructions that BarBud understands and executes.
What is an API Key?
It's a special password for your code. When you log in to the dashboard, you use an email and password. When your code talks to BarBud, it uses an API Key.
Keep it safe: Anyone with this key can manage your bar. Don't share it in public forums or client-side code.
How do I use it?
You include the key in a "Header" with every message you send. It looks like this:
Your First "Hello World"
Let's fetch your inventory. We recommend using a tool like Insomnia or Postman to test requests before writing code.
- Open your API Client (Postman/Insomnia).
- Create a new GET request.
- Enter the URL:
https://barbud.net/api/v1/inventory/items - Go to the Auth tab, select Bearer Token, and paste your API Key.
- Click Send. You should see a JSON list of your drinks!
Authentication
Security is paramount. Access to the API is controlled via Bearer Tokens. You generate these long-lived API keys in your dashboard settings under the "Developer" tab.
Each key allows full administrative access to your tenant's data. Treat these keys like passwords. Do not commit them to version control, and never include them in client-side code (like React apps or mobile binaries) where they can be extracted by users. All API requests should be proxied through your own secure backend server.
Implementation Details
Authorization Header
Pass your key in the standard HTTP Authorization header.
headers: { 'Authorization': 'Bearer sk_live_<userId>.<keyId>.<secret>' }Rate Limiting
We protect platform stability with a standard limit of 1,000 requests per hour.
X-RateLimit-Remaining: 998
X-RateLimit-Reset: 1698765432
API Standards
Consistent patterns make integration easier. Here's what you can expect across all our endpoints.
Pagination & Filtering
List endpoints support pagination via the limit parameter (default: 50, max: 100).
Time & Dates
All timestamps are returned as Unix Epoch milliseconds (e.g., 1698765432000) or ISO 8601 strings in UTC.
Idempotency
Safely retry requests without side effects. Use the Idempotency-Key header for sensitive POST/PATCH operations.
Error Handling
Errors happen. We try to be helpful when they do. All error responses follow a consistent JSON envelope, allowing you to programmatically handle failures in your UI.
400 Bad RequestInvalid body or parameters401 UnauthorizedInvalid API key403 ForbiddenInsufficient permissions404 Not FoundResource doesn't exist429 Too Many RequestsRate limit exceededError Object
Every non-200 response will look like this:
{
"data": null,
"error": {
"code": "RATE_LIMIT_EXCEEDED",
"message": "You have exceeded the request limit for this hour.",
"details": {
"retryAfter": 3600
}
}
}Quickstart
Let's make your first request. We'll connect to the API and fetch your current inventory list. This confirms your API key is working and you can parse the response format.
Base URL
https://barbud.net/api/v1Fetch Inventory
const fetch = require('node-fetch');
async function getInventory() {
const response = await fetch('https://barbud.net/api/v1/inventory/items', {
headers: {
'Authorization': 'Bearer sk_live_<userId>.<keyId>.<secret>',
'Content-Type': 'application/json'
}
});
if (!response.ok) throw new Error(`Error: ${response.status}`);
const { data } = await response.json();
console.log(`Found ${data.length} items`);
}
getInventory();Inventory
Inventory is the heart of BarBud. These endpoints allow you to manage your product catalog programmatically. This is crucial for syncing your POS with external e-commerce platforms, supplier databases, or digital menus.
Changes made here—like updating a price or stock level—propagate instantly to all connected devices in your bar. Use the category field to organize items effectively.
/inventory/itemsReturns a complete list of all active drink items in the system.
Pro Tip: Caching
Inventory data changes relatively infrequently. We recommend fetching this list on startup and then using Webhooks (`inventory.item_updated`) to keep your local state fresh, rather than polling this endpoint continuously.
/inventory/itemsCreates a new inventory item. Useful for bulk importing products from a CSV or supplier feed.
Request Body
await fetch('https://barbud.net/api/v1/inventory/items', {
method: 'POST',
headers: { 'Authorization': 'Bearer sk_live_<userId>.<keyId>.<secret>', 'Content-Type': 'application/json' },
body: JSON.stringify({ name: "Mojito", category: "Cocktails", price: 14.00, stock: 100 })
});Response
{
"data": {
"id": "item_123",
"name": "Mojito",
...
},
"error": null
}Tabs & Sales
In BarBud, a Tab is a mutable container for a customer's order. It stays "Open" while items are being added. Once payment is collected, the Tab is "Closed", and it transforms into a Sale Record.
Sale Records are immutable financial history. You query them to generate reports, calculate revenue, or analyze trends. This separation ensures that your historical data remains consistent even if you change your menu later.
Tabs API
Manage live orders.
{ "name": "Table 12" }{ "data": { "id": "tab_123", ... } }Atomic operation. Converts tab items to sales records.
{ "paymentMethod": "card" }Sales API
Access historical data.
Filter by date range. Sorted by newest first.
GET /sales?startDate=1698765432000&limit=10Shifts
Shifts provide the context for all sales. They track when a bartender started working, how much cash was in the drawer, and when they finished. This is critical for Cash Reconciliation and staff accountability.
Our API supports "Blind Balancing", meaning you can end a shift programmatically and submit the counted cash amount. The system will then calculate the variance (over/short) against the recorded sales.
{
"bartenderIds": ["user_123"],
"startCash": 200.00
}{
"endCash": 540.50
}Customers & Loyalty
BarBud's CRM features allow you to track customer spending and manage a loyalty program. The API exposes "Headless Loyalty" capabilities—meaning you can build your own customer-facing mobile app that awards points or redeems credit without using our UI.
Loyalty balances are updated transactionally. You can safely add or subtract credit knowing that an audit log is created for every adjustment.
POST /customers/:id/loyalty
Adjust a customer's loyalty balance transactionally.
Request Body
{
"action": "add", // "subtract", "set"
"amount": 50,
"notes": "Bonus points from app"
}Response
{
"data": {
"balance": 150
},
"error": null
}Webhooks
Polling APIs for changes is inefficient and slow. Webhooks allow your application to react immediately when something happens in BarBud. This "push" model reduces server load and latency.
Common use cases include: triggering a "Thank You" email when a tab.closed event fires, or syncing inventory levels to your website instantly on inventory.item_updated.
Verifying Signatures
Security is critical for webhooks. You must verify that the request actually came from BarBud. We sign every payload using a shared secret and HMAC-SHA256.
const crypto = require('crypto');
function verifyWebhook(secret, payload, signature) {
const hash = crypto
.createHmac('sha256', secret)
.update(payload)
.digest('hex');
return hash === signature;
}Supported Events
Analytics
Building a custom dashboard for investors or owners? The Analytics API exposes pre-aggregated metrics so you don't have to crunch raw sales data yourself.
We calculate totals, time-series distributions, and category breakdowns on the server. This ensures that the numbers you see in your custom app exactly match the numbers in the BarBud dashboard.
Summary
/analytics/summaryTotal revenue, units sold.
{ "totalRevenue": 15420.50, "totalSold": 1205 }Top Items
/analytics/top-itemsBest sellers by volume.
?limit=5&startDate=...Assistant API
BarBud includes a powerful AI assistant that understands your bar's specific data context. This endpoint allows you to pass natural language queries programmatically.
For example, you could build a Slack bot that allows managers to ask "How are sales tonight?" without logging into the dashboard.
POST /assistant/query
{
"query": "Who sold the most Rum?"
}{
"response": "Alex sold 12 Rum cocktails...",
"sources": ["sales_report_today"]
}© 2024 BarBud. All rights reserved.