Order
The Order entity is the heart of your store's accounting and customer purchase history. It represents the formalization of a commercial transaction, recording the financial, logistical, and personal details involved at the exact moment of the sale.
Every order is inextricably linked to a Customer (who must be registered in the system before the order is created) and contains the fundamental data for billing and delivery.
Anatomy of an Order
An order in Webround Commerce aggregates several critical pieces of information:
- Financial Data: The grand total (
amount), shipping costs, and the currency used. - Logistics: Shipping and billing addresses, shipping status, and the tracking URL for the customer.
- Payment Status: Monitoring the transaction lifecycle (
created,paid,failed,refunded, etc.). - Stripe Integration: Dedicated fields to map Stripe checkout session IDs, payment intents, subscriptions, and generated invoices.
- Post-Sale Management: Tracking of refunds and disputes.
Definition
| Property | Type | Description |
|---|---|---|
| id | string (UUID) | Unique identifier of the order. |
| storeId | string (UUID) | ID of the store where the purchase was made. |
| customerId | string (UUID) | ID of the customer who placed the order. |
| amount | string (Decimal) | Grand total of the order (gross). |
| currencyCode | string | ISO currency code (e.g., EUR). |
| paymentStatus | string | Payment lifecycle status (e.g., paid, pending, failed). |
| shippingStatus | string | Shipping status (e.g., unassigned, shipped, delivered). |
| stripeInvoiceUrl | string (URL) | Direct link to the Stripe-generated invoice. |
| shippingTrackingUrl | string | null | Carrier tracking URL, set manually after dispatch. |
| items | OrderItem[] | Line items included in the order. |
| createdAt | string (ISO 8601) | Order creation timestamp. |
| updatedAt | string (ISO 8601) | Last update timestamp. |
Order Items
An order is more than just a financial total — it contains the details of the items purchased through Order Items. Each order line specifies the exact Variant purchased, the quantity, and the pricing snapshot frozen at the time of sale.
Definition
| Property | Type | Description |
|---|---|---|
| productId | string (UUID) | ID of the parent product. |
| variantId | string (UUID) | ID of the specific Variant purchased. |
| variantName | string | Display name of the variant at time of sale (e.g., "Black Cap"). |
| coverUrl | string (URL) | Cover image URL of the product at time of sale. |
| quantity | number | Quantity purchased for this line. |
| deliveryMethod | DeliveryMethod | Delivery method chosen for this item. |
| appliedTaxRate | number | VAT rate applied (e.g., 22). |
| unitNet | string (Decimal) | Unit net price (tax excluded). |
| unitGross | string (Decimal) | Unit gross price (tax included). |
| totalNet | string (Decimal) | Line total net (unitNet × quantity). |
| totalGross | string (Decimal) | Line total gross (unitGross × quantity). |
Financial values (amount, unitNet, etc.) are returned as string to preserve decimal precision during financial operations, avoiding the floating-point rounding errors typical of JavaScript's number type.
Management Modes
Webround Commerce offers two distinct approaches to order management, adapting to both fully automated workflows and manual or custom needs.
1. Automatic Mode (Managed by Stripe)
In this mode, Webround acts as an intelligent bridge to Stripe. The system creates the order the moment a user starts a checkout session.
- Workflow: Webround receives real-time events from Stripe via webhooks and updates the order accordingly — including successful payments, anti-fraud holds, and failures.
- Data Integrity: Since the transaction is certified by Stripe, totals, quantities, and Order Items cannot be modified manually. This data is locked to reflect the actual movement of money.
- What you can manage: You have full control over the logistical side — specifically updating the Shipping Status and entering the Tracking URL.
2. Manual Mode (Total Flexibility)
This mode transforms Webround into a powerful management tool free from automation constraints. It is ideal for tracking sales made in your physical store, phone orders, or bulk imports via API from external systems.
- Autonomy: Stripe does not intervene. You can define prices, items, and statuses as you prefer.
- Modifiability: There are no locks on changes. You can update any field of the order at any time to reflect manual operations or offline corrections.
In automatic mode, the creation of an order does not necessarily coincide with a successful payment. The order is born when the user shows the intention to purchase (opening the checkout session). This allows you to monitor initiated checkouts and analyze potential bottlenecks in the conversion process.