canonical: https://jentic.com/apis/billbee.io/billbee

# Billbee API

Billbee is a German multi-channel e-commerce back office that consolidates orders, shipments, products, and customers from marketplaces and webshops into a single workflow. The API exposes orders across connected shop accounts, lets agents create invoices and delivery notes, transition order states, attach shipments, and patch product and stock data. Customer records, customer addresses, events, layouts, cloud storage targets, and webhook subscriptions round out the surface so an agent can run end-to-end fulfillment without opening the Billbee web app.

## For AI agents

Read multi-channel orders, create invoices and shipments, update product stock, and manage Billbee customers and webhooks for an e-commerce back office.

## Scope

Does not handle storefront rendering, payment processing, or carrier rate-shopping - use for multi-channel order management, invoicing, and shipment booking only.

## Capabilities

- Read and patch orders across connected shop accounts and transition order states
- Generate invoices and delivery notes for orders and attach shipment records with tracking numbers
- Manage products, custom fields, categories, and stock counts including image uploads
- Maintain customers and customer addresses, and look up a customer's order history
- Subscribe webhooks to order, shipment, and product events for real-time agent triggers

## Use cases

### Multi-channel order processing

Pull new orders from every connected shop into one queue, generate the invoice and delivery note, and transition the order state once the shipment is booked. The Billbee API exposes GET `/api/v1/orders` for the queue, POST `/api/v1/orders/CreateInvoice/{id}` and POST `/api/v1/orders/CreateDeliveryNote/{id}` for documents, and PUT `/api/v1/orders/{id}/orderstate` for the state change. A small operations team can process hundreds of marketplace orders a day from a single agent loop.

Example prompt: Fetch open orders via GET `/api/v1/orders`, then for each call POST `/api/v1/orders/CreateInvoice/{id}` and PUT `/api/v1/orders/{id}/orderstate` to mark them shipped

### Inventory and product catalog sync

Keep the Billbee product catalog and stock levels in step with an upstream PIM or ERP. POST `/api/v1/products` creates new SKUs, POST `/api/v1/products/{id}/stockcode` (and related stock endpoints) update available units, and POST `/api/v1/products/images` uploads imagery. This avoids the drift that breaks marketplace listings when stock counts go stale.

Example prompt: Create a product with SKU 'WIDGET-001' via POST `/api/v1/products`, then patch its stock to 50 and verify with GET `/api/v1/products/{id}`

### Customer record and history lookup

Maintain customer master records and pull a buyer's full order history for support workflows. The API exposes POST `/api/v1/customers` to create, PUT `/api/v1/customers/{id}` to update, and GET `/api/v1/customers/{id}/orders` to retrieve every order placed by that customer. Useful when a support agent needs context on a returning buyer in seconds.

Example prompt: Look up customer ID 12345 via GET `/api/v1/customers/{id}`, then call GET `/api/v1/customers/{id}/orders` and return the last five orders

### Event-driven shipping workflow

Subscribe a webhook so an agent reacts the moment a new order or shipment event fires in Billbee. The API exposes GET `/api/v1/events` to enumerate event types and the webhooks endpoints to register a callback URL. The agent can then call POST `/api/v1/orders/{id}/shipment` to attach a label and tracking number as soon as the order is ready.

Example prompt: Register a webhook for the order.created event, then on receipt call POST `/api/v1/orders/{id}/shipment` with the carrier and tracking number

### Agent-driven Billbee operations via Jentic

An AI agent uses Jentic to discover Billbee operations from intents like 'create an invoice for an order' or 'update product stock'. Jentic returns the matching operation, loads its schema, and executes with credentials held in the vault. The agent can run a full fulfillment loop without ever holding the X-Billbee-Api-Key header value directly.

Example prompt: Search Jentic for 'create an invoice for an order in billbee', load the CreateInvoice schema, and execute it for order ID 778899

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | `/api/v1/orders` | List orders across connected shops |
| POST | `/api/v1/orders/CreateInvoice/{id}` | Create an invoice for an order |
| POST | `/api/v1/orders/CreateDeliveryNote/{id}` | Create a delivery note for an order |
| PUT | `/api/v1/orders/{id}/orderstate` | Transition the order state |
| POST | `/api/v1/orders/{id}/shipment` | Attach a shipment to an order |
| GET | `/api/v1/products` | List products in the catalog |
| POST | `/api/v1/customers` | Create a customer record |
| GET | `/api/v1/customers/{id}/orders` | Get a customer's order history |

