Orders

Create and track customer orders across the full checkout, payment, and fulfillment lifecycle.

More information about the module's user interface https://doc.oneentry.cloud/docs/category/orders (opens in a new tab)

---

The Orders module turns a cart into an order, previews totals (discounts, coupons, bonuses), tracks the order status and handles refund requests. The cart UI is yours to build.

Orders live in order storages: containers you configure in the admin panel and reference by marker. Payment goes through the gateway configured for the chosen payment account; see the Payments module.

Quickstart

Initialize the module from defineOneEntry:

const {  } = defineOneEntry(
  , {
    
  }
);

Create an order in a storage and read back the result (this example uses a signed-in user):

// Create an order in the "my_order" storage.
const order = await Orders.createOrder("my_order", {
  formIdentifier: "orderForm",
  paymentAccountIdentifier: "cash",
  formData: [],
  products: [{ productId: 2957, quantity: 2 }],
});
if ('statusCode' in order) throw new Error(order.message);

console.log(order.id, order.totalSum, order.statusIdentifier);
// 179 285 "inProgress-payment"

Order object

Read methods (getOrderByMarkerAndId(), getOrderById(), getAllOrdersByMarker()) return orders in this shape (IOrderByMarkerEntity). createOrder() and updateOrderByMarkerAndId() return a shorter IBaseOrdersEntity.

{
  id: 179,
  storageId: 1,
  createdDate: '2025-07-03T00:43:02.908Z',
  statusIdentifier: 'inProgress',
  formIdentifier: 'orderForm',
  formData: [
    { marker: 'order_name', type: 'string', value: 'John' }
  ],
  attributeSetIdentifier: 'order_form',
  totalSum: '300.00',
  currency: 'USD',
  paymentAccountIdentifier: 'cash',
  paymentAccountLocalizeInfos: { title: 'Cash' },
  paymentUrl: null,
  products: [
    {
      id: 2957,
      title: 'Cosmo',
      sku: null,
      previewImage: null,
      price: 150,
      quantity: 2,
      isGift: false,
    },
  ],
  isCompleted: false,
}

The fields you'll use most:

• id: order identifier
• storageId: the order storage the order belongs to
• formIdentifier / formData: the order form and the data the customer submitted
• products: line items (id, title, quantity, price, …)
• totalSum / currency: order total and currency
• paymentAccountIdentifier: the chosen payment account
• paymentUrl: gateway checkout link, or null
• statusIdentifier / isCompleted: current state
• createdDate: timestamp

Storages and statuses

An order storage groups related orders, for example orders from a specific form or sales channel. You address a storage by its marker and an order inside it by marker and id. Markers are stable, so reference storages and forms by marker rather than by display name.

Each storage defines its own set of statuses, and an order's current state is in statusIdentifier. Get the statuses available in a storage with getAllStatusesByStorageMarker(), and change an order's status with updateOrderByMarkerAndId(). To react to status changes, use the Events module.

Creating an order

You provide the form data and the line items; OneEntry calculates the total. To create an order, pass:

1. formIdentifier: the order form
2. formData: the fields the customer submitted
3. products: an array of line items, each with productId, quantity and an optional signedPrice
4. paymentAccountIdentifier: how the customer will pay

Call previewOrder() first to show discounts, coupons and bonuses in the checkout summary. Read and update methods require an authenticated user (see AuthProvider). createOrder() also works for guests if the guest user group has permission. Paginate order lists with offset and limit instead of loading every order at once.

The module doesn't store raw card data: payment is handled by the gateway, through the payment session or paymentUrl.

You can change an order after it's created with updateOrderByMarkerAndId(): its status, form data or products. Be careful changing items or totals once payment is in progress.

Cancellations and refunds

To cancel an order, update its status with updateOrderByMarkerAndId(). Refunds are handled in this module: request one with createRefundRequest(), list an order's refund requests with getRefunds(), and cancel one with cancelRefundRequest().

---

Methods

Method	Description
createOrder()	Create a new order
getAllOrdersByMarker() 🔐	Get all orders in a storage (paginated)
getOrdersStorageByMarker() 🔐	Get an order storage by marker
getAllOrdersStorage() 🔐	Get all order storages
getOrderByMarkerAndId() 🔐	Get one of the user's orders by storage marker and id
getOrderById() 🔐	Get one of the user's orders by id, without the storage marker
updateOrderByMarkerAndId() 🔐	Update one of the user's orders by storage marker and id
previewOrder()	Preview order totals, discounts and coupons before creating the order
getAllStatusesByStorageMarker() 🔐	Get all order statuses of a storage
getRefunds() 🔐	Get all refund requests for an order
createRefundRequest() 🔐	Create a refund request for an order
cancelRefundRequest() 🔐	Cancel a refund request for an order
getOrdersByVectorSearch() 🔐	Semantic (vector) search over the authenticated user's orders

🔐 = Requires authorization

---

Fixed product price (signedPrice)

signedPrice is a signed token that locks a product's price. When an order line carries it, the server charges that fixed price instead of looking the price up again, so the customer pays the amount they saw in the catalog or cart. Use it whenever products feed into checkout, so the price can't drift between browsing and ordering.

Where to get it

You don't generate signedPrice yourself. It comes inside the product data, but only if you requested the products with the signPrice parameter set to your order storage marker:

• Products module: pass signPrice in userQuery (getProducts, getProductsByPageUrl, …).
• Blocks module: pass signPrice as an argument of the recommendation methods (getCartSimilar, getRecentlyViewed, …).

Each returned product then contains a signedPrice string. See Fixing the price (signPrice) for details.

How to use it

Pass the token back in each product of the createOrder() body, and the order keeps the fixed price:

const products = await Products.([], "en_US", {
  signPrice: "my_order"
});
if ('statusCode' in products) throw new Error(products.message);
const { items } = products;
const  = {
  formIdentifier: "orderForm",
  paymentAccountIdentifier: "cash",
  formData: [],
  products: [
    {
      productId: items[0].id,
      quantity: 2,
      signedPrice: items[0].
    }
  ]
};
const order = await Orders.createOrder("my_order", body);

Without signedPrice, the order is created with the product's current price at checkout time.

---

Related

• Products: products available for purchase
• Payments: payment sessions for orders
• Users: the customers who place orders
• AuthProvider: authorization for order methods
• Events: order status notifications