Orders (admin API)

Admin routes of the orders module. Every route needs a staff session and the permission named on it; send X-Resolve-Locale: false to receive every locale of a translatable field for editing.

GET /v1/admin/orders

List orders (admin)

Parameters:

• dateFrom in query (string, optional).
• dateTo in query (string, optional).
• page in query (number, min 1, optional).
• pageSize in query (number, min 1, optional).
• paymentStatus in query ("AUTHORIZED", "CANCELLED", "CAPTURED", "FAILED", "PARTIALLY_REFUNDED", "PENDING", "REFUNDED", optional).
• search in query (string, optional).
• sortBy in query (string, optional).
• sortOrder in query ("asc", "desc", optional).
• status in query ("CANCELLED", "COMPLETED", "CONFIRMED", "DELIVERED", "ON_HOLD", "PENDING", "PROCESSING", "RETURNED", "RETURN_REQUESTED", "SHIPPED", optional).
• userId in query (string, optional).

Responses:

• 200: Orders retrieved.
• 401: Unauthorized.
• 403: Insufficient permissions.

POST /v1/admin/orders

Create order (admin manual)

Parameters:

• accept-language in header (string, required).

Request body: CreateAdminOrderDto.

Responses:

• 201: Order created.
• 400: Invalid input.
• 401: Unauthorized.
• 403: Insufficient permissions.

GET /v1/admin/orders/{id}

Get order by ID (admin)

Parameters:

• id in path (string, required).

Responses:

• 200: Order retrieved.
• 401: Unauthorized.
• 403: Insufficient permissions.
• 404: Order not found.

PATCH /v1/admin/orders/{id}

Edit order

Parameters:

• accept-language in header (string, required).
• id in path (string, required).

Request body: EditOrderDto.

Responses:

• 200: Order updated.
• 400: Invalid input.
• 401: Unauthorized.
• 403: Insufficient permissions.
• 404: Order not found.

GET /v1/admin/orders/{id}/invoice

Get order invoice (admin)

Parameters:

• id in path (string, required).

Responses:

• 200: Invoice retrieved.
• 401: Unauthorized.
• 403: Insufficient permissions.
• 404: Order not found.

GET /v1/admin/orders/{id}/invoice/pdf

Download order invoice as a branded PDF (admin)

Parameters:

• accept-language in header (string, required).
• id in path (string, required).

Responses:

• 200: PDF stream.
• 401: Unauthorized.
• 403: Insufficient permissions.
• 404: Order not found or invoice not ready.

POST /v1/admin/orders/{id}/notes

Add order note

Parameters:

• id in path (string, required).

Request body: AddNoteDto.

Responses:

• 200: Note added.
• 400: Invalid input.
• 401: Unauthorized.
• 403: Insufficient permissions.
• 404: Order not found.

POST /v1/admin/orders/{id}/payment/cancel

Cancel the order payment through its provider

Parameters:

• id in path (string, required).

Responses:

• 200: Payment cancelled.
• 401: Unauthorized.
• 403: Insufficient permissions.
• 404: Order not found.
• 409: Transition not allowed or no payment session.

POST /v1/admin/orders/{id}/payment/capture

Capture the order payment through its provider

Parameters:

• id in path (string, required).

Responses:

• 200: Payment captured.
• 401: Unauthorized.
• 403: Insufficient permissions.
• 404: Order not found.
• 409: Transition not allowed or no payment session.

POST /v1/admin/orders/{id}/payment/refund

Refund the full order payment through its provider

Parameters:

• id in path (string, required).

Responses:

• 200: Payment refunded.
• 401: Unauthorized.
• 403: Insufficient permissions.
• 404: Order not found.
• 409: Transition not allowed or no payment session.

POST /v1/admin/orders/{id}/shipments

Create shipment

Parameters:

• id in path (string, required).

Request body: CreateShipmentDto.

Responses:

