Orders

The Orders API allows you to create, retrieve, and manage restaurant orders. All order operations are fully compliant with German GoBD regulations, ensuring a complete and immutable audit trail.

GoBD Compliance

All order data is stored in an append-only database. Cancellations create storno (reversal) entries rather than deleting the original record. This ensures full traceability as required by German fiscal law (GoBD). Original order items are never deleted.

List Orders

GET/api/ordersProtected

Retrieve a list of orders for the authenticated restaurant. Supports filtering by status and pagination via limit.

Query Parameters

Name	Type	Required	Description
`status`	`string`	Optional	Filter by order status. Can be repeated for multiple statuses, e.g. ?status=open&status=in_progress. Values: open, in_progress, ready, served, closed, cancelled.
`limit`	`integer`	Optional	Maximum number of orders to return. Default: 50. Max: 200.

Response 200 OK

json

{
  __PH0__: [
    {
      __PH1__: "d290f1ee-6c54-4b01-90e6-d701748f0851",
      __PH3__: "a1b2c3d4-0000-0000-0000-000000000001",
      __PH5__: "dine_in",
      __PH7__: "open",
      __PH9__: 4,
      __PH10__: [...],
      __PH11__: 4580,
      __PH12__: "2026-03-20T14:30:00Z",
      __PH14__: "2026-03-20T14:30:00Z"
    }
  ],
  __PH16__: 1
}

bash

curl __PH1__Authorization: Bearer eyJhbGci..."

Create Order

POST/api/ordersProtected

Create a new order. The order is assigned to a table and can include initial items.

Request Body

Name	Type	Required	Description
`table_id`	`uuid`	Required	ID of the table this order is assigned to.
`order_type`	`string`	Required	Type of order: dine_in, takeaway, or delivery. Affects VAT calculation (19% dine-in vs 7% takeaway).
`guest_count`	`integer`	Optional	Number of guests at the table. Default: 1.
`items`	`array`	Optional	Array of order items to include initially (see item fields below).

Order Item Fields

Name	Type	Required	Description
`menu_item_id`	`uuid`	Required	ID of the menu item being ordered.
`quantity`	`integer`	Required	Number of this item to order (min: 1).
`is_takeaway`	`boolean`	Optional	Override the order-level type for this specific item. When true, 7% VAT applies instead of 19%. Useful for mixed orders.
`notes`	`string`	Optional	Special instructions for the kitchen, e.g. "ohne Zwiebeln" (without onions).
`modifiers`	`array`	Optional	Array of modifier IDs to apply (e.g. extra cheese, size upgrades).

Mixed VAT Orders

German tax law requires correct VAT handling for mixed orders. Set is_takeaway on individual items when a dine-in order includes takeaway items. Dine-in items are taxed at 19%, takeaway items at 7%.

json

{
  __PH0__: "a1b2c3d4-0000-0000-0000-000000000001",
  __PH2__: "dine_in",
  __PH4__: 2,
  __PH5__: [
    {
      __PH6__: "c3d4e5f6-1111-2222-3333-444455556666",
      __PH8__: 2,
      __PH9__: "medium rare",
      __PH11__: ["mod-extra-sauce"]
    },
    {
      __PH13__: "d4e5f6a7-2222-3333-4444-555566667777",
      __PH15__: 1,
      __PH16__: true,
      __PH17__: "zum Mitnehmen"
    }
  ]
}

Response 201 Created

json

{
  __PH0__: "d290f1ee-6c54-4b01-90e6-d701748f0851",
  __PH2__: "a1b2c3d4-0000-0000-0000-000000000001",
  __PH4__: "dine_in",
  __PH6__: "open",
  __PH8__: 2,
  __PH9__: [
    {
      __PH10__: "item-uuid-1",
      __PH12__: "c3d4e5f6-1111-2222-3333-444455556666",
      __PH14__: "Rindersteak",
      __PH16__: 2,
      __PH17__: 2490,
      __PH18__: 4980,
      __PH19__: 19,
      __PH20__: false,
      __PH21__: "medium rare",
      __PH23__: [{__PH24__: "mod-extra-sauce", __PH26__: "Extra Sauce", __PH28__: 50}],
      __PH29__: "ordered"
    },
    {
      __PH31__: "item-uuid-2",
      __PH33__: "d4e5f6a7-2222-3333-4444-555566667777",
      __PH35__: "Pommes Frites",
      __PH37__: 1,
      __PH38__: 450,
      __PH39__: 450,
      __PH40__: 7,
      __PH41__: true,
      __PH42__: "zum Mitnehmen",
      __PH44__: [],
      __PH45__: "ordered"
    }
  ],
  __PH47__: 5430,
  __PH48__: "2026-03-20T14:30:00Z",
  __PH50__: "2026-03-20T14:30:00Z"
}

Get Order

GET/api/orders/:idProtected

Retrieve a single order by its ID, including all items, modifiers, and current status.

Path Parameters

Name	Type	Required	Description
`id`	`uuid`	Required	The unique identifier of the order.

Response 200 OK

Returns the full order object (same structure as the create response above).

bash

curl https://api.possfer.com/api/orders/d290f1ee-6c54-4b01-90e6-d701748f0851 \
  -H "Authorization: Bearer eyJhbGci..."

Add Items to Order

POST/api/orders/:id/itemsProtected

Add one or more items to an existing open order. The order's total is recalculated automatically.

Path Parameters

Name	Type	Required	Description
`id`	`uuid`	Required	The order ID to add items to.

Request Body

Name	Type	Required	Description
`items`	`array`	Required	Array of order items to add (same fields as create order items).

json

{
  __PH0__: [
    {
      __PH1__: "e5f6a7b8-3333-4444-5555-666677778888",
      __PH3__: 2,
      __PH4__: "ohne Eis"
    }
  ]
}

Response 200 OK

Returns the updated order object with the newly added items included.

Update Order Status

PATCH/api/orders/:id/statusProtected

Transition an order to a new status. Status transitions follow a defined lifecycle.

Request Body

Name	Type	Required	Description
`status`	`string`	Required	The new status. Valid values: open, in_progress, ready, served, closed, cancelled.

Status Lifecycle

open → in_progress → ready → served → closed

An order can be cancelled from any status except closed.

json

{
  __PH0__: "in_progress"
}

bash

curl -X PATCH https://api.possfer.com/api/orders/d290f1ee-6c54-4b01-90e6-d701748f0851/status \
  -H "Authorization: Bearer eyJhbGci..." \
  -H "Content-Type: application/json" \
  -d '{"status": "in_progress"}'

Cancel Order Item (Storno)

POST/api/orders/:id/items/:itemId/cancelProtected

Cancel a specific item within an order. Creates a storno (reversal) entry for GoBD compliance. The original item record is never deleted.

Path Parameters

Name	Type	Required	Description
`id`	`uuid`	Required	The order ID.
`itemId`	`uuid`	Required	The order item ID to cancel.

GoBD Storno

Per GoBD requirements, this endpoint does not delete the original item. Instead, it creates a storno entry — a negative reversal record linked to the original. Both the original and storno entries remain in the database permanently for audit purposes.

Request Body

Name	Type	Required	Description
`reason`	`string`	Optional	Reason for cancellation (recorded in the storno entry for audit trail).

json

{
  __PH0__: "Guest changed their mind"
}

Response 200 OK

json

{
  __PH0__: "storno-uuid-123",
  __PH2__: "item-uuid-1",
  __PH4__: -__PH9__,
  __PH5__: "Guest changed their mind",
  __PH7__: "2026-03-20T14:45:00Z"
}

Transfer Order to Another Table

POST/api/orders/:id/transferProtected

Transfer an open order from one table to another. The original table is freed up and the order is reassigned to the target table.

Path Parameters

Name	Type	Required	Description
`id`	`uuid`	Required	The order ID to transfer.

Request Body

Name	Type	Required	Description
`target_table_id`	`uuid`	Required	The ID of the destination table.

json

{
  __PH0__: "b2c3d4e5-0000-0000-0000-000000000007"
}

Response 200 OK

Returns the updated order object with the new table_id reflecting the target table.

bash

curl -X POST https://api.possfer.com/api/orders/d290f1ee-6c54-4b01-90e6-d701748f0851/transfer \
  -H "Authorization: Bearer eyJhbGci..." \
  -H "Content-Type: application/json" \
  -d '{"target_table_id": "b2c3d4e5-0000-0000-0000-000000000007"}'