Introduzione

Questa sezione definisce gli schemi completi per ogni evento relativo agli ordini su Webround Commerce.

Perché ascoltare gli eventi sugli ordini

L'integrazione degli eventi sugli ordini consente di gestire in tempo reale:

Emissione di fatture elettroniche al cambio di stato del pagamento.
Elaborazione logistica e tracking delle spedizioni.
Gestione delle dispute e dei rimborsi Stripe.
Sincronizzazione dell'inventario tramite righe d'ordine.

Tabella Completa Eventi e Payload

Evento	Payload Schema	Esempio JSON
`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

Tipi di dato

Tipi Base

Tipo	Definizione Zod	Descrizione
uuid	`string`	Stringa in formato UUID v4 unico universale
isoDate	`string`	Stringa data e ora in formato ISO 8601
amount	`string`	Stringa numerica decimale (fino a 8 decimali)

Schema Indirizzo (`addressSchema`)

Utilizzato per la definizione di billingAddress e shippingAddress.

Campo	Tipo	Note
fullName	`string - null`	Opzionale
company	`string - null`	Opzionale
addressLine1	`string`	Obbligatorio
addressLine2	`string - null`	Opzionale
city	`string`	Obbligatorio
postalCode	`string`	Obbligatorio
countryCode	`string`	Obbligatorio (ISO 3166-1 alpha-2)
phone	`string - null`	Opzionale
province	`string - null`	Opzionale
additionalInfo	`string - null`	Opzionale

Schema Ordine (`orderDataSchema`)

Campo	Tipo	Note
id	`uuid`	Obbligatorio
storeId	`uuid`	Obbligatorio
customerId	`uuid`	Obbligatorio
customerEmail	`string`	Obbligatorio (Email)
paymentStatus	`string`	Obbligatorio
shippingStatus	`string`	Obbligatorio
amount	`amount`	Obbligatorio
currencyCode	`string`	Obbligatorio
shippingCost	`amount - null`	Opzionale
billingAddress	`addressSchema - null`	Opzionale
shippingAddress	`addressSchema - null`	Opzionale
shippingTrackingUrl	`string - null`	Opzionale (URL)
stripePaymentIntentId	`string - null`	Opzionale
stripeSubscriptionId	`string - null`	Opzionale
stripeCheckoutSessionId	`string - null`	Opzionale
stripeInvoiceId	`string - null`	Opzionale
stripeInvoiceUrl	`string - null`	Opzionale (URL)
stripeAccountId	`string - null`	Opzionale
amountCapturable	`amount - null`	Opzionale
partialFundingAmount	`amount - null`	Opzionale
disputeStatus	`string`	Obbligatorio
refundStatus	`string`	Obbligatorio
stripeDisputeId	`string - null`	Opzionale
lastRefundId	`string - null`	Opzionale
refundAmount	`amount - null`	Opzionale
createdAt	`isoDate`	Opzionale
updatedAt	`isoDate`	Opzionale

Esempio Schema Ordine

{
    "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": "Italia",
        "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": "Italia",
        "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"
}

Schema Ordine Eliminato (`order.deleted`)

Campo	Tipo	Note
orderId	`uuid`	Obbligatorio (ID dell'ordine eliminato)

Esempio Schema Ordine Eliminato

{
    "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"
}

Schema Riga Ordine Creata (`order-item.created`)

Campo	Tipo	Note
id	`uuid`	Obbligatorio
orderId	`uuid`	Obbligatorio
skuId	`uuid`	Obbligatorio
productId	`uuid`	Obbligatorio
variantId	`uuid`	Obbligatorio
coverUrl	`string - null`	Opzionale (URL)
skuCode	`string`	Obbligatorio
quantity	`number`	Obbligatorio (Intero positivo)
deliveryMethod	`string`	Obbligatorio
unitNet	`amount`	Obbligatorio
unitGross	`amount`	Obbligatorio
unitTax	`amount`	Obbligatorio
totalNet	`amount`	Obbligatorio
totalGross	`amount`	Obbligatorio
totalTax	`amount`	Obbligatorio
appliedTaxRate	`number`	Obbligatorio
taxBehavior	`string`	Obbligatorio
stripePriceId	`string - null`	Opzionale
stripeProductId	`string - null`	Opzionale
stripeTaxCodeId	`string - null`	Opzionale
createdAt	`isoDate`	Obbligatorio
updatedAt	`isoDate`	Obbligatorio

Esempio Schema Riga Ordine Creata

{
    "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"
}

Schema Riga Ordine Aggiornata (`order-item.updated`)

Campo	Tipo	Note
id	`uuid`	Obbligatorio
orderId	`uuid`	Obbligatorio
skuId	`uuid`	Obbligatorio
productId	`uuid`	Obbligatorio
variantId	`uuid`	Obbligatorio
coverUrl	`string - null`	Opzionale (URL)
skuCode	`string`	Obbligatorio
quantity	`number`	Obbligatorio
deliveryMethod	`string`	Obbligatorio
unitNet	`amount`	Obbligatorio
unitGross	`amount`	Obbligatorio
unitTax	`amount`	Obbligatorio
totalNet	`amount`	Obbligatorio
totalGross	`amount`	Obbligatorio
totalTax	`amount`	Obbligatorio
appliedTaxRate	`number`	Obbligatorio
taxBehavior	`string`	Obbligatorio
updatedAt	`isoDate`	Obbligatorio

Schema Riga Ordine Eliminata (`order-item.deleted`)

Campo	Tipo	Note
orderId	`uuid`	Obbligatorio
orderItemId	`uuid`	Obbligatorio (ID della riga eliminata)

Esempio Schema Riga Ordine Eliminata

{
    "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"
}

Schema Promozione Sostituita (`order.promotion-usage.replaced`)

Campo	Tipo	Note
orderId	`uuid`	Obbligatorio
orderItemId	`uuid[]`	Obbligatorio (Array di ID delle righe ordine coinvolte)

Esempio Schema Promozione Sostituita

{
    "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"
}

Perché ascoltare gli eventi sugli ordini

Tabella Completa Eventi e Payload

Tipi di dato​

Tipi Base​

Schema Indirizzo (addressSchema)​

Schema Ordine (orderDataSchema)​

Esempio Schema Ordine​

Schema Ordine Eliminato (order.deleted)​

Esempio Schema Ordine Eliminato​

Schema Riga Ordine Creata (order-item.created)​

Esempio Schema Riga Ordine Creata​

Schema Riga Ordine Aggiornata (order-item.updated)​

Schema Riga Ordine Eliminata (order-item.deleted)​

Esempio Schema Riga Ordine Eliminata​

Schema Promozione Sostituita (order.promotion-usage.replaced)​

Esempio Schema Promozione Sostituita​