create an order - Example be.open API

Creates a new order or updates an existing one (by reference). Authentication: requires ROLE_API_ADMIN. The request body is validated server-side against a JSON Schema. Status code on success is 201 Created, not 200. Update semantic: if an order with the same reference already exists in state dispatch_failed, it is updated instead of creating a new one. With ?forceTransfer=1, any existing order with the same reference is updated regardless of state. After persisting, the order is dispatched to the service provider. If dispatch fails, the order is set to state dispatch_failed and the original exception is rethrown.

Request

Query Params

Body Params application/json

Example

{
    "reference": "shop-order-12345",
    "currency": "EUR",
    "details": [
        {
            "sku": "cfg-uuid-1111",
            "product_id": "p1111111-1111-1111-1111-111111111111",
            "reference": "cart-item-1",
            "sender_address": {
                "first_name": "Shop",
                "last_name": "GmbH",
                "street": "Senderstr.",
                "house_number": "1",
                "zip_code": "10115",
                "city": "Berlin",
                "country": "DE"
            },
            "invoice_address": {
                "first_name": "Max",
                "last_name": "Mustermann",
                "street": "Rechnungstr.",
                "house_number": "12",
                "zip_code": "10115",
                "city": "Berlin",
                "country": "DE"
            },
            "delivery_address": {
                "first_name": "Max",
                "last_name": "Mustermann",
                "street": "Beispielstr.",
                "house_number": "12a",
                "zip_code": "10115",
                "city": "Berlin",
                "country": "DE"
            },
            "files": [],
            "order_combination": {
                "data": {
                    "color": "red",
                    "format": "din-a4"
                }
            }
        }
    ]
}

Responses

🟢201Success

application/json

Order was created (or updated).

Bodyapplication/json

Example

{
    "jsonapi": {
        "version": "1.0"
    },
    "data": {
        "type": "orders",
        "id": "ord-uuid-1111",
        "attributes": {
            "reference": "shop-order-12345",
            "currency": "EUR",
            "status": "new",
            "created_at": "2026-05-27T10:00:00+02:00"
        }
    }
}

🟠401

🟠422