Skip to content

Orders (storefront API)

Storefront and customer routes of the orders module. Send Accept-Language (or X-Locale from a browser) on every call; a customer route needs the session cookie.

List orders

Parameters:

  • page in query (number, min 1, optional).
  • pageSize in query (number, min 1, optional).
  • status in query ("CANCELLED", "COMPLETED", "CONFIRMED", "DELIVERED", "ON_HOLD", "PENDING", "PROCESSING", "RETURNED", "RETURN_REQUESTED", "SHIPPED", optional).

Responses:

  • 200: Orders retrieved.
  • 401: Unauthorized.

Create order (authenticated customer or guest)

Parameters:

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

Request body: CreateOrderDto.

Responses:

  • 201: Order created.
  • 400: Invalid input.
  • 403: Guest checkout disabled.

Get order by ID (owner or the guest who placed it)

Parameters:

  • id in path (string, required).

Responses:

  • 200: Order retrieved.
  • 403: Not the caller’s order.
  • 404: Order not found.

Cancel order

Parameters:

  • id in path (string, required).

Responses:

  • 200: Order cancelled.
  • 401: Unauthorized.
  • 404: Order not found.
  • 409: Order cannot be cancelled.

Get order invoice

Parameters:

  • id in path (string, required).

Responses:

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

Download order invoice as a branded PDF

Parameters:

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

Responses:

  • 200: PDF stream.
  • 401: Unauthorized.
  • 403: Order does not belong to the caller.
  • 404: Order not found or invoice not ready.

Retry the payment of an order

Parameters:

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

Responses:

  • 200: New payment action.
  • 404: Order not found.
  • 409: Order payment is not retryable.

Confirm the payment status of an order with the provider

Parameters:

  • id in path (string, required).

Responses:

  • 200: Current payment status.
  • 404: Order not found.

Create return request

Parameters:

  • orderId in path (string, required).

Request body: CreateReturnDto.

Responses:

  • 201: Return created.
  • 400: Invalid input.
  • 401: Unauthorized.
  • 404: Order not found.

Track an order by number and email

Request body: TrackOrderDto.

Responses:

  • 200: Order tracking data.
  • 400: Invalid input.
  • 404: Order not found.

Retry the payment of a tracked order

Parameters:

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

Request body: TrackOrderDto.

Responses:

  • 200: New payment action.
  • 404: Order not found.
  • 409: Order payment is not retryable.
  • 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).
  • guestEmail (string, email, optional).
  • shippingAddressId (string, optional).
  • shippingAddress (AddressDto, optional).
  • billingAddressId (string, optional).
  • billingAddress (AddressDto, optional).
  • shippingMethodId (string, optional).
  • paymentMethodCode (string, optional).
  • notes (string, optional).
  • giftCardCode (string, pattern ^[A-Z0-9]{8,20}$, optional).
  • couponCode (string, optional).
  • items (array of ReturnItemDto, required).
  • reason ("CHANGED_MIND", "DEFECTIVE", "NOT_AS_DESCRIBED", "OTHER", "WRONG_SIZE", required).
  • reasonDetail (string, max length 1000, optional).
  • photoAssetIds (array of string, optional).
  • refundMethod ("EXCHANGE", "ORIGINAL_PAYMENT", "STORE_CREDIT", optional).
  • orderItemId (string, required).
  • quantity (number, min 1, required).
  • exchangeVariantId (string, optional).
  • orderNumber (string, pattern ^[A-Z0-9-]+$, max length 32, required).
  • email (string, email, max length 254, required).
As seen on Open Source Alternatives The Merchant Engine badge