POST /api/v1/orders — Create a pickup order

The Create Order endpoint allows an authenticated user to place a new pickup order at a specific store. The server validates the store, resolves each requested product, calculates per-item pricing — including any size-based surcharge — and stores a total_price_chf on the resulting order document. The response includes a fully populated order object with store and user details.

This endpoint requires a valid user JWT passed in the Authorization header. Orders are automatically associated with the authenticated user; no user_id field is accepted in the request body.

HTTP method and path

POST /api/v1/orders

Request parameters

Headers

Authorization

string

required

Bearer token for the authenticated user. Format: Bearer <token>.

Body

store_id

string

required

MongoDB ObjectId of the store where the order will be picked up.

pickup

string

required

ISO 8601 datetime string for the scheduled pickup time. Example: 2026-01-10T12:30:00Z.

items

object[]

required

Array of items to include in the order. Must contain at least one entry.

Show item properties

items[].product_id

string

required

MongoDB ObjectId of the product to order.

items[].size

string

required

Product size. Accepted values: S, M, L.

items[].quantity

number

required

Number of units to order. Minimum: 1, maximum: 100.

Response fields

201 Created

message

string

Human-readable confirmation. Value: "Order successfully created".

order

object

The newly created order, populated with store and user references.

Show order properties

order._id

string

Unique MongoDB ObjectId of the order.

order.user_id

object

Populated user object containing email and display_name.

order.store_id

object

Populated store object.

order.status

string

Initial order status. Always "en préparation" on creation.

order.pickup

string

ISO 8601 datetime of the scheduled pickup.

order.total_price_chf

number

Total price in Swiss francs, calculated as the sum of (basePriceCHF + extra_chf[size]) × quantity for each item.

order.createdAt

string

ISO 8601 timestamp of when the order was created.

order.updatedAt

string

ISO 8601 timestamp of the last update.

Error codes

Status	Meaning
`400`	Missing or invalid request data. Returned when `store_id`, `pickup`, or `items` are absent, or when an individual item is missing `product_id`, `size`, or `quantity`.
`401`	Missing or invalid JWT token.
`404`	The specified store or a referenced product was not found.
`422`	Mongoose validation error (e.g. invalid ObjectId format, size not in enum).
`500`	Unexpected server error.

Example

curl --request POST \
  --url https://api.example.com/api/v1/orders \
  --header 'Authorization: Bearer <user_token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "store_id": "64f1c2e9a1b2c3d4e5f12345",
    "pickup": "2026-01-10T12:30:00Z",
    "items": [
      {
        "product_id": "64f1c2e9a1b2c3d4e5f12346",
        "size": "M",
        "quantity": 2
      }
    ]
  }'

{
  "message": "Order successfully created",
  "order": {
    "_id": "64f1c2e9a1b2c3d4e5f99999",
    "user_id": {
      "_id": "64f1c2e9a1b2c3d4e5f00001",
      "email": "[email protected]",
      "display_name": "Alice"
    },
    "store_id": {
      "_id": "64f1c2e9a1b2c3d4e5f12345",
      "name": "Ocha Lausanne"
    },
    "status": "en préparation",
    "pickup": "2026-01-10T12:30:00.000Z",
    "total_price_chf": 11.80,
    "createdAt": "2026-01-09T08:00:00.000Z",
    "updatedAt": "2026-01-09T08:00:00.000Z"
  }
}

Authentication

Users

Products

Stores

Orders

POST /api/v1/orders — Create a pickup order

HTTP method and path

Request parameters

Headers

Body

Response fields

201 Created

Error codes

Example

Build docs developers (and LLMs) love

Authentication

Users

Products

Stores

Orders

Documentation Index

​HTTP method and path

​Request parameters

​Headers

​Body

​Response fields

​201 Created

​Error codes

​Example

Build docs developers (and LLMs) love

HTTP method and path

Request parameters

Headers

Body

Response fields

201 Created

Error codes

Example