## Key resources

- **Orders** — Read, patch, and transition orders across all connected shop accounts
- **Products** — Manage products, categories, custom fields, and stock counts
- **Customers** — Create and update customer records and look up their order history
- **CustomerAddresses** — Maintain customer shipping and billing addresses
- **Shipments** — Attach shipments and tracking numbers to orders
- **Webhooks** — Subscribe to order, shipment, and product events
- **ShopAccounts** — Inspect connected marketplace and webshop accounts
- **CloudStorage** — Manage cloud-storage targets for invoices and delivery notes

## Why Jentic

- **Setup:** Wiring the Billbee API by hand means sending its Billbee application-key header plus HTTP Basic username and password on every call and building each order, product, and customer path yourself. Through Jentic you install once, import Billbee from the API Directory, store both credentials once, and your agent calls it.
- **Permission scoping:** Billbee puts the order and customer id in the URL path (`/orders/{id}/shipment`, `/customers/{id}/orders`), so a rule can pin your agent to one order or one customer. You choose the operations it may call, so changing order state or booking a shipment is not included unless you add them.
- **Credential handling:** Your Billbee API key and Basic username and password are stored once, encrypted, by your own Jentic One instance and injected at execution time. They never enter the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'create an invoice for an order' or 'list open orders', and Jentic returns the matching Billbee operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **Shopify** — Shopify is the storefront platform; Billbee aggregates orders from many shops including Shopify.
- **ShipStation** — ShipStation is a shipping-focused order manager popular in North America.
- **Easyship** — Easyship adds carrier-rate and label generation alongside Billbee's order management.

## FAQ

### What authentication does the Billbee API use?

Billbee requires two credentials on every request: an API key sent in the X-Billbee-Api-Key header that identifies your application, plus a basic-auth header carrying the Billbee username and an API password. Through Jentic both credentials sit encrypted in the vault and the agent only ever holds a scoped reference.

### Can I create invoices and delivery notes with this API?

Yes. Call POST `/api/v1/orders/CreateInvoice/{id}` to generate an invoice for an order and POST `/api/v1/orders/CreateDeliveryNote/{id}` to generate the delivery note. The endpoints return a reference to the document and Billbee can also push it to a configured cloud-storage target.

### What rate limits apply to the Billbee API?

Billbee enforces 50 calls per second per API key, 10 calls per second per API key plus user combination, and a per-endpoint cap of 2 requests per second per API key plus user. Exceeding the limit returns HTTP 429 with a Retry-After header indicating the wait.

### How do I create an invoice through Jentic?

Search Jentic for 'create an invoice for an order in billbee'. Jentic returns the CreateInvoice operation, loads its schema, and your agent calls POST `/api/v1/orders/CreateInvoice/{id}` with the order ID. Pair with PUT `/api/v1/orders/{id}/orderstate` to mark the order processed.

### Can I subscribe to Billbee events?

Yes. Use GET `/api/v1/events` to enumerate event types and the webhooks endpoints to register a callback URL. Webhooks fire on order, shipment, and product events so an agent can react in near real time without polling.

### Is the Billbee API free?

API access is included with paid Billbee plans rather than a separate free tier. You also need to email support@billbee.io to request your developer API key. Jentic does not add usage charges on top of the underlying plan.

### Can I limit what my agent is allowed to do with the Billbee API?

Yes. Because you run Jentic One yourself, your own rules decide which Billbee operations and credentials the agent may use, so you can allow read-only calls like GET `/api/v1/orders` or GET `/api/v1/customers/{id}/orders` while withholding state-changing ones like PUT `/api/v1/orders/{id}/orderstate` or POST `/api/v1/orders/{id}/shipment.` Since Billbee carries the order and customer id in the URL path, you can also pin the agent to a single order or a single customer rather than the whole account. Nothing runs unless you have added it to the operations your agent is permitted to call.