Événements : expéditions

Cette page détaille les trois clés d’événement liées à l’expédition : created_shippingbox, updated_shippingbox, deleted_shippingbox. Une expédition (« shippingbox ») est un colis planifié : un abonnement en génère une à chaque cycle, une commande boutique peut en générer une directement. Pour la configuration générale, voir Comprendre un envoi de webhook.

Objet expédition

Chaque envoi lié à une expédition porte l’objet complet.

Champ	Type	Nullable	Sens
tenant_id	entier	non	boutique propriétaire
id	entier	non	identifiant interne
uuid	chaîne	non	identifiant public
address	objet	oui	voir Objet adresse
transporter	objet	oui	voir Objet transporteur
created_at	date ISO 8601	non	création
updated_at	date ISO 8601	non	dernière modification
scheduled_at	date ISO 8601	oui	départ planifié
tracking_link	chaîne	oui	nul sans numéro de suivi (combiné à l’URL de suivi du transporteur) ni URL de suivi enregistrée directement sur l’expédition
subscription_uuid	chaîne	oui	abonnement d’origine ; nul pour une expédition boutique
address_id	entier	oui	id de l’adresse
phone	chaîne	oui	téléphone destinataire
status	chaîne	non	libre (created, shipped…), pas une énumération fermée
tracking_number	chaîne	oui	numéro de suivi
customer_id	chaîne	oui	id public du client (cus_...), pas le numérique
supply_id	chaîne	oui	lot logistique
transporter_id	entier	oui	id du transporteur
first_name	chaîne	oui	prénom destinataire
last_name	chaîne	oui	nom destinataire
postcode	chaîne	oui	code postal
address1	chaîne	oui	adresse
address2	chaîne	oui	complément
division	chaîne	oui	subdivision administrative
city	chaîne	oui	ville
country	chaîne	oui	pays
mail	chaîne	oui	e-mail client à l’envoi
subscriptions_count	chaîne	oui	abonnements du client, en chaîne
transporter_name	chaîne	oui	nom du transporteur
shipped_count	chaîne	oui	envois du cycle, en chaîne
site_name	chaîne	oui	boutique
options	chaîne	oui	déclinaison, valeurs séparées par |
iso_code	chaîne	oui	code pays ISO
relay	objet	oui	point relais choisi
relay_id	chaîne	oui	id du point relais
orderable_name	chaîne	oui	nom du produit expédié
orderable_id	chaîne	oui	id du produit, en chaîne
orderable_type	chaîne	oui	type de produit expédié : formule (App\Plan) ou produit (App\Product)
order_id	entier	oui	commande liée
ref	chaîne	oui	référence produit
customization_products	tableau	oui	choix de personnalisation
extra_customization_products	tableau	oui	personnalisations ajoutées après coup

Objet transporteur

L’objet transporter suit la structure décrite ci-dessous. Il est nul quand l’expédition n’a pas de transporteur assigné.

Champ	Type	Nullable	Sens
id	entier	non	identifiant interne
countries	tableau d’objets	non	pays couverts (id, name)
plan_blacklisted	tableau d’objets	non	formules exclues (id, name)
name	chaîne	non	nom du transporteur
description	chaîne	oui	description commerciale
price	nombre	non	prix, flottant
gift	booléen	non	disponible pour une carte cadeau
active	booléen	non	transporteur actif
shipped_count	entier	non	envois par cycle
type	chaîne	non	type de transporteur
relayOptions	objet	oui	voir ci-dessous

relayOptions est une structure non contractuelle : son contenu varie selon le transporteur relais choisi (Mondial Relay, Colissimo, DPD) et peut changer sans préavis. N’en exploitez pas les clés individuellement. Dans les exemples de cette page, il vaut null (pas de point relais).

created_shippingbox

Objet envoyé : expédition complète. Délai avant l’envoi : aucun. Exemple complet : dans le contrat OpenAPI (/openapi/ciklik-webhooks.yaml), webhook created_shippingbox.

Quand il part

• Création ou renouvellement d’un abonnement (génération standard, y compris boutique composable).
• Commande boutique générant directement une expédition, hors abonnement.
• Report anti-churn : un report d’échéance produit un updated_subscription suivi d’autant de created_shippingbox que de mois reportés. Voir Événements : abonnements.

Quand il ne part pas

Aucun cas connu : toute création d’expédition déclenche l’envoi.

Ce que contient changed

Toujours un tableau vide ([]) : un created_* n’a par définition rien à comparer à un état antérieur.

Effets en cascade

Aucun, au-delà de son origine. Le cas du report anti-churn est lui-même un effet en cascade d’un updated_subscription, pas l’inverse.

Exemple

created_shippingbox

{
    "tenant_id": 1,
    "id": 1,
    "uuid": "c636e863-bdf5-4914-b108-05e117cb0c12",
    "address": {
        "id": 1,
        "user_id": 1,
        "address": "12 rue des Lilas",
        "address1": "Bâtiment B, 3e étage",
        "postcode": "69003",
        "city": "Lyon",
        "phone": "+33612345678",
        "first_name": "Claire",
        "last_name": "Martin",
        "region_id": 1,
        "division": null,
        "division_name": null,
        "deletable": false,
        "company_name": null,
        "country": {
            "id": 1,
            "name": "France",
            "alphaCode": "FR"
        },
        "external_id": 4821
    },
    "transporter": {
        "id": 1,
        "countries": [
            {
                "id": 1,
                "name": "France"
            }
        ],
        "plan_blacklisted": [],
        "name": "Colissimo domicile",
        "description": "Livraison à domicile sous 48h",
        "price": 4.9,
        "gift": false,
        "active": true,
        "shipped_count": 1,
        "type": "subs",
        "relayOptions": null
    },
    "created_at": "2026-09-10T08:15:42.000000Z",
    "updated_at": "2026-09-10T08:15:42.000000Z",
    "scheduled_at": "2026-09-15T00:00:00.000000Z",
    "tracking_link": null,
    "subscription_uuid": "sub_N8PxGUEdS2U7DP",
    "address_id": 1,
    "phone": "+33612345678",
    "status": "created",
    "tracking_number": null,
    "customer_id": "cus_Qx7hR3eaEowcv1DX",
    "supply_id": null,
    "transporter_id": 1,
    "first_name": "Claire",
    "last_name": "Martin",
    "postcode": "69003",
    "address1": "12 rue des Lilas",
    "address2": "Bâtiment B, 3e étage",
    "division": null,
    "city": "Lyon",
    "country": "France",
    "mail": "claire.martin@example.com",
    "subscriptions_count": "1",
    "transporter_name": "Colissimo domicile",
    "shipped_count": "1",
    "site_name": "Boutique Exemple",
    "options": null,
    "iso_code": "fr",
    "relay": null,
    "relay_id": null,
    "orderable_name": "Box mensuelle",
    "orderable_id": "1",
    "orderable_type": "App\\Plan",
    "order_id": 1,
    "ref": "BOX-MENSUELLE",
    "customization_products": [
        {
            "id": 1,
            "quantity": 1
        }
    ],
    "extra_customization_products": null,
    "changed": []
}

updated_shippingbox

Objet envoyé : expédition complète, dans son état au moment de l’envoi. Délai avant l’envoi : aucun. Exemple complet : dans le contrat OpenAPI (/openapi/ciklik-webhooks.yaml), webhook updated_shippingbox.

Quand il part

• Modification directe de l’expédition (adresse, statut, numéro de suivi…) par l’API vendors ou par l’équipe Ciklik.
• Cascade depuis une adresse, un abonnement ou un client modifié : voir « Effets en cascade ».

Quand il ne part pas

• Liaison d’une expédition à sa commande d’origine (écriture silencieuse).
• Ajout de personnalisations supplémentaires depuis l’interface interne (extra_customization_products, écriture silencieuse).
• Recalcul du compteur shipped_count ou correctif d’options par une commande de maintenance interne.

Le passage à « expédié » n’est pas toujours notifié

Le passage du statut à shipped déclenche un updated_shippingbox quand il est posé par l’API vendors (POST /deliveries/{id}, champ status ou tracking_number) ou par l’import de numéros de suivi de l’équipe Ciklik. Il n’en déclenche aucun quand il provient des connecteurs logistiques Wonderweb ou Effitrace : c’est l’un des pièges les plus coûteux pour un intégrateur qui attendrait ce webhook pour notifier un client ou mettre à jour un stock sur ces canaux. En cas de doute sur l’origine du passage à shipped, interrogez l’API plutôt que d’attendre un webhook.

Ce que contient changed

Un objet {colonne : valeur brute}.

Attention à l’interprétation

Avant l’envoi, Ciklik resynchronise depuis l’adresse et l’abonnement liés les champs first_name, last_name, phone, postcode, address1, address2, city, country, mail, subscriptions_count, transporter_name, iso_code, relay et relay_id : les champs texte sont réécrits en majuscules et sans accents, indépendamment de ce que l’appelant a réellement modifié. Le changed contient donc ces champs synchronisés en plus de ceux modifiés par l’appelant, sans distinction entre les deux : n’en déduisez pas que le client a saisi son adresse en majuscules. Un même changement peut aussi produire deux envois updated_shippingbox pour la même expédition, quand un traitement interne enregistre deux fois la même expédition.

Effets en cascade

Trois origines produisent, chacune, un updated_shippingbox par expédition planifiée depuis le premier jour de l’avant-dernier mois (M-2, par exemple le 1er juillet pour un envoi en septembre), expéditions déjà parties incluses :

Origine	Déclencheur	Portée
Adresse	updated_address, quel que soit le champ modifié	chaque abonnement lié à l’adresse
Abonnement	changement d’adresse, de transporteur, de déclinaison, de point relais ou de personnalisation produit	l’abonnement modifié
Client	changement de l’e-mail du client	chaque abonnement du client, en plus de l’updated_user

La cascade du changement d’e-mail est établie dans le code : un client dont l’e-mail change et qui a 12 expéditions dans cette fenêtre déclenche 1 updated_user puis 12 updated_shippingbox (détail sur Événements : clients, adresses et inscriptions). Le changement sur l’abonnement déclenche en plus un ou deux updated_checkoutorder par commande en cours de création (voir Événements : commandes, transactions et factures).

Exemple

changed de updated_shippingbox

{
    "changed": {
        "phone": "06 12 34 56 78",
        "first_name": "CLAIRE",
        "last_name": "MARTIN",
        "postcode": "69007",
        "address1": "27 AVENUE JEAN JAURES",
        "address2": "",
        "city": "LYON",
        "country": "FRANCE",
        "mail": "claire.martin-dupont@example.com",
        "status": "shipped",
        "tracking_number": "6A12345678901"
    }
}

Le reste de la charge utile est identique à celle de created_shippingbox. Ici, first_name, last_name, address1, city, country, phone, postcode et mail proviennent de la resynchronisation ; seuls status et tracking_number sont réellement modifiés par l’appelant.

deleted_shippingbox

Objet envoyé : expédition complète, même après suppression (l’état est relu au moment de l’envoi, sans tenir compte de la suppression). Délai avant l’envoi : aucun. Exemple complet : dans le contrat OpenAPI (/openapi/ciklik-webhooks.yaml), webhook deleted_shippingbox.

Quand il part

• Suppression via l’API vendors, DELETE /deliveries/{id}.
• Validation d’une demande de retrait par l’équipe Ciklik, avec l’option de suppression : seules les expéditions futures sont supprimées.
• Remboursement d’une transaction par l’équipe Ciklik, avec l’option de suppression : toutes les expéditions de la commande sont supprimées, passées et futures.

Quand il ne part pas

Des expéditions supprimées sans aucun envoi

La mise en pause d’un abonnement par l’équipe Ciklik, avec l’option de suppression des expéditions futures, les supprime par une écriture en masse qui ne déclenche pas de webhook. Aucun deleted_shippingbox ne part dans ce cas : un intégrateur qui synchronise ses expéditions uniquement par webhook garde en base des expéditions qui n’existent déjà plus chez Ciklik.

Ce que contient changed

Toujours {"deleted": true}, quelle que soit l’expédition.

Effets en cascade

Aucun effet en cascade propre à la suppression n’est documenté : elle intervient en fin de parcours (retrait validé ou remboursement), sans autre webhook associé.

Exemple

changed de deleted_shippingbox

{
    "changed": {
        "deleted": true
    }
}

Le reste de la charge utile est identique à celle de created_shippingbox.