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).statusin query ("CANCELLED","COMPLETED","CONFIRMED","DELIVERED","ON_HOLD","PENDING","PROCESSING","RETURNED","RETURN_REQUESTED","SHIPPED", 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/{id}/payment
Section titled “POST /v1/orders/{id}/payment”Retry the payment of an order
Parameters:
accept-languagein header (string, required).idin path (string, required).
Responses:
200: New payment action.404: Order not found.409: Order payment is not retryable.
POST /v1/orders/{id}/payment/confirm
Section titled “POST /v1/orders/{id}/payment/confirm”Confirm the payment status of an order with the provider
Parameters:
idin path (string, required).
Responses:
200: Current payment status.404: Order not found.
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.
POST /v1/orders/track/payment
Section titled “POST /v1/orders/track/payment”Retry the payment of a tracked order
Parameters:
accept-languagein header (string, required).
Request body: TrackOrderDto.
Responses:
200: New payment action.404: Order not found.409: Order payment is not retryable.
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, 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).
CreateReturnDto
Section titled “CreateReturnDto”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).
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, email, max length 254, required).
