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.
GET /v1/orders
Section titled “GET /v1/orders”List orders
Parameters:
pagein query (number, min 1, optional).pageSizein query (number, min 1, optional).
Responses:
200: Orders retrieved.401: Unauthorized.
POST /v1/orders
Section titled “POST /v1/orders”Create order (authenticated customer or guest)
Parameters:
accept-languagein header (string, required).
Request body: CreateOrderDto.
Responses:
201: Order created.400: Invalid input.403: Guest checkout disabled.
GET /v1/orders/{id}
Section titled “GET /v1/orders/{id}”Get order by ID (owner or the guest who placed it)
Parameters:
idin path (string, required).
Responses:
200: Order retrieved.403: Not the caller’s order.404: Order not found.
POST /v1/orders/{id}/cancel
Section titled “POST /v1/orders/{id}/cancel”Cancel order
Parameters:
idin path (string, required).
Responses:
200: Order cancelled.401: Unauthorized.404: Order not found.409: Order cannot be cancelled.
GET /v1/orders/{id}/invoice
Section titled “GET /v1/orders/{id}/invoice”Get order invoice
Parameters:
idin path (string, required).
Responses:
200: Invoice retrieved.401: Unauthorized.404: Order not found.
GET /v1/orders/{id}/invoice/pdf
Section titled “GET /v1/orders/{id}/invoice/pdf”Download order invoice as a branded PDF
Parameters:
accept-languagein header (string, required).idin 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.
POST /v1/orders/{orderId}/returns
Section titled “POST /v1/orders/{orderId}/returns”Create return request
Parameters:
orderIdin path (string, required).
Request body: CreateReturnDto.
Responses:
201: Return created.400: Invalid input.401: Unauthorized.404: Order not found.
POST /v1/orders/track
Section titled “POST /v1/orders/track”Track an order by number and email
Request body: TrackOrderDto.
Responses:
200: Order tracking data.400: Invalid input.404: Order not found.
Schemas
Section titled “Schemas”AddressDto
Section titled “AddressDto”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).
CreateOrderDto
Section titled “CreateOrderDto”guestEmail(string, 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).
CreateReturnDto
Section titled “CreateReturnDto”items(array of ReturnItemDto, required).reason(object, required).reasonDetail(string, max length 1000, optional).photoAssetIds(array of string, optional).refundMethod(object, optional).
ReturnItemDto
Section titled “ReturnItemDto”orderItemId(string, required).quantity(number, min 1, required).exchangeVariantId(string, optional).
TrackOrderDto
Section titled “TrackOrderDto”orderNumber(string, pattern/^[A-Z0-9-]+$/, max length 32, required).email(string, max length 254, required).