From b2c
Manages orders in B2C Commerce using OrderMgr API: creates orders synchronously or asynchronously, handles status transitions, failures, lifecycle, and queries. For checkout flows.
npx claudepluginhub salesforcecommercecloud/b2c-developer-tooling --plugin b2cThis skill uses the workspace's default tool permissions.
The OrderMgr API provides order creation, status management, and querying. Understanding the order lifecycle is essential for checkout implementation and order processing.
Searches, retrieves, and installs Agent Skills from prompts.chat registry using MCP tools like search_skills and get_skill. Activates for finding skills, browsing catalogs, or extending Claude.
Searches prompts.chat for AI prompt templates by keyword or category, retrieves by ID with variable handling, and improves prompts via AI. Use for discovering or enhancing prompts.
Checks Next.js compilation errors using a running Turbopack dev server after code edits. Fixes actionable issues before reporting complete. Replaces `next build`.
The OrderMgr API provides order creation, status management, and querying. Understanding the order lifecycle is essential for checkout implementation and order processing.
Orders progress through these statuses:
Basket → CREATED → NEW → (COMPLETED or CANCELLED or FAILED)
| Status | Description | Can Transition To |
|---|---|---|
CREATED | Order created, not yet placed | NEW, FAILED |
NEW | Order placed, awaiting fulfillment | OPEN, COMPLETED, CANCELLED, FAILED |
OPEN | Order in processing | COMPLETED, CANCELLED |
COMPLETED | Order fulfilled | - |
CANCELLED | Order cancelled | NEW (via undoCancel) |
FAILED | Order failed (payment, validation) | - (cannot be reopened) |
Important: Once an order reaches FAILED status, it cannot be reopened or cancelled. Use failOrder(order, true) to reopen the basket for retry instead.
var OrderMgr = require('dw/order/OrderMgr');
var Transaction = require('dw/system/Transaction');
var Status = require('dw/system/Status');
function createOrder(basket) {
var order;
Transaction.wrap(function() {
// Create order from basket (status: CREATED)
order = OrderMgr.createOrder(basket);
});
if (!order) {
return { error: true, message: 'Order creation failed' };
}
// Authorize payment
var paymentResult = authorizePayment(order);
if (!paymentResult.success) {
Transaction.wrap(function() {
OrderMgr.failOrder(order, true); // Reopen basket
});
return { error: true, message: 'Payment failed' };
}
// Place the order (status: CREATED → NEW)
var placeResult;
Transaction.wrap(function() {
placeResult = OrderMgr.placeOrder(order);
});
if (placeResult.error) {
return { error: true, message: 'Order placement failed' };
}
// Set confirmation status
Transaction.wrap(function() {
order.setConfirmationStatus(order.CONFIRMATION_STATUS_CONFIRMED);
});
return { error: false, order: order };
}
For SCAPI/headless, create the order before payment authorization:
var OrderMgr = require('dw/order/OrderMgr');
var Transaction = require('dw/system/Transaction');
// Step 1: Create order (before payment)
function createOrderAsync(basket, orderNo) {
var order;
Transaction.wrap(function() {
// Create with specific order number (for idempotency)
order = OrderMgr.createOrder(basket, orderNo);
});
return order;
}
// Step 2: After payment success, place the order
function placeOrderAfterPayment(order) {
Transaction.wrap(function() {
OrderMgr.placeOrder(order);
order.setConfirmationStatus(order.CONFIRMATION_STATUS_CONFIRMED);
order.setExportStatus(order.EXPORT_STATUS_READY);
});
}
// Step 2 (alt): Payment failed, fail the order
function failOrderAfterPayment(order) {
Transaction.wrap(function() {
OrderMgr.failOrder(order, false); // Don't reopen basket
});
}
| Method | Description |
|---|---|
createOrder(basket) | Create order with auto-generated number |
createOrder(basket, orderNo) | Create order with specific number |
createOrderNo() | Generate next order number |
createOrderSequenceNo() | Get next sequence number (for custom formatting) |
| Method | Description |
|---|---|
placeOrder(order) | Place order (CREATED → NEW) |
failOrder(order, reopenBasket) | Fail order (set to FAILED status) |
cancelOrder(order) | Cancel order (set to CANCELLED status) |
undoCancelOrder(order) | Revert cancelled order to NEW |
Note: There is no undoFailOrder() method. Failed orders cannot be reopened. Use failOrder(order, true) to reopen the basket for retry.
| Method | Description |
|---|---|
getOrder(orderNo) | Get order by number |
searchOrder(query, ...args) | Search for single order |
searchOrders(query, sortString, ...args) | Search for multiple orders |
queryOrder(query, ...args) | Query single order |
queryOrders(query, sortString, ...args) | Query multiple orders |
var OrderMgr = require('dw/order/OrderMgr');
var order = OrderMgr.getOrder('00001234');
if (order) {
var status = order.status.value;
var total = order.totalGrossPrice;
}
var OrderMgr = require('dw/order/OrderMgr');
// Search by customer email
var orders = OrderMgr.searchOrders(
'customerEmail = {0} AND status != {1}',
'creationDate desc',
'customer@example.com',
dw.order.Order.ORDER_STATUS_FAILED
);
while (orders.hasNext()) {
var order = orders.next();
// Process order
}
orders.close();
var OrderMgr = require('dw/order/OrderMgr');
var Calendar = require('dw/util/Calendar');
var startDate = new Calendar();
startDate.add(Calendar.DAY_OF_YEAR, -7);
var orders = OrderMgr.searchOrders(
'creationDate >= {0} AND status = {1}',
'creationDate desc',
startDate.time,
dw.order.Order.ORDER_STATUS_NEW
);
while (orders.hasNext()) {
var order = orders.next();
// Process order
}
orders.close();
var OrderMgr = require('dw/order/OrderMgr');
var Transaction = require('dw/system/Transaction');
var Order = require('dw/order/Order');
function cancelOrder(orderNo) {
var order = OrderMgr.getOrder(orderNo);
if (!order) {
return { error: true, message: 'Order not found' };
}
// Can only cancel NEW or OPEN orders
if (order.status.value !== Order.ORDER_STATUS_NEW &&
order.status.value !== Order.ORDER_STATUS_OPEN) {
return { error: true, message: 'Order cannot be cancelled' };
}
Transaction.wrap(function() {
OrderMgr.cancelOrder(order);
});
return { error: false };
}
var OrderMgr = require('dw/order/OrderMgr');
var Transaction = require('dw/system/Transaction');
function failOrder(order, reopenBasket) {
// reopenBasket: true = customer can retry checkout
// false = basket is lost
Transaction.wrap(function() {
OrderMgr.failOrder(order, reopenBasket);
});
}
Failed orders cannot be reopened. Instead, use failOrder(order, true) to reopen the basket:
var OrderMgr = require('dw/order/OrderMgr');
var Transaction = require('dw/system/Transaction');
// When payment fails, fail the order and reopen basket
function handlePaymentFailure(order) {
Transaction.wrap(function() {
// reopenBasket=true allows customer to retry checkout
OrderMgr.failOrder(order, true);
});
// Basket is now available again for the customer
return { error: true, message: 'Payment failed. Please try again.' };
}
For SCAPI integrations, use the failed_with_reopen status to fail an order while reopening the basket:
PATCH /checkout/orders/v1/organizations/{orgId}/orders/{orderNo}?siteId={siteId}
Authorization: Bearer {token}
Content-Type: application/json
{
"status": "failed_with_reopen"
}
This is equivalent to OrderMgr.failOrder(order, true) in Script API.
Cancelled orders can be reopened using undoCancelOrder():
var OrderMgr = require('dw/order/OrderMgr');
var Transaction = require('dw/system/Transaction');
var Order = require('dw/order/Order');
function reopenCancelledOrder(orderNo) {
var order = OrderMgr.getOrder(orderNo);
if (order.status.value !== Order.ORDER_STATUS_CANCELLED) {
return { error: true, message: 'Order is not cancelled' };
}
Transaction.wrap(function() {
// Revert to NEW status
OrderMgr.undoCancelOrder(order);
});
return { error: false, order: order };
}
| Property | Description |
|---|---|
orderNo | Order number |
status | Current order status |
confirmationStatus | Confirmation status |
exportStatus | Export status for OMS |
paymentStatus | Payment status |
shippingStatus | Shipping status |
customerEmail | Customer email |
customerName | Customer name |
totalGrossPrice | Order total (with tax) |
totalNetPrice | Order total (without tax) |
totalTax | Total tax amount |
creationDate | Order creation date |
productLineItems | Line items in order |
shipments | Order shipments |
paymentInstruments | Payment instruments |
Use the dw.order.createOrderNo hook for custom order number generation:
// hooks.json
{
"hooks": [
{
"name": "dw.order.createOrderNo",
"script": "./hooks/orderNo.js"
}
]
}
// hooks/orderNo.js
var OrderMgr = require('dw/order/OrderMgr');
var Site = require('dw/system/Site');
exports.createOrderNo = function() {
var seqNo = OrderMgr.createOrderSequenceNo();
var prefix = Site.current.ID.toUpperCase();
var year = new Date().getFullYear();
return prefix + '-' + year + '-' + seqNo;
};
failOrder(order, true) to let customers retry| Scenario | Solution |
|---|---|
| Basket is empty | Validate basket before createOrder() |
| Invalid basket | Check for missing shipping/billing addresses |
| Payment failed | Use failOrder(order, true) to reopen basket |
| Order number exists | Use auto-generated numbers or validate uniqueness |
| Status transition invalid | Check current status before calling status methods |