Events: shipments

This page details the three shipment-related event keys: created_shippingbox, updated_shippingbox, deleted_shippingbox. A shipment (“shippingbox”) is a scheduled parcel: a subscription generates one per cycle, and a shop order can generate one directly. For general configuration, see Understanding a webhook delivery.

Shipment object

Every shipment-related delivery carries the full object.

Field	Type	Nullable	Meaning
tenant_id	integer	no	owning shop
id	integer	no	internal identifier
uuid	string	no	public identifier
address	object	yes	see Address object
transporter	object	yes	see Carrier object
created_at	ISO 8601 date	no	creation
updated_at	ISO 8601 date	no	last modification
scheduled_at	ISO 8601 date	yes	scheduled departure
tracking_link	string	yes	null without a tracking number (combined with the carrier’s tracking URL) nor a tracking URL set directly on the shipment
subscription_uuid	string	yes	originating subscription; null for a shop shipment
address_id	integer	yes	address id
phone	string	yes	recipient phone number
status	string	no	free-form (created, shipped…), not a closed enumeration
tracking_number	string	yes	tracking number
customer_id	string	yes	public customer id (cus_...), not the numeric one
supply_id	string	yes	logistics batch
transporter_id	integer	yes	carrier id
first_name	string	yes	recipient first name
last_name	string	yes	recipient last name
postcode	string	yes	postal code
address1	string	yes	address
address2	string	yes	address line 2
division	string	yes	administrative subdivision
city	string	yes	city
country	string	yes	country
mail	string	yes	customer e-mail at the time of delivery
subscriptions_count	string	yes	customer’s subscriptions, as a string
transporter_name	string	yes	carrier name
shipped_count	string	yes	shipments per cycle, as a string
site_name	string	yes	shop
options	string	yes	variant, values separated by |
iso_code	string	yes	ISO country code
relay	object	yes	selected pickup point
relay_id	string	yes	pickup point id
orderable_name	string	yes	name of the shipped product
orderable_id	string	yes	product id, as a string
orderable_type	string	yes	type of shipped product: plan (App\Plan) or product (App\Product)
order_id	integer	yes	related order
ref	string	yes	product reference
customization_products	array	yes	customization choices
extra_customization_products	array	yes	customizations added afterwards

Carrier object

The transporter object follows the structure described below. It is null when the shipment has no assigned carrier.

Field	Type	Nullable	Meaning
id	integer	no	internal identifier
countries	array of objects	no	covered countries (id, name)
plan_blacklisted	array of objects	no	excluded plans (id, name)
name	string	no	carrier name
description	string	yes	marketing description
price	number	no	price, float
gift	boolean	no	available for a gift card
active	boolean	no	carrier is active
shipped_count	integer	no	shipments per cycle
type	string	no	carrier type
relayOptions	object	yes	see below

relayOptions is a non-contractual structure: its contents vary with the selected pickup-point carrier (Mondial Relay, Colissimo, DPD) and may change without notice. Do not rely on its individual keys. In the examples on this page it is null (no pickup point).

created_shippingbox

Object sent: full shipment. Delay before delivery: none. Full example: in the OpenAPI contract (/openapi/ciklik-webhooks.yaml), webhook created_shippingbox.

When it is sent

• Creation or renewal of a subscription (standard generation, including the composable shop).
• Shop order generating a shipment directly, outside any subscription.
• Anti-churn postponement: postponing a due date produces an updated_subscription followed by as many created_shippingbox as months postponed. See Events: subscriptions.

When it is not sent

No known case: every shipment creation triggers the delivery.

What changed contains

Always an empty array ([]): by definition, a created_* has no previous state to compare against.

Cascading effects

None, beyond its own origin. The anti-churn postponement case is itself a cascading effect of an updated_subscription, not the other way round.

Example

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

Object sent: full shipment, in its state at the time of delivery. Delay before delivery: none. Full example: in the OpenAPI contract (/openapi/ciklik-webhooks.yaml), webhook updated_shippingbox.

When it is sent

• Direct modification of the shipment (address, status, tracking number…) through the vendors API or by the Ciklik team.
• Cascade from a modified address, subscription or customer: see “Cascading effects”.

When it is not sent

• Linking a shipment to its originating order (silent write).
• Adding extra customizations from the internal interface (extra_customization_products, silent write).
• Recalculating the shipped_count counter or fixing options through an internal maintenance command.

The transition to “shipped” is not always notified

Changing the status to shipped triggers an updated_shippingbox when it is made through the vendors API (POST /deliveries/{id}, status or tracking_number field) or through the Ciklik team’s tracking-number import. It triggers none when it comes from the Wonderweb or Effitrace logistics connectors: this is one of the most costly pitfalls for an integrator who would wait for this webhook to notify a customer or update stock on those channels. When in doubt about the origin of a transition to shipped, query the API rather than wait for a webhook.

What changed contains

An object {column: raw value}.

Beware of interpretation

Before delivery, Ciklik resynchronizes from the linked address and subscription the fields first_name, last_name, phone, postcode, address1, address2, city, country, mail, subscriptions_count, transporter_name, iso_code, relay and relay_id: text fields are rewritten in uppercase without accents, regardless of what the caller actually modified. changed therefore contains these synchronized fields in addition to those modified by the caller, with no way to tell them apart: do not conclude that the customer typed their address in uppercase. A single change may also produce two updated_shippingbox deliveries for the same shipment, when an internal process saves the same shipment twice.

Cascading effects

Three origins each produce one updated_shippingbox per shipment scheduled since the first day of the month before last (M-2, for example July 1st for a shipment in September), shipments already sent included:

Origin	Trigger	Scope
Address	updated_address, whatever the modified field	every subscription linked to the address
Subscription	change of address, carrier, variant, pickup point or product customization	the modified subscription
Customer	change of the customer’s e-mail	every subscription of the customer, in addition to the updated_user

The e-mail change cascade is established in the code: a customer whose e-mail changes and who has 12 shipments in that window triggers 1 updated_user followed by 12 updated_shippingbox (details in Events: customers, addresses and opt-ins). A change on the subscription additionally triggers one or two updated_checkoutorder per order being created (see Events: orders, transactions and invoices).

Example

changed of 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"
    }
}

The rest of the payload is identical to that of created_shippingbox. Here, first_name, last_name, address1, city, country, phone, postcode and mail come from resynchronization; only status and tracking_number are actually modified by the caller.

deleted_shippingbox

Object sent: full shipment, even after deletion (the state is re-read at the time of delivery, regardless of the deletion). Delay before delivery: none. Full example: in the OpenAPI contract (/openapi/ciklik-webhooks.yaml), webhook deleted_shippingbox.

When it is sent

• Deletion through the vendors API, DELETE /deliveries/{id}.
• Validation of a withdrawal request by the Ciklik team, with the deletion option: only future shipments are deleted.
• Refund of a transaction by the Ciklik team, with the deletion option: all shipments of the order are deleted, past and future.

When it is not sent

Shipments deleted without any delivery

Pausing a subscription by the Ciklik team, with the option to delete future shipments, removes them through a bulk write that does not trigger a webhook. No deleted_shippingbox is sent in that case: an integrator who synchronizes shipments only through webhooks keeps in their database shipments that no longer exist at Ciklik.

What changed contains

Always {"deleted": true}, whatever the shipment.

Cascading effects

No cascading effect specific to deletion is documented: it occurs at the end of the journey (validated withdrawal or refund), with no other associated webhook.

Example

changed of deleted_shippingbox

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

The rest of the payload is identical to that of created_shippingbox.