• 201: Shipment created.
• 400: Invalid input.
• 401: Unauthorized.
• 403: Insufficient permissions.
• 404: Order not found.

PATCH /v1/admin/orders/{id}/shipments/{sid}

Update shipment

Parameters:

• id in path (string, required).
• sid in path (string, required).

Request body: UpdateShipmentDto.

Responses:

• 200: Shipment updated.
• 400: Invalid input.
• 401: Unauthorized.
• 403: Insufficient permissions.
• 404: Shipment not found.

PATCH /v1/admin/orders/{id}/status

Update order status

Parameters:

• id in path (string, required).

Request body: UpdateOrderStatusDto.

Responses:

• 200: Status updated.
• 400: Invalid input.
• 401: Unauthorized.
• 403: Insufficient permissions.
• 404: Order not found.

GET /v1/admin/orders/export

Export orders to CSV

Parameters:

• dateFrom in query (string, optional).
• dateTo in query (string, optional).
• page in query (number, min 1, optional).
• pageSize in query (number, min 1, optional).
• paymentStatus in query ("AUTHORIZED", "CANCELLED", "CAPTURED", "FAILED", "PARTIALLY_REFUNDED", "PENDING", "REFUNDED", optional).
• search in query (string, optional).
• sortBy in query (string, optional).
• sortOrder in query ("asc", "desc", optional).
• status in query ("CANCELLED", "COMPLETED", "CONFIRMED", "DELIVERED", "ON_HOLD", "PENDING", "PROCESSING", "RETURNED", "RETURN_REQUESTED", "SHIPPED", optional).
• userId in query (string, optional).

Responses:

• 200: CSV file.
• 401: Unauthorized.
• 403: Insufficient permissions.

GET /v1/admin/orders/stats

Get orders statistics

Responses:

• 200: Statistics retrieved.
• 401: Unauthorized.
• 403: Insufficient permissions.

Schemas

AddItemDto

• variantId (string, required).
• quantity (number, min 1, required).

AddNoteDto

• note (string, min length 1, required).

AdminOrderAddressDto

• fullName (string, required).
• phone (string, required).
• addressLine1 (string, required).
• addressLine2 (string, optional).
• city (string, required).
• state (string, optional).
• postalCode (string, optional).
• country (string, pattern ^[A-Z]{2}$, required).

AdminOrderItemDto

• variantId (string, required).
• quantity (number, min 1, required).

CreateAdminOrderDto

• userId (string, optional).
• items (array of AdminOrderItemDto, required).
• shippingAddress (AdminOrderAddressDto, required).
• billingAddress (AdminOrderAddressDto, optional).
• shippingMethodId (string, optional).
• couponCode (string, optional).
• notes (string, optional).

CreateShipmentDto

• items (array of ShipmentItemDto, required).
• carrier (string, optional).
• trackingNumber (string, optional).

EditAddressDto

• fullName (string, required).
• phone (string, required).
• addressLine1 (string, required).
• addressLine2 (string, optional).
• city (string, required).
• state (string, optional).
• postalCode (string, optional).
• country (string, pattern ^[A-Z]{2}$, required).

EditOrderDto

• addItems (array of AddItemDto, optional).
• removeItems (array of RemoveItemDto, optional).
• shippingAddress (EditAddressDto, optional).
• manualDiscount (number, min 0, optional).
• internalNotes (string, optional).

RemoveItemDto

• orderItemId (string, required).

ShipmentItemDto

• orderItemId (string, required).
• quantity (number, min 1, required).

UpdateOrderStatusDto

• status ("CANCELLED", "COMPLETED", "CONFIRMED", "DELIVERED", "ON_HOLD", "PENDING", "PROCESSING", "RETURNED", "RETURN_REQUESTED", "SHIPPED", required).

UpdateShipmentDto

• carrier (string, optional).
• trackingNumber (string, optional).
• status ("DELIVERED", "PROCESSING", "SHIPPED", optional).