Ana içeriğe geç

Introduction

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

🎯 What does this module do?​

The Orders module lets you create, manage, and track customer orders — from checkout to payment to fulfillment. You build the cart UI; this module turns the cart into an order, previews totals (discounts, coupons, bonuses), tracks status, and handles refund requests.

Orders live inside order storages (containers you configure in the admin panel) and are referenced by a storage marker. Payment is delegated to the gateway configured for the chosen payment account — see the Payments module.

🚀 Quickstart​

Initialize the module from defineOneEntry:


const { Orders } = defineOneEntry(
  "your-project-url", {
    "token": "your-app-token"
  }
);

Create an order in a storage and read back the result (auth required):

// Create an order in the "order_storage_1" storage.
const order = await Orders.createOrder("order_storage_1", {
  formIdentifier: "orderForm",
  paymentAccountIdentifier: "cash",
  formData: [],
  products: [{ productId: 2957, quantity: 2 }],
});

console.log(order.id, order.totalSum, order.statusIdentifier);
// 179 "300.00" "inProgress"

✨ Key Concepts​

What is an Order?​

An Order is a customer purchase transaction. Each order object carries:

  • id — order identifier
  • storageId — the order storage it belongs to
  • formIdentifier / formData — the order form and the data the customer submitted
  • products — line items (productId, 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

Order Structure​

{
  id: 179,
  storageId: 1,
  createdDate: '2025-07-03T00:43:02.908Z',
  statusIdentifier: 'inProgress',
  formIdentifier: 'orderForm',
  formData: [
    { marker: 'order_name', type: 'string', value: 'Ivan' }
  ],
  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: true,
}

Order storage vs. individual orders​

An order storage is a container that groups related orders (for example, orders from a specific form or sales channel). Individual orders are the actual transactions inside a storage. You address a storage by its marker and an order inside it by marker + id.

Order statuses​

Each storage defines its own status set; an order's current state is in statusIdentifier. Fetch the available statuses for a storage with getAllStatusesByStorageMarker(), and update an order's status with updateOrderByMarkerAndId().

📋 What You Need to Know​

Orders are built from cart data​

You provide the order form data and the line items; OneEntry computes totals. To create an order you pass:

  1. formIdentifier — the order form
  2. formData — the customer's submitted form fields
  3. products — line items (productId, quantity, optional signedPrice)
  4. paymentAccountIdentifier — how the customer will pay

What the module does and doesn't do​

  • ✅ Create orders from cart data, preview totals, update status, manage refund requests
  • ✅ Delegate payment to the gateway via the payment session / paymentUrl
  • ❌ Does not provide the shopping cart UI — you build that
  • ❌ Does not store raw card data — payment is handled by the gateway

Refunds​

Refund handling lives in the Orders module: request a refund with createRefundRequest(), list an order's refund requests with getRefunds(), and cancel one with cancelRefundRequest().

📊 Quick Reference Table​

MethodDescription
createOrder() 🔐Create new order
getAllOrdersByMarker() 🔐Get all orders for a storage (paginated)
getOrdersStorageByMarker() 🔐Get one order storage object by marker.
getAllOrdersStorage() 🔐Getting all order storage objects.
getOrderByMarkerAndId() 🔐Getting one order by marker and id from the order storage object created by the user.
updateOrderByMarkerAndId() 🔐Update one order by marker and id from the order storage object created by the user.
previewOrder() 🔐Preview order totals, discounts and coupons before creating it.
getAllStatusesByStorageMarker()Get all order statuses for a storage marker.
getRefunds()Get all refund requests for an order.
createRefundRequest()Create a refund request for an order.
cancelRefundRequest()Cancel a refund request for an order.

🔐 = Requires authorization

Fixed product price (signedPrice)​

signedPrice is a signed token that locks a product's price. When it is present on an order line, the server charges that exact fixed price instead of looking the price up again — so the amount the customer saw in the catalog or cart is the amount they pay.

signedPrice — type string

The signed price of the product is obtained along with the product data when signPrice is set.

Where to get it​

You don't generate signedPrice yourself — it arrives inside the product data, but only when 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 the recommendation-method argument (getCartSimilar, getRecentlyViewed, …).

Each returned product then contains a signedPrice string. Read more in the Fixing the price (signPrice) section of the Products module.

How to use it​

Pass the token back in each product of the createOrder() body. The order then keeps the fixed price:


const { items } = await Products.getProducts([], "en_US", {
  signPrice: "my-order"
});

const body = {
  formIdentifier: "orderForm",
  paymentAccountIdentifier: "cash",
  formData: [],
  products: [
    {
      productId: items[0].id,
      quantity: 2,
      signedPrice: items[0].signedPrice
    }
  ]
};

const order = await Orders.createOrder("my-order", body);

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

❓ Common Questions (FAQ)​

How do I create an order with multiple products?​

Pass an array of product objects in the products field of the order body. Each item needs productId and quantity (and optionally signedPrice). The total sum is calculated automatically.

Can I update an order after it's been created?​

Yes — use updateOrderByMarkerAndId() to modify order details such as status, form data, or products. Be cautious changing items or totals once payment is in progress.

How do I track order status changes?​

Read the statusIdentifier field for the current state, and fetch the storage's available statuses with getAllStatusesByStorageMarker(). You can also use the Events module to react to changes.

What's the difference between order storage and individual orders?​

Order storage is a container that groups related orders (e.g. orders from a specific form or sales channel). Individual orders are the transactions within that storage. Use markers to identify and organize storages.

How do I handle order cancellations and refunds?​

Update the order status with updateOrderByMarkerAndId(). For refunds, use the Orders refund methods: createRefundRequest() to request one, getRefunds() to list an order's requests, and cancelRefundRequest() to cancel one.

🎓 Best Practices​

  • Preview before creating — call previewOrder() to show discounts, coupons, and bonuses in the checkout summary.
  • Use signedPrice when products feed into checkout so the price can't drift between browsing and ordering.
  • Authenticate first — order create/read/update methods require an authorized user (see AuthProvider).
  • Paginate order lists (offset + limit) — don't load every order at once.
  • Reference storages and forms by marker, not by display name — markers are stable.

🔗 Related Documentation​