← Back to EcomCentral
BILLBEE REST API v1

Billbee Setup Guide

Connect your Billbee account to EcomCentral using HTTP Basic Auth plus a dedicated API key.

About Billbee

Billbee (billbee.io) is a German e-commerce ERP and order management system used by thousands of German online sellers to centrally manage orders from multiple marketplaces and shop systems — including Amazon, eBay, Shopify, Otto, Kaufland, and many more. Billbee consolidates orders, handles invoicing, manages inventory, and syncs stock levels across all connected channels.

ℹ️ EcomCentral connects to Billbee's REST API v1 at https://app.billbee.io/api/v1. Every request requires both HTTP Basic Auth (username and password) and an X-Billbee-Api-Key header. API access must be enabled in your Billbee account settings before any requests will succeed.

Prerequisites

Enabling API Access & Generating a Key

  1. Log in to your Billbee account at app.billbee.io
  2. Navigate to Einstellungen (Settings) → API
  3. Toggle API aktivieren (Activate API) to on if it is not already enabled
  4. Switch to the API-Keys tab
  5. Click Neuen API-Key erstellen (Create new API key) and give it a label such as "EcomCentral"
  6. Copy the generated key — it is shown only once. Store it securely
  7. In EcomCentral, add a new Billbee connection and fill in all three credential fields
  8. Click ⚡ Test to verify the connection
⚠️ If API access is not enabled, all requests will return 401 Unauthorized regardless of whether the username, password, and key are correct. Enable the API toggle first.

Credentials Reference

KeyRequiredDescriptionExample
username Required Your Billbee login email address (used for HTTP Basic Auth) seller@example.com
password Required Your Billbee account password (used for HTTP Basic Auth) ••••••••
api_key Required API key from Billbee Settings → API → API-Keys tab a1b2c3d4-e5f6-…
✅ Alternative key names accepted: user or email for the username; apiKey for the API key.
⚠️ Billbee requires BOTH headers on every request — HTTP Basic Auth (Authorization: Basic …) carrying your username and password, and the X-Billbee-Api-Key header carrying your API key. Missing either header results in a 401 or 403 error.

API Endpoints Used

OperationMethodEndpoint
Test connectionGET/orders?page=1&pageSize=1
List ordersGET/orders?page=P&pageSize=N
Order detailGET/orders/{id}
Add shipment / trackingPOST/orders/{id}/shipment with {"ShippingId":"…","OrderStateId":5,"ChangeStateToSend":true}
List productsGET/products?page=P&pageSize=N
Product detailGET/products/{id}
Update stockPATCH/products/{id}/stockchange with {"StockId":0,"NewQuantity":N,"Reason":"…"}
ℹ️ All responses are wrapped in {"Data":…,"ErrorCode":0,"ErrorMessage":null}. ErrorCode 0 means success; any non-zero code signals an error — the message is in ErrorMessage. List responses nest the item array and paging under Data.Data and Data.Paging respectively.

Order Status Codes

Billbee uses numeric status codes. EcomCentral maps them to labels and colour-coded badges. Note: order IDs in Billbee are the internal Billbee IDs — ExternalId contains the original marketplace order number (e.g. Amazon or eBay order reference).

CodeLabelBadge colour
1PendingBlue
2ConfirmedBlue
3ProcessingBlue
4Ready to ShipBlue
5ShippedGreen
6CancelledRed
7ClosedGreen
8ArchivedAmber
9ReturnAmber
10AbortedRed
12CompletedGreen
13RevokedRed
14Partially CompletedGreen

Supported Features

FeatureSupportedNotes
View orders (paginated)✅Billbee ID, marketplace reference (ExternalId), date, status, total + currency
View order detail✅Buyer info, invoice & shipping addresses, line items, current tracking & ship date
Add tracking / shipment✅POST /orders/{id}/shipment — sets ShippingId and marks order as Shipped (status 5)
View products (paginated)✅Product ID, SKU, EAN, multilingual title, price, stock quantity
View product detail✅Full product with multilingual description (HTML stripped), EAN, category, weight, image
Update stock quantity✅PATCH /products/{id}/stockchange — targets StockId 0 (default location); syncs to connected channels
Test connection✅GET /orders?pageSize=1 — success confirms both Basic Auth and API key are valid
ℹ️ Stock updates use the internal product ID (shown in the product list), not the SKU. Billbee's central inventory stock change then syncs to all connected channels (Amazon, eBay, Shopify, etc.) automatically.

Troubleshooting

401 Unauthorized

The username (email) or password is wrong, or the API is not enabled in Billbee Settings → API. Check both the API aktivieren toggle and your login credentials. Also confirm the email address matches the Billbee login exactly.

403 Forbidden

The X-Billbee-Api-Key header is missing or the key is incorrect. Regenerate the API key in Billbee Settings → API → API-Keys and update the connection in EcomCentral.

ErrorCode non-zero in response

All Billbee API responses include {"ErrorCode": N, "ErrorMessage": "…"}. A non-zero ErrorCode means the request was understood but Billbee rejected it — read ErrorMessage for the exact reason (e.g. order not found, stock location invalid, etc.).

Rate limiting

Billbee enforces a rate limit of approximately 60 requests per minute on the free and entry-level tiers. If you exceed it, requests return HTTP 429. EcomCentral fetches data on demand (no background polling), so rate limits are rarely reached in normal use.

🔧 Quick sanity check — in your browser's address bar visit https://app.billbee.io/api/v1/orders?page=1&pageSize=1 with Basic Auth credentials. A 200 response with "ErrorCode":0 means everything is working. A 401 or 403 points to a credential or API-key problem.