order/created

Overview

Property	Value
Webhook type	order/created
Kafka topic	order.created
Direction	Platform → Your endpoint

Description

Fired when a new order is created in the system. This can happen via the GraphQL API (from a CMS integration or App), or internally when an order is imported. Every order creation triggers exactly one order/created event.

Trigger Conditions

• An order is submitted through the HappyColis GraphQL API
• An order is imported via a third-party application integration
• sourceType will be CMS for storefront-created orders or APP for orders created programmatically via the API

Message Envelope

{
  "header": {
    "organizationId": "org_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "messageId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "webhookId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "type": "order/created",
    "date": "2024-03-15T10:23:45.000Z"
  },
  "body": { ... }
}

The body field contains the full OrderEntity object as described below.

Body — Property Table

Order Object

Field	Type	Nullable	Description
id	string (uuid)	No	Unique order identifier
externalReference	string	Yes	External reference from the originating platform (e.g. Shopify order ID)
organizationId	string (uuid)	No	Organization that owns this order
tpAppId	string (uuid)	Yes	Third-party application ID that created the order
shippingMethodId	string (uuid)	Yes	Assigned shipping method
shippingMethodName	string	Yes	Human-readable shipping method name
collectPointId	string	Yes	Pickup point ID (for deliveryType: PICKUP)
collectPointCountry	string	Yes	Country code of the pickup point
collectPointZipCode	string	Yes	ZIP code of the pickup point
lines	OrderLine[]	No	Array of order lines (see below)
type	enum	No	Order type: B2B or B2C
dispatchingType	enum	No	Dispatching mode: MANUAL or AUTOMATIC
total	float	Yes	Total order amount (tax-exclusive)
totalTaxInclusive	float	Yes	Total order amount (tax-inclusive)
totalShipping	float	Yes	Total shipping cost
totalDiscount	float	Yes	Total discount applied
totalVat	float	Yes	Total VAT amount
totalInsurance	float	Yes	Total insurance amount
currency	string	No	ISO 4217 currency code, default EUR
invoiceNumber	string	No	Invoice reference number
invoiceUrl	string	Yes	URL to the invoice document
gift	boolean	Yes	Whether this is a gift order
inventoryPolicy	enum	Yes	Inventory policy: DENY or CONTINUE
issuedAt	string (ISO 8601)	No	Timestamp when the order was placed by the customer
prepareAt	string (ISO 8601)	Yes	Scheduled preparation time
receivedAt	string (ISO 8601)	No	Timestamp when the order was received by the platform
fulfillmentRequestedAt	string (ISO 8601)	Yes	Timestamp when fulfillment was requested
buyer	Contact	Yes	Buyer contact information (see Contact object)
billingContact	Contact	Yes	Billing address contact (see Contact object)
deliveryContact	Contact	Yes	Delivery address contact (see Contact object)
seller	Contact	Yes	Seller contact information (see Contact object)
comment	string	Yes	Free-text comment on the order
meta	object	Yes	Arbitrary metadata (JSON)
state	enum	No	Order state: DRAFT, OPENED, or COMPLETED
priority	enum	No	Order priority: LOW, NORMAL, or HIGH
locked	boolean	No	Whether the order is locked for modifications
opening	boolean	No	Whether the order is currently being opened
sourceType	enum	No	Origin source: CMS or APP
deliveryType	enum	No	Delivery type: HOME or PICKUP

OrderLine Object

Field	Type	Nullable	Description
id	string (uuid)	No	Unique order line identifier
orderId	string (uuid)	No	Parent order ID
status	enum	No	Line status: PENDING, CANCELED, ACCEPTED, IN_PROGRESS, FULFILLED, PARTIALLY_FULFILLED, ERRORED, DELIVERED
label	string	Yes	Product label / display name
sku	string	No	Stock keeping unit identifier
price	float	Yes	Unit price (tax-exclusive)
vatRate	float	Yes	VAT rate as a decimal (e.g. 0.20 for 20%)
total	float	Yes	Line total (quantity × price, tax-exclusive)
totalTaxInclusive	float	Yes	Line total (tax-inclusive)
fulfillableQuantity	integer	Yes	Quantity eligible for fulfillment
quantity	integer	Yes	Ordered quantity
fulfilledQuantity	integer	No	Quantity already fulfilled, default 0
meta	object	Yes	Arbitrary metadata (JSON)
locationId	string (uuid)	Yes	Preferred fulfillment location
shippingMethodId	string (uuid)	Yes	Preferred shipping method
number	string	Yes	Line identifier within the order (unique per order)

Contact Object

Field	Type	Nullable	Description
id	string (uuid)	No	Unique contact identifier
type	enum	No	Contact type: PERSON or COMPANY
organizationId	string (uuid)	No	Owning organization
fullname	string	Yes	Full name
email	string	Yes	Email address
address	string	Yes	Street address line 1
addressComplement	string	Yes	Street address line 2
zipcode	string	Yes	Postal/ZIP code
country	string	Yes	ISO 3166-1 alpha-2 country code
city	string	Yes	City name
state	string	Yes	State/region
phone	string	Yes	Phone number
comments	string	Yes	Free-text comment
metadata	object	Yes	Arbitrary metadata (JSON)
taxId	string	Yes	Tax identifier (VAT number, etc.)
eori	string	Yes	Economic Operators Registration and Identification number
form	string	Yes	Legal form (for companies)
capital	string	Yes	Share capital (for companies)
companyId	string	Yes	Company registration number
registration	string	Yes	Trade register number

