order.created

Fired when a new order is placed in the store.

Event Structure

{
  "event_type": "order.created",
  "payload": { ... }
}

Payload

{
  "_id": "6764a1b2c3d4************",
  "qid": "qid://qumra/Order/01JDXM************",
  "app": "6720ff8e4a21************",
  "account": "674b3c11d9a0************",
  "market": "671a88f3bc45************",
  "marketSnapshot": {
    "name": "Saudi Arabia",
    "code": "sa",
    "currency": "SAR",
    "countries": ["SA"]
  },
  "totalPrice": 350,
  "totalPriceWithTax": 398.75,
  "handel": "#1042",
  "tax": "67205c8ab1c2************",
  "taxAmount": 48.75,
  "totalCompareAtPrice": 400,
  "shippingAddress": "6764a0ff77e1************",
  "paymentMethod": "67210def44a9************",
  "manualPayment": null,
  "paymentType": "gateway",
  "channel": "STORE",
  "salesLead": null,
  "items": [
    "6764a1b2c3d5************",
    "6764a1b2c3d6************"
  ],
  "status": "6764a1b2c3d7************",
  "orderStatus": "pending",
  "financialStatus": "paid",
  "fulfillmentStatus": "unfulfilled",
  "deleted": false,
  "paidAt": "2025-02-24T14:30:05.000Z",
  "isFastOrder": false,
  "freeze": true,
  "priceWithShipping": 375,
  "shippingPrice": 25,
  "type": "account",
  "shipping": {
    "carrier": "mylerz",
    "barCode": "MLZ-2025-********",
    "reference": "REF-0001****",
    "mylerzWarehouseId": "WH-RYD-***",
    "status": "pending"
  },
  "currency": {
    "code": "SAR",
    "symbol": "ر.س",
    "rate": 1
  },
  "createdAt": "2025-02-24T14:30:00.000Z",
  "updatedAt": "2025-02-24T14:30:00.000Z"
}

Payload Fields

Field	Type	Description
_id	string	MongoDB ObjectId of the order
qid	string	Qumra QID (qid://qumra/Order/<ULID>)
app	string	Store ID that owns the order
account	string | null	Customer account ID (null for guest/lead orders)
market	string | null	Market ID
marketSnapshot	object	Frozen copy of the market at order time (currency, countries, etc.)
totalPrice	number	Order subtotal (before tax and shipping)
totalPriceWithTax	number	Order total including tax
handel	string	Human-readable order number (e.g. #1042)
tax	string | null	Tax record ID
taxAmount	number	Total tax amount
totalCompareAtPrice	number	Sum of compare-at prices (for showing savings)
shippingAddress	string	Shipping address ID
paymentMethod	string | null	Payment method ID (gateway)
manualPayment	string | null	Manual payment ID (bank transfer, etc.)
paymentType	string	One of gateway, manual, cash
channel	string	Order channel: STORE or POS
salesLead	string | null	Sales lead ID if created from a lead
items	string[]	Array of order item IDs
status	string	Order status record ID
orderStatus	string	Lifecycle status (pending, confirmed, cancelled, ...)
financialStatus	string	Payment status (unpaid, paid, refunded, ...)
fulfillmentStatus	string	Fulfillment status (unfulfilled, partial, fulfilled)
deleted	boolean	Soft-delete flag
paidAt	string | null	ISO 8601 timestamp when payment was captured
isFastOrder	boolean	Whether this was a fast-checkout order
freeze	boolean	Whether the order is frozen (post-creation hold)
priceWithShipping	number	Total including shipping (before tax)
shippingPrice	number	Shipping cost
type	string	Order origin type: lead, account, or guest
shipping	object | null	Shipping/carrier metadata
shipping.carrier	string	Carrier name (e.g. mylerz, aramex)
shipping.barCode	string	Shipment bar code
shipping.reference	string	Carrier reference number
shipping.mylerzWarehouseId	string	Mylerz warehouse ID (when carrier is Mylerz)
shipping.status	string	Carrier-side status
currency	object	Currency snapshot (code, symbol, rate)
createdAt	string	ISO 8601 creation timestamp
updatedAt	string	ISO 8601 last update timestamp

info

Line items are referenced by ID in the items array. To fetch their full data (product, variant, quantity, price), call the orders API with the order ID.

Example Handler

app/routes/webhooks.orders.tsx

import { authenticate } from "~/qumra.server";

export async function action({ request }: { request: Request }) {
  const { payload, topic, storeId } =
    await authenticate.admin(request);

  if (topic === "order.created") {
    console.log(`New order ${payload.handel} (${payload._id})`);
    console.log(`Total: ${payload.totalPriceWithTax} ${payload.currency?.code}`);
    console.log(`Items: ${payload.items.length}`);

    // Send confirmation email, sync to ERP, update analytics, etc.
  }

  return Response.json({ success: true });
}