Orders¶

Read and write pharmacy orders for your organization.

List orders¶

GET /api/v2/public/orgs/{orgId}/orders?limit=50&offset=0&status=awaiting_packing&shop_id=shop1
Authorization: Bearer {token}

Scope: orders.read

Query	Default	Max	Description
`limit`	`50`	`200`	Page size
`offset`	`0`	—	Offset
`status`	—	—	Filter by status
`shop_id`	—	—	Filter by shop

Response¶

{
  "data": [
    {
      "id": "ORD_20260605_abc123",
      "external_id": "POS-999",
      "status": "awaiting_packing",
      "shop_id": "shop1",
      "customer_name": "Max Mustermann",
      "total_amount": 42.99,
      "payment_status": "paid",
      "created_at": "2026-06-05T10:00:00Z",
      "updated_at": "2026-06-05T11:00:00Z"
    }
  ],
  "pagination": { "limit": 50, "offset": 0, "total": 705 }
}

Get order¶

GET /api/v2/public/orgs/{orgId}/orders/{orderId}
Authorization: Bearer {token}

Scope: orders.read

Includes shipping address, line items, and flags:

{
  "id": "ORD_20260605_abc123",
  "external_id": "POS-999",
  "status": "awaiting_packing",
  "shop_id": "shop1",
  "customer_name": "Max Mustermann",
  "customer_email": "max@example.com",
  "total_amount": 42.99,
  "payment_status": "paid",
  "payment_reference": "TX-123",
  "shipped": false,
  "picked_up": false,
  "cash_on_pickup": true,
  "shipping_address": {
    "street": "Musterstr. 1",
    "city": "Berlin",
    "postal_code": "10115",
    "phone": "+49123456789"
  },
  "items": [
    { "p1_id": "12345", "name": "Cannabis flos", "quantity": 5, "price": 8.59 }
  ],
  "created_at": "2026-06-05T10:00:00Z",
  "updated_at": "2026-06-05T11:00:00Z"
}

Create or upsert order¶

Upserts by external_id + shop_id.

POST /api/v2/public/orgs/{orgId}/orders
Authorization: Bearer {token}
Content-Type: application/json

Scope: orders.write

Request body¶

{
  "shop_id": "shop1",
  "external_id": "POS-ORDER-123",
  "order_number": "optional-existing-number",
  "order_datetime": "2026-06-05T12:00:00Z",
  "customer_name": "Max Mustermann",
  "customer_email": "max@example.com",
  "address_street": "Musterstr. 1",
  "address_city": "Berlin",
  "address_postal_code": "10115",
  "address_phone": "+49123456789",
  "total_amount": 42.99,
  "payment_status": "paid",
  "payment_reference": "TX-123",
  "shipping_option": "Abholung",
  "shipped": false,
  "picked_up": false,
  "cash_on_pickup": true,
  "items": [
    { "name": "Cannabis flos 27/1", "qty": 5, "price": 8.59, "p1_id": "12345" }
  ]
}

Line items use qty

Order upsert items must use qty, not quantity. Order-request payloads use quantity — see Order requests.

Update order¶

PUT /api/v2/public/orgs/{orgId}/orders/{orderId}
Authorization: Bearer {token}
Content-Type: application/json

Scope: orders.write

Partial update — only external-safe fields are accepted.

Patch status¶

PATCH /api/v2/public/orgs/{orgId}/orders/{orderId}/status
Authorization: Bearer {token}
Content-Type: application/json

{
  "status": "ready_pickup",
  "payment_status": "paid",
  "shipped": true,
  "picked_up": false
}

Scope: orders.write

At least one field required. Triggers order_status_updated webhook when subscribed.

Response¶

{
  "order_id": "ORD_20260605_abc123",
  "status": "ready_pickup",
  "updated_at": "2026-06-05T12:00:00Z"
}

Common order statuses¶

Status	Description
`pending`	New / unprocessed
`awaiting_payment`	Awaiting payment
`awaiting_packing`	Paid, needs packing
`ready_pickup`	Ready for customer pickup
`shipped`	Shipped
`picked_up`	Picked up
`completed`	Completed
`cancelled`	Cancelled

Exact status workflow may vary by org configuration.