Create or edit an order
Create an order (a purchasing list for one shop) or change one: name, supplier, status, shipping cost, expected delivery date, notes. Create: leave out order and send name (plus optional items to put on it right away). Edit: send order (id or name) and only what changes. Status: "draft" (still to order), "ordered" (placed; its items count as on order in the planner), "partial" (some items arrived), "received" (everything arrived). Setting "ordered" stamps the order date. Setting "received" does NOT book anything into stock: to put arrived items into the inventory use receive_order. To add, change or remove lines later use edit_order_items. To build an order from what the planned brews are short of, use create_order_from_shortages. Needs the plan feature `orders`. Scope: `inventory:write` (or `write`).
Create an order (a purchasing list for one shop) or change one: name, supplier, status, shipping cost, expected delivery date, notes. Create: leave out order and send name (plus optional items to put on it right away). Edit: send order (id or name) and only what changes. Status: "draft" (still to order), "ordered" (placed; its items count as on order in the planner), "partial" (some items arrived), "received" (everything arrived). Setting "ordered" stamps the order date. Setting "received" does NOT book anything into stock: to put arrived items into the inventory use receive_order. To add, change or remove lines later use edit_order_items. To build an order from what the planned brews are short of, use create_order_from_shortages.
Needs the plan feature orders. Scope: inventory:write (or write).
API token in format: bfk_. Each operation lists the token scope it requires (the scopes are listed below).
read: Read everything (all areas)write: Create, change and delete everything (all areas)brews:read: List and view brewsbrews:write: Create, update, delete brews and notesinventory:read: List inventory itemsinventory:write: Create, update, delete inventory itemsequipment:read: List equipment profilesequipment:write: Create, update, delete equipment profilesstyles:read: List style profilesstyles:write: Create, update, delete style profilesprofiles:read: List mash, fermentation, and water profilescustom-fields:read: List custom field definitionscustom-fields:write: Create, update, delete custom field definitionsprofiles:write: Create, update, delete mash, fermentation, and water profilescellar:read: View cellar, packaged stock, tap lists, and labelscellar:write: Manage cellar, packaging, stock, tap lists, and labelssettings:read: View preferences, imports, calculators, and your data exportsettings:write: Change preferences and undo importscommunity:read: View community, feedback, tickets, inbox, and account overviewcommunity:write: Post, vote, and reply in community, feedback, and tickets
In: header
Scope: inventory:write
Request Body
application/json
The order: its id (from get_orders) or its exact name (e.g. "Hopfen der Welt November"). Case does not matter. Leave out to create a new order.
Order name (required to create), e.g. "Hopfen der Welt November".
1 <= length <= 200Shop or supplier (e.g. "Hopfen der Welt"); "" clears it. Becomes the stock rows' supplier when receiving.
length <= 200"draft" (still to order), "ordered" (placed; its items count as on order in the planner), "partial" (some items arrived), "received" (everything arrived). New orders start as "draft".
"draft" | "ordered" | "partial" | "received"Shipping for the whole order in the user's currency (split over the line prices when receiving); null clears it.
Expected delivery date, YYYY-MM-DD (e.g. "2026-11-20"); YYYY-MM means the last day of that month.
Free text; "" clears it.
length <= 1000Create only: lines for the new order. Each: {ingredient (name or id), amount, unit?, type?, form?, alpha_acid_pct?, harvest_year?, estimated_cost?, price_paid?, notes?}, e.g. [{"ingredient": "Pale Ale Malt", "amount": 1, "unit": "kg"}].
items <= 100Response Body
application/json
application/json
application/json
application/json
application/json
application/json
application/json
curl -X POST "https://brewforge.sh/api/v1/actions/save_order" \ -H "Content-Type: application/json" \ -d '{}'{
"order": {
"id": "string",
"name": "string",
"supplier": "string",
"status": "draft",
"ordered_date": "string",
"expected_date": "string",
"received_date": "string",
"shipping_cost": 0,
"notes": "string",
"item_count": 0,
"arrived_count": 0,
"items_cost": 0,
"total_cost": 0,
"next_step": "add_items",
"free_text_items": [
"string"
],
"items": [
{
"id": "string",
"type": "fermentable",
"name": "string",
"ingredient_id": "string",
"form": "string",
"alpha_acid_pct": 0,
"harvest_year": 0,
"amount": 0,
"ordered_amount": 0,
"unit": "string",
"received": 0,
"remaining": 0,
"arrival": "pending",
"estimated_cost": 0,
"price_paid": 0,
"notes": "string"
}
]
},
"created": true,
"note": "string"
}{
"error": {
"code": "string",
"message": "string",
"hint": "string",
"candidates": [
{
"id": "string",
"name": "string"
}
],
"fields": {
"property1": [
"string"
],
"property2": [
"string"
]
},
"details": {}
}
}{
"error": {
"code": "string",
"message": "string",
"hint": "string",
"candidates": [
{
"id": "string",
"name": "string"
}
],
"fields": {
"property1": [
"string"
],
"property2": [
"string"
]
},
"details": {}
}
}{
"error": {
"code": "string",
"message": "string",
"hint": "string",
"candidates": [
{
"id": "string",
"name": "string"
}
],
"fields": {
"property1": [
"string"
],
"property2": [
"string"
]
},
"details": {}
}
}{
"error": {
"code": "string",
"message": "string",
"hint": "string",
"candidates": [
{
"id": "string",
"name": "string"
}
],
"fields": {
"property1": [
"string"
],
"property2": [
"string"
]
},
"details": {}
}
}{
"error": {
"code": "string",
"message": "string",
"hint": "string",
"candidates": [
{
"id": "string",
"name": "string"
}
],
"fields": {
"property1": [
"string"
],
"property2": [
"string"
]
},
"details": {}
}
}{
"error": {
"code": "string",
"message": "string",
"hint": "string",
"candidates": [
{
"id": "string",
"name": "string"
}
],
"fields": {
"property1": [
"string"
],
"property2": [
"string"
]
},
"details": {}
}
}