shipment/created

Overview

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

Description

Fired when a shipment is created. A shipment represents a physical parcel dispatched to the customer — it has a carrier label, tracking number, and delivery address. One delivery order may generate multiple shipments (e.g. partial fulfillments or multiple parcels).

Trigger Conditions

• A warehouse creates a carrier label and registers a shipment
• An operator manually creates a shipment via the GraphQL API
• The fulfillment pipeline generates a shipment after a delivery order line reaches IN_PROGRESS

Message Envelope

{
  "header": {
    "organizationId": "org_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "messageId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "webhookId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "type": "shipment/created",
    "date": "2024-03-15T16:00:00.000Z"
  },
  "body": { ... }
}

Body — Property Table

Shipment Object

Field	Type	Nullable	Description
id	string (uuid)	No	Unique shipment identifier
externalId	string	Yes	External reference (carrier-assigned ID)
locationId	string (uuid)	Yes	Originating warehouse/location
organizationId	string (uuid)	No	Owning organization
shippingMethodId	string (uuid)	Yes	Shipping method used
shippingMethodName	string	Yes	Human-readable shipping method name
details	ShipmentDetail[]	No	Array of parcel contents (see below)
addresses	ShipmentAddress[]	No	Delivery and return addresses (see below)
events	ShippingEvent[]	No	Array of tracking events (see below)
lastEvent	enum	No	Most recent tracking event code (see ShippingEventEnum)
state	enum	Yes	Shipment state: DRAFT, OPENED, or COMPLETED
label	string	No	Carrier label identifier (e.g. 1Z999AA10123456784)
reference	string	No	Internal shipment reference
trackingUrl	string	Yes	Public tracking URL
tracking	string	Yes	Tracking number as a plain string
meta	object	Yes	Arbitrary metadata (JSON)
issuedAt	string (ISO 8601)	No	When the shipment was issued
createdAt	string (ISO 8601)	No	When the shipment record was created
deliveredAt	string (ISO 8601)	Yes	When the package was delivered
firstAttemptedAt	string (ISO 8601)	Yes	When the first delivery attempt was made
estimatedAt	string (ISO 8601)	Yes	Estimated delivery date
weight	float	Yes	Package weight
weightSellingUnit	enum	Yes	Weight unit: kg, g, or mg, default kg
volume	float	Yes	Package volume
volumeSellingUnit	enum	Yes	Volume unit: l or ml, default l
format	string	Yes	Package format descriptor

ShipmentDetail Object (parcel line item)

Field	Type	Nullable	Description
id	string (uuid)	No	Unique detail identifier
shipmentId	string (uuid)	No	Parent shipment ID
orderLineId	string (uuid)	Yes	Source order line ID
deliveryOrderLineId	string (uuid)	No	Source delivery order line ID
label	string	No	Product label
quantity	integer	No	Quantity in this parcel
batchNumber	string	Yes	Batch/lot number (for regulated goods)
limitUsageDate	string (ISO 8601)	Yes	Expiration date (for perishable goods)

ShipmentAddress Object

Field	Type	Nullable	Description
id	string (uuid)	No	Unique address identifier
shipmentId	string (uuid)	No	Parent shipment ID
type	enum	No	Address type: DELIVERY or RETURN
fullname	string	No	Full recipient name
email	string	No	Email address
address	string	No	Street address line 1
addressComplement	string	Yes	Street address line 2
zipcode	string	No	Postal/ZIP code
city	string	No	City name
country	string	No	ISO 3166-1 alpha-2 country code
state	string	Yes	State/region
phone	string	Yes	Phone number
mobile	string	Yes	Mobile number
comments	string	Yes	Free-text comment

ShippingEvent Object

Field	Type	Nullable	Description
id	string (uuid)	No	Unique event identifier
shipmentId	string (uuid)	No	Parent shipment ID
event	enum	No	Event code (see below)
eventCode	string	Yes	Carrier-specific event code
eventMessage	string	Yes	Human-readable event message from carrier
eventDescription	string	Yes	Detailed description
eventCountry	string	Yes	Country where the event occurred
eventDate	string (ISO 8601)	Yes	When the carrier event occurred
date	string (ISO 8601)	No	When HappyColis recorded this event
comment	string	Yes	Internal comment
meta	object	Yes	Arbitrary metadata (JSON)

ShippingEventEnum values:

Value	Description
NEW	Shipment created, not yet in carrier system
INFO_RECEIVED	Carrier received shipping information (default)
PENDING	Awaiting carrier pickup
IN_TRANSIT	Package in transit
OUT_FOR_DELIVERY	Out for final delivery attempt
ATTEMPT_FAIL	Delivery attempt failed
AVAILABLE_FOR_PICKUP	Available at pickup point
DELIVERED	Successfully delivered
DELIVERED_TO_SENDER	Returned to sender
EXCEPTION	Carrier exception (damage, loss, etc.)
RETURNED_TO_SENDER	In transit back to sender
EXPIRED	Shipment expired without delivery

Full JSON Payload Sample

{
  "header": {
    "organizationId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "messageId": "e1f2a3b4-c5d6-7890-efab-567890123456",
    "webhookId": "c3d4e5f6-a7b8-9012-cdef-123456789012",
    "type": "shipment/created",
    "date": "2024-03-15T16:00:00.000Z"
  },
  "body": {
    "id": "f2a3b4c5-d6e7-8901-fabc-678901234567",
    "externalId": "CLS-9387263847",
    "locationId": "f0a1b2c3-d4e5-6789-f0ab-123456789012",
    "organizationId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "shippingMethodId": "f6a7b8c9-d0e1-2345-fabc-456789012345",
    "shippingMethodName": "Colissimo Domicile",
    "lastEvent": "INFO_RECEIVED",
    "state": "OPENED",
    "label": "1Z999AA10123456784",
    "reference": "SHP-2024-001234",
    "trackingUrl": "https://www.laposte.fr/outils/track-a-parcel?code=1Z999AA10123456784",
    "tracking": "1Z999AA10123456784",
    "meta": null,
    "issuedAt": "2024-03-15T16:00:00.000Z",
    "createdAt": "2024-03-15T16:00:00.000Z",
    "deliveredAt": null,
    "firstAttemptedAt": null,
    "estimatedAt": "2024-03-17T18:00:00.000Z",
    "weight": 1.5,
    "weightSellingUnit": "kg",
    "volume": null,
    "volumeSellingUnit": "l",
    "format": "S",
    "addresses": [
      {
        "id": "a3b4c5d6-e7f8-9012-abcd-789012345678",
        "shipmentId": "f2a3b4c5-d6e7-8901-fabc-678901234567",
        "type": "DELIVERY",
        "fullname": "Alice Dupont",
        "email": "alice.dupont@example.com",
        "address": "12 Rue de la Paix",
        "addressComplement": "Apt 4B",
        "zipcode": "75001",
        "city": "Paris",
        "country": "FR",
        "state": null,
        "phone": "+33612345678",
        "mobile": null,
        "comments": null
      },
      {
        "id": "b4c5d6e7-f8a9-0123-bcde-890123456789",
        "shipmentId": "f2a3b4c5-d6e7-8901-fabc-678901234567",
        "type": "RETURN",
        "fullname": "HappyColis Entrepôt Paris",
        "email": "returns@happycolis.com",
        "address": "123 Avenue des Champs-Élysées",
        "addressComplement": null,
        "zipcode": "75008",
        "city": "Paris",
        "country": "FR",
        "state": null,
        "phone": "+33140000000",
        "mobile": null,
        "comments": null
      }
    ],
    "details": [
      {
        "id": "c5d6e7f8-a9b0-1234-cdef-901234567890",
        "shipmentId": "f2a3b4c5-d6e7-8901-fabc-678901234567",
        "orderLineId": "c9d0e1f2-a3b4-5678-cdef-789012345678",
        "deliveryOrderLineId": "b2c3d4e5-f6a7-8901-bcde-012345678901",
        "label": "T-Shirt Blanc Taille M",
        "quantity": 2,
        "batchNumber": null,
        "limitUsageDate": null
      }
    ],
    "events": [
      {
        "id": "d6e7f8a9-b0c1-2345-defa-012345678901",
        "shipmentId": "f2a3b4c5-d6e7-8901-fabc-678901234567",
        "event": "INFO_RECEIVED",
        "eventCode": null,
        "eventMessage": null,
        "eventDescription": null,
        "eventCountry": null,
        "eventDate": null,
        "date": "2024-03-15T16:00:00.000Z",
        "comment": null,
        "meta": null
      }
    ]
  }
}

Related Events

• shipment/shipping_event — fired when tracking status changes
• shipment/completed — fired when delivery is confirmed
• delivery_order/completed — typically follows last shipment completion

Notes

• One delivery order can generate multiple shipments (e.g. items from the same order split across multiple parcels).
• At creation, events always contains at least one INFO_RECEIVED event.
• The lastEvent field is a convenience field reflecting the most recent event code — it is updated by each new ShippingEvent.
• state: DRAFT may occur when the shipment is pre-created before label generation; OPENED means the label is active.
• details links this shipment back to specific delivery order lines via deliveryOrderLineId.
• For B2C orders, there is typically one DELIVERY address and one RETURN address.