Full JSON Payload Sample

{
  "header": {
    "organizationId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "messageId": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
    "webhookId": "c3d4e5f6-a7b8-9012-cdef-123456789012",
    "type": "order/created",
    "date": "2024-03-15T10:23:45.000Z"
  },
  "body": {
    "id": "d4e5f6a7-b8c9-0123-defa-234567890123",
    "externalReference": "SHOP-12345",
    "organizationId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "tpAppId": "e5f6a7b8-c9d0-1234-efab-345678901234",
    "shippingMethodId": "f6a7b8c9-d0e1-2345-fabc-456789012345",
    "shippingMethodName": "Colissimo Domicile",
    "collectPointId": null,
    "collectPointCountry": null,
    "collectPointZipCode": null,
    "type": "B2C",
    "dispatchingType": "AUTOMATIC",
    "total": 85.00,
    "totalTaxInclusive": 102.00,
    "totalShipping": 5.99,
    "totalDiscount": 0.00,
    "totalVat": 17.00,
    "totalInsurance": null,
    "currency": "EUR",
    "invoiceNumber": "INV-2024-001234",
    "invoiceUrl": "https://cdn.example.com/invoices/INV-2024-001234.pdf",
    "gift": false,
    "inventoryPolicy": "DENY",
    "issuedAt": "2024-03-15T09:00:00.000Z",
    "prepareAt": null,
    "receivedAt": "2024-03-15T10:23:45.000Z",
    "fulfillmentRequestedAt": null,
    "buyer": {
      "id": "a7b8c9d0-e1f2-3456-abcd-567890123456",
      "type": "PERSON",
      "organizationId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "fullname": "Alice Dupont",
      "email": "alice.dupont@example.com",
      "address": "12 Rue de la Paix",
      "addressComplement": "Apt 4B",
      "zipcode": "75001",
      "country": "FR",
      "city": "Paris",
      "state": null,
      "phone": "+33612345678",
      "comments": null,
      "metadata": null,
      "taxId": null,
      "eori": null,
      "form": null,
      "capital": null,
      "companyId": null,
      "registration": null
    },
    "billingContact": {
      "id": "a7b8c9d0-e1f2-3456-abcd-567890123456",
      "type": "PERSON",
      "organizationId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "fullname": "Alice Dupont",
      "email": "alice.dupont@example.com",
      "address": "12 Rue de la Paix",
      "addressComplement": "Apt 4B",
      "zipcode": "75001",
      "country": "FR",
      "city": "Paris",
      "state": null,
      "phone": "+33612345678",
      "comments": null,
      "metadata": null,
      "taxId": null,
      "eori": null,
      "form": null,
      "capital": null,
      "companyId": null,
      "registration": null
    },
    "deliveryContact": {
      "id": "b8c9d0e1-f2a3-4567-bcde-678901234567",
      "type": "PERSON",
      "organizationId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "fullname": "Alice Dupont",
      "email": "alice.dupont@example.com",
      "address": "12 Rue de la Paix",
      "addressComplement": "Apt 4B",
      "zipcode": "75001",
      "country": "FR",
      "city": "Paris",
      "state": null,
      "phone": "+33612345678",
      "comments": null,
      "metadata": null,
      "taxId": null,
      "eori": null,
      "form": null,
      "capital": null,
      "companyId": null,
      "registration": null
    },
    "seller": null,
    "comment": null,
    "meta": null,
    "state": "OPENED",
    "priority": "NORMAL",
    "locked": false,
    "opening": false,
    "sourceType": "CMS",
    "deliveryType": "HOME",
    "lines": [
      {
        "id": "c9d0e1f2-a3b4-5678-cdef-789012345678",
        "orderId": "d4e5f6a7-b8c9-0123-defa-234567890123",
        "status": "PENDING",
        "label": "T-Shirt Blanc Taille M",
        "sku": "TSHIRT-WHITE-M",
        "price": 25.00,
        "vatRate": 0.20,
        "total": 50.00,
        "totalTaxInclusive": 60.00,
        "fulfillableQuantity": 2,
        "quantity": 2,
        "fulfilledQuantity": 0,
        "meta": null,
        "locationId": null,
        "shippingMethodId": null,
        "number": "1"
      },
      {
        "id": "d0e1f2a3-b4c5-6789-defa-890123456789",
        "orderId": "d4e5f6a7-b8c9-0123-defa-234567890123",
        "status": "PENDING",
        "label": "Pantalon Bleu Taille 38",
        "sku": "PANTS-BLUE-38",
        "price": 35.00,
        "vatRate": 0.20,
        "total": 35.00,
        "totalTaxInclusive": 42.00,
        "fulfillableQuantity": 1,
        "quantity": 1,
        "fulfilledQuantity": 0,
        "meta": null,
        "locationId": null,
        "shippingMethodId": null,
        "number": "2"
      }
    ]
  }
}

Related Events

• order/updated — fired when any order field changes
• order/completed — fired when all order lines are fulfilled
• order/cancelled — fired when the order is cancelled

Notes

• The body is a serialized OrderEntity — all @Exclude() fields (e.g. buyerId, billingContactId, etc.) are stripped from the payload; only the eager-loaded relation objects are included.
• issuedAt reflects when the customer placed the order on the storefront; receivedAt reflects when HappyColis received it.
• The lines array is always present (eager-loaded) but may be empty for draft orders.
• A freshly created order always has state: OPENED unless it was explicitly created as DRAFT.
• Line statuses history is excluded from the webhook payload (marked @Exclude()).