Skip to content

Add delivery_bill_id to shipment fulfillment payload - #291

Open
Marvin-Magmodules wants to merge 2 commits into
masterfrom
feature/delivery-bill-id
Open

Marvin-Magmodules wants to merge 2 commits into
masterfrom
feature/delivery-bill-id

Conversation

@Marvin-Magmodules

@Marvin-Magmodules Marvin-Magmodules commented Sep 14, 2026 •

Copy link
Copy Markdown
Member

Channable requires a delivery_bill_id on every shipment update: the number of the delivery note included in the parcel. Marketplaces such as Conrad use it to match their invoice to the physical delivery the customer received.

What it does

Default — the Magento shipment increment ID. Works out of the box for every merchant, no configuration or manual input. It is already printed on Magento's standard packing slip, so the number in the parcel matches the number Channable receives.

ERP override. Merchants who print delivery notes from an ERP (DSN-123) supply their own number through the channable_delivery_bill_id extension attribute on the shipment, either on creation:

POST /rest/V1/order/{orderId}/ship
{
  "tracks": [{"carrier_code": "dhl", "title": "DHL", "track_number": "3S123456789"}],
  "arguments": {"extension_attributes": {"channable_delivery_bill_id": "DSN-123"}}
}

or afterwards, when a shipping extension created the shipment:

POST /rest/V1/shipment
{"entity": {"entity_id": 12, "order_id": 34, "extension_attributes": {"channable_delivery_bill_id": "DSN-123"}}}

Empty falls back to the increment ID, so shipping extensions that know nothing about the field keep working unchanged.

Multi-shipment fixes

  • Shipment entries now carry shipment_id. Previously id held the order increment ID, so two shipments of the same order were indistinguishable.
  • The order status endpoint merged all shipments into one fulfillment object with +=, silently dropping the tracking data of the second and later shipments. It now returns a fulfillments array with one entry per shipment. The existing fulfillment key is kept and holds the most recent shipment, so the Channable side does not break.

Changes

  • Service/Order/Shipping/Fulfillment.php — delivery_bill_id with ERP override and fallback
  • Service/Webhook/Shipments.php — shipment_id per entry
  • Service/Webhook/OrderStatus.php — one fulfillment entry per shipment
  • Plugin/Shipment/DeliveryBillId.php — load and persist the extension attribute
  • Plugin/Shipment/DeliveryBillIdArgument.php — accept the value as shipment creation argument
  • etc/db_schema.xml — channable_delivery_bill_id on sales_shipment (nullable varchar, instant DDL)
  • etc/module.xml — completed the module sequence

Testing

12 new E2E tests in Test/End-2-end/tests/order/delivery-bill-id.spec.ts covering the default, both ERP paths, the fallback and multi-shipment orders. Full suite green on the VPS: 62 passed.

Merchant documentation added in docs/SHIPMENTS.md + docs/SHIPMENTS_NL.md.

Channable requires a delivery_bill_id on every shipment update: the number of
the delivery note included in the parcel, used by marketplaces such as Conrad
to match their invoice to the delivery.

- Defaults to the Magento shipment increment ID, which is printed on the
  standard packing slip
- ERP systems can supply their own number through the channable_delivery_bill_id
  extension attribute, on shipment creation or on an existing shipment
- Add shipment_id to the shipments webhook so multiple shipments of the same
  order can be told apart
- Return one fulfillment entry per shipment on the order status endpoint; the
  previous merge flattened them and lost tracking data of later shipments
- Add Magento module dependencies to the module sequence
- Add E2E coverage and merchant documentation
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant