Introduction

This section defines the complete schemas for every order-related event on Webround Commerce.

Why listen to order events

Integrating order events allows you to manage the following in real time:

Issuing electronic invoices upon payment status changes.
Logistics processing and shipment tracking.
Managing Stripe disputes and refunds.
Inventory synchronization via order line items.

Complete Events and Payloads Table

Event	Payload Schema	JSON Example
`order.created`	Order Data Schema	Link
`order.updated`	Order Data Schema	-
`order.canceled`	Order Data Schema	-
`order.paid`	Order Data Schema	-
`order.payment-failed`	Order Data Schema	-
`order.payment-authorized`	Order Data Schema	-
`order.payment-canceled`	Order Data Schema	-
`order.payment-partially-funded`	Order Data Schema	-
`order.refund.updated`	Order Data Schema	-
`order.dispute.updated`	Order Data Schema	-
`order.deleted`	Order Deleted Schema	Link
`order-item.created`	Order Item Created Schema	Link
`order-item.updated`	Order Item Updated Schema	-
`order-item.deleted`	Order Item Deleted Schema	Link
`order.promotion-usage.replaced`	Promotion Replaced Schema	Link

Data Types

Base Types

Type	Format	Description
uuid	`string`	Universally unique identifier in UUID v4 format
isoDate	`string`	Date and time string in ISO 8601 format
amount	`string`	Decimal numeric string (up to 8 decimal places)

Address Schema (`addressSchema`)

Used for defining billingAddress and shippingAddress.

Field	Type	Notes
fullName	`string - null`	Optional
company	`string - null`	Optional
addressLine1	`string`	Required
addressLine2	`string - null`	Optional
city	`string`	Required
postalCode	`string`	Required
countryCode	`string`	Required (ISO 3166-1 alpha-2)
phone	`string - null`	Optional
province	`string - null`	Optional
additionalInfo	`string - null`	Optional

Order Schema (`orderDataSchema`)

Field	Type	Notes
id	`uuid`	Required
storeId	`uuid`	Required
customerId	`uuid`	Required
customerEmail	`string`	Required (Email)
paymentStatus	`string`	Required
shippingStatus	`string`	Required
amount	`amount`	Required
currencyCode	`string`	Required
shippingCost	`amount - null`	Optional
billingAddress	`addressSchema - null`	Optional
shippingAddress	`addressSchema - null`	Optional
shippingTrackingUrl	`string - null`	Optional (URL)
stripePaymentIntentId	`string - null`	Optional
stripeSubscriptionId	`string - null`	Optional
stripeCheckoutSessionId	`string - null`	Optional
stripeInvoiceId	`string - null`	Optional
stripeInvoiceUrl	`string - null`	Optional (URL)
stripeAccountId	`string - null`	Optional
amountCapturable	`amount - null`	Optional
partialFundingAmount	`amount - null`	Optional
disputeStatus	`string`	Required
refundStatus	`string`	Required
stripeDisputeId	`string - null`	Optional
lastRefundId	`string - null`	Optional
refundAmount	`amount - null`	Optional
createdAt	`isoDate`	Optional
updatedAt	`isoDate`	Optional

Order Schema Example

{
    "envelopeId": "e17d2354-580c-44f7-9f46-e4eed2cdff14",
    "eventType": "order.created",
    "initiatedBy": null,
    "storeId": "a7734977-c5b1-49a4-911c-0b0bf745bd4f",
    "occurredAt": "2026-02-17T19:36:46.552Z",
    "data": {
        "id": "3e29362a-da1b-4641-a656-5fe6b9f3a836",
        "storeId": "a7734977-c5b1-49a4-911c-0b0bf745bd4f",
        "customerId": "00e72027-3672-4c12-a78f-e9ff744a0892",
        "customerEmail": "[email protected]",
        "paymentStatus": "created",
        "shippingStatus": "unassigned",
        "amount": "178.12000000",
        "currencyCode": "EUR",
        "shippingCost": "12.20000000",
        "billingAddress": {
            "fullName": "John Doe",
            "company": "Webround",
            "addressLine1": "Via Roma 123",
            "addressLine2": "n. 4",
            "city": "Milano",
            "postalCode": "20100",
            "countryCode": "IT",
            "phone": "+IT 1234567890",
            "province": "Italy",
            "additionalInfo": "info..."
        },
        "shippingAddress": {
            "fullName": "John Doe",
            "company": "Webround",
            "addressLine1": "Via Roma 123",
            "addressLine2": "n. 4",
            "city": "Milano",
            "postalCode": "20100",
            "countryCode": "IT",
            "phone": "+IT 1234567890",
            "province": "Italy",
            "additionalInfo": "info..."
        },
        "shippingTrackingUrl": null,
        "stripePaymentIntentId": null,
        "stripeSubscriptionId": null,
        "stripeCheckoutSessionId": "cs_...",
        "stripeInvoiceId": null,
        "stripeInvoiceUrl": null,
        "stripeAccountId": "acct_...",
        "amountCapturable": null,
        "partialFundingAmount": null,
        "disputeStatus": "none",
        "refundStatus": "none",
        "stripeDisputeId": null,
        "lastRefundId": null,
        "refundAmount": null,
        "createdAt": "2026-02-17T19:36:45.498Z",
        "updatedAt": "2026-02-17T19:36:45.498Z"
    },
    "eventId": "5b7137c3-d261-40d8-aeb0-ad4831209b4b"
}

Deleted Order Schema (`order.deleted`)

Field	Type	Notes
orderId	`uuid`	Required (ID of the deleted order)

Deleted Order Schema Example

{
    "envelopeId": "e17d2354-580c-44f7-9f46-e4eed2cdff14",
    "eventType": "order.deleted",
    "initiatedBy": "[email protected]",
    "storeId": "a7734977-c5b1-49a4-911c-0b0bf745bd4f",
    "occurredAt": "2026-02-17T19:36:46.552Z",
    "data": {
        "orderId": "00e72027-3672-4c12-a78f-e9ff744a0892"
    },
    "eventId": "5b7137c3-d261-40d8-aeb0-ad4831209b4b"
}

Created Order Line Item Schema (`order-item.created`)

Field	Type	Notes
id	`uuid`	Required
orderId	`uuid`	Required
skuId	`uuid`	Required
productId	`uuid`	Required
variantId	`uuid`	Required
coverUrl	`string - null`	Optional (URL)
skuCode	`string`	Required
quantity	`number`	Required (Positive integer)
deliveryMethod	`string`	Required
unitNet	`amount`	Required
unitGross	`amount`	Required
unitTax	`amount`	Required
totalNet	`amount`	Required
totalGross	`amount`	Required
totalTax	`amount`	Required
appliedTaxRate	`number`	Required
taxBehavior	`string`	Required
stripePriceId	`string - null`	Optional
stripeProductId	`string - null`	Optional
stripeTaxCodeId	`string - null`	Optional
createdAt	`isoDate`	Required
updatedAt	`isoDate`	Required

Created Order Line Item Schema Example

{
    "envelopeId": "5039a305-7b68-4ef9-8956-40bc263bda36",
    "eventType": "order-item.created",
    "initiatedBy": null,
    "storeId": "a7734977-c5b1-49a4-911c-0b0bf745bd4f",
    "occurredAt": "2026-02-17T19:36:46.562Z",
    "data": {
        "id": "f957722a-92a1-4876-8e47-bda6f4944e61",
        "orderId": "3e29362a-da1b-4641-a656-5fe6b9f3a836",
        "skuId": "01e1c35f-8cb2-4c35-bd8b-1fa42dbc6a8c",
        "productId": "5aa07d67-33e0-459c-ba9d-86b68d202e18",
        "variantId": "1057deeb-024f-4a5b-9365-a3131aeb7826",
        "coverUrl": "https://cdn.webround.com/asset.png",
        "skuCode": "T-Shirt",
        "quantity": 1,
        "deliveryMethod": "shipping",
        "unitNet": "17.00000000",
        "unitGross": "20.74000000",
        "unitTax": "3.74000000",
        "totalNet": "17.00000000",
        "totalGross": "20.74000000",
        "totalTax": "3.74000000",
        "appliedTaxRate": 22,
        "taxBehavior": "useWrTax",
        "stripePriceId": null,
        "stripeProductId": null,
        "stripeTaxCodeId": null,
        "createdAt": "2026-02-17T19:36:45.498Z",
        "updatedAt": "2026-02-17T19:36:45.498Z"
    },
    "eventId": "5b6520ae-eb78-4510-a32a-55ef1fe66d3d"
}

Updated Order Line Item Schema (`order-item.updated`)

Field	Type	Notes
id	`uuid`	Required
orderId	`uuid`	Required
skuId	`uuid`	Required
productId	`uuid`	Required
variantId	`uuid`	Required
coverUrl	`string - null`	Optional (URL)
skuCode	`string`	Required
quantity	`number`	Required
deliveryMethod	`string`	Required
unitNet	`amount`	Required
unitGross	`amount`	Required
unitTax	`amount`	Required
totalNet	`amount`	Required
totalGross	`amount`	Required
totalTax	`amount`	Required
appliedTaxRate	`number`	Required
taxBehavior	`string`	Required
updatedAt	`isoDate`	Required

Deleted Order Line Item Schema (`order-item.deleted`)

Field	Type	Notes
orderId	`uuid`	Required
orderItemId	`uuid`	Required (ID of the deleted line item)

Deleted Order Line Item Schema Example

{
    "envelopeId": "5039a305-7b68-4ef9-8956-40bc263bda36",
    "eventType": "order-item.deleted",
    "initiatedBy": null,
    "storeId": "a7734977-c5b1-49a4-911c-0b0bf745bd4f",
    "occurredAt": "2026-02-17T19:36:46.562Z",
    "data": {
        "orderId": "3e29362a-da1b-4641-a656-5fe6b9f3a836",
        "orderItemId": "f957722a-92a1-4876-8e47-bda6f4944e61"
    },
    "eventId": "5b6520ae-eb78-4510-a32a-55ef1fe66d3d"
}

Replaced Promotion Schema (`order.promotion-usage.replaced`)

Field	Type	Notes
orderId	`uuid`	Required
orderItemId	`uuid[]`	Required (Array of affected order line item IDs)

Replaced Promotion Schema Example

{
    "envelopeId": "5039a305-7b68-4ef9-8956-40bc263bda36",
    "eventType": "order.promotion-usage.replaced",
    "initiatedBy": null,
    "storeId": "a7734977-c5b1-49a4-911c-0b0bf745bd4f",
    "occurredAt": "2026-02-17T19:36:46.562Z",
    "data": {
        "orderId": "3e29362a-da1b-4641-a656-5fe6b9f3a836",
        "orderItemId": ["f957722a-92a1-4876-8e47-bda6f4944e61"]
    },
    "eventId": "5b6520ae-eb78-4510-a32a-55ef1fe66d3d"
}

Why listen to order events

Complete Events and Payloads Table

Data Types​

Base Types​

Address Schema (addressSchema)​

Order Schema (orderDataSchema)​

Order Schema Example​

Deleted Order Schema (order.deleted)​

Deleted Order Schema Example​

Created Order Line Item Schema (order-item.created)​

Created Order Line Item Schema Example​

Updated Order Line Item Schema (order-item.updated)​

Deleted Order Line Item Schema (order-item.deleted)​

Deleted Order Line Item Schema Example​

Replaced Promotion Schema (order.promotion-usage.replaced)​

Replaced Promotion Schema Example​