ce-orders

LLM Docs Header: All requests to https://llm-docs.commercengine.io must include the Accept: text/markdown header (or append .md to the URL path). Without it, responses return HTML instead of parseable markdown.

Order Management

Prerequisite: Order creation requires a cart with items and addresses. See cart-checkout/ .

Quick Reference

Task SDK Method

Create order sdk.order.createOrder({ cart_id, payment_method? })

List orders sdk.order.listOrders({ page, limit })

Get order detail sdk.order.getOrderDetails({ order_number })

Get shipments sdk.order.listOrderShipments({ order_number })

Get payments sdk.order.listOrderPayments({ order_number })

Payment status sdk.order.getPaymentStatus(orderNumber) — takes a plain string, not { order_number }

Retry payment sdk.order.retryOrderPayment({ order_number }, { payment_method })

Cancel order sdk.order.cancelOrder({ order_number }, { cancellation_reason, refund_mode })

Get refunds sdk.order.listOrderRefunds({ order_number })

Note: Returns are managed by the brand admin (Admin Portal), not the storefront. Customers can cancel within the cancellation window (is_cancellation_allowed ); the admin then decides whether to schedule a return shipment or issue a direct refund. The default behavior is to refund if cancelled within the window. Return/replacement request APIs for storefront are under development.

Decision Tree

User Request │ ├─ "Place order" / "Checkout" │ └─ sdk.order.createOrder() → handle payment_info │ → See cart-checkout/ for full checkout flow │ ├─ "My orders" / "Order history" │ └─ sdk.order.listOrders({ page, limit }) │ ├─ "Order detail" / "Order #123" │ └─ sdk.order.getOrderDetails({ order_number }) │ ├─ "Track shipment" │ └─ sdk.order.listOrderShipments({ order_number }) │ → tracking_url, awb_no, status, eta_delivery │ ├─ "Payment failed" / "Retry" │ ├─ Check → sdk.order.getPaymentStatus(orderNumber) │ └─ Retry → sdk.order.retryOrderPayment({ order_number }, { payment_method }) │ └─ "Cancel order" ├─ Check is_cancellation_allowed first └─ sdk.order.cancelOrder({ order_number }, { ... })

Order Statuses

Status Description

draft

Order created, awaiting payment

confirmed

Payment successful, order confirmed

processing

Being prepared for shipment

shipped

In transit

delivered

Delivered to customer

cancelled

Order cancelled

Payment Statuses

Status Description Action

pending

Payment not yet processed Poll again after delay

success

Payment successful Show confirmation

failed

Payment failed Check is_retry_available

Key Patterns

Create Order from Cart

See cart-checkout/references/payment-patterns.md § "Building Payment Payloads" for all payment_method shapes.

const { data: order, error } = await sdk.order.createOrder({ cart_id: cartId, payment_method: { payment_provider_slug: "juspay", integration_type: "hyper-checkout", gateway_reference_id: gatewayRefId, return_url: "https://yoursite.com/order/confirm", action: "paymentPage", }, });

if (order.payment_required) { // Use payment_info to redirect or handle payment flow }

List Orders with Filters

const { data, error } = await sdk.order.listOrders({ page: 1, limit: 10, sort_by: JSON.stringify({ order_date: "desc" }), });

// data.orders → OrderList[] (summary view) // data.pagination → { total_records, total_pages, next_page }

Poll Payment Status

async function pollPaymentStatus(orderNumber: string) { // Note: getPaymentStatus takes a string, not an object const { data, error } = await sdk.order.getPaymentStatus(orderNumber);

if (data.status === "pending") { setTimeout(() => pollPaymentStatus(orderNumber), 3000); return; }

if (data.status === "success") { showConfirmation(orderNumber); } else if (data.is_retry_available) { showRetryOption(orderNumber); } else { showPaymentFailed(); } }

Cancel Order

// First check if cancellation is allowed const { data: order } = await sdk.order.getOrderDetails({ order_number: orderNumber, });

if (order.is_cancellation_allowed) { const { data, error } = await sdk.order.cancelOrder( { order_number: orderNumber }, { cancellation_reason: "Changed my mind", refund_mode: "original_payment_mode", feedback: "Optional feedback", } ); }

Shipment Tracking

const { data, error } = await sdk.order.listOrderShipments({ order_number: orderNumber, });

data.shipments.forEach((shipment) => { console.log(shipment.status); // "shipped", "delivered", etc. console.log(shipment.tracking_url); // Courier tracking link console.log(shipment.awb_no); // Air waybill number console.log(shipment.eta_delivery); // Estimated delivery date });

Common Pitfalls

Level Issue Solution

CRITICAL Creating order without address Cart must have billing/shipping addresses set before createOrder()

HIGH Not polling payment status After gateway redirect, always poll getPaymentStatus()

HIGH Showing cancel button when not allowed Check is_cancellation_allowed from order detail first

MEDIUM Not handling multiple shipments One order can have multiple shipments — iterate data.shipments

MEDIUM Missing return_url

Must provide return_url for payment gateway callback

MEDIUM Building a returns flow on storefront Returns are admin-managed. Storefront supports cancellation only (cancelOrder ). Show order/refund status, not a "Request Return" form.

LOW Not filtering orders by status Use status[] query param to show relevant orders per tab

Safety Notice

Copy this and send it to your AI assistant to learn

Source Transparency

Related Skills

ce-cart-checkout

ce

ce-auth