# Integrations — magento-shippingfields

> **Last verified:** 2026-02-26 (Europe/London)
> **Owner:** Engineering
> **Related:** [API.md](API.md) | [BOUNDARIES.md](BOUNDARIES.md)

---

## Integration Catalogue

| Name | Direction | Mechanism | Purpose | Criticality | Evidence |
|------|-----------|-----------|---------|-------------|----------|
| Magento Checkout — `ShippingInformationManagement` | Inbound plugin | `beforeSaveAddressInformation` plugin | Capture `shipping_date`/`shipping_message` from request JSON during shipping save | HIGH | `src/Plugin/ShippingInformationManagementPlugin.php` |
| Magento Quote — `QuoteRepository` | Bidirectional plugin | `beforeSave`, `afterGet` plugins | Sync extension attributes with quote data | HIGH | `src/Plugin/QuoteRepositoryPlugin.php` |
| Magento Quote — `CartRepository` | Bidirectional plugin | `beforeSave`, `afterGet` plugins | Sync extension attributes with cart data | HIGH | `src/Plugin/CartRepositoryPlugin.php` |
| Magento Sales — `OrderRepository` | Bidirectional plugin | `beforeSave`, `afterGet` plugins | Sync extension attributes with order data | HIGH | `src/Plugin/OrderRepositoryPlugin.php` |
| Magento Sales — `QuoteToOrder` | Plugin | `aroundConvert` plugin | Transfer fields from quote item to order item | MEDIUM | `src/Plugin/QuoteToOrderPlugin.php` |
| Magento Sales — `sales_model_service_quote_submit_before` | Inbound event | Observer | Copy `shipping_date`/`shipping_message` from quote to order on submission | HIGH | `src/Observer/QuoteSubmitBefore.php` |
| Magento Checkout — `PaymentInformationManagement` | Inbound plugin | `beforeSavePaymentInformationAndPlaceOrder` plugin | Debug logging only | LOW | `src/Plugin/PaymentInformationManagementPlugin.php` |
| portalpeople/magento-disableddates | Inbound | `CollectionFactory` DB read | Provide disabled dates for date picker | MEDIUM | `src/Model/Checkout/DeliveryDateConfigProvider.php` |
| Frontend Checkout JS | Bidirectional | REST API `POST /V1/carts/mine/save-shipping-fields` | Save fields from checkout UI to quote | HIGH | `src/etc/webapi.xml`, `src/view/frontend/web/js/action/set-shipping-information-mixin.js` |

---

## Integration Detail

### 1. Frontend Checkout — Shipping Step Capture

The `set-shipping-information-mixin.js` intercepts the shipping step "Next" button click. It reads `shipping_date` and `shipping_message` from the Magento `checkoutProvider` data, then calls the REST API endpoint before allowing the shipping step to complete.

```mermaid
%% Title: magento-shippingfields — Shipping Step Integration (L3)
%% Layer: L3
%% Owner: Engineering
%% Last verified: 2026-02-26 (Europe/London)
%% Scope: Frontend shipping step through to quote save
%% Excludes: Date picker configuration, payment step

sequenceDiagram
  autonumber
  actor Customer
  participant UI as Checkout Shipping Step
  participant ShippingMixin as set-shipping-information-mixin
  participant REST as REST API
  participant Plugin as ShippingInformationManagementPlugin
  participant Quote as quote DB

  Customer->>UI: Click Next (shipping step)
  UI->>ShippingMixin: beforeSaveAddressInformation
  ShippingMixin->>REST: POST /V1/carts/mine/save-shipping-fields
  REST->>Quote: Save shipping_date + shipping_message
  REST-->>ShippingMixin: true
  ShippingMixin->>Plugin: (continues) saveAddressInformation
  Plugin->>Quote: Set fields (secondary path)
```

---

### 2. Quote to Order — Observer

The `QuoteSubmitBefore` observer fires when Magento is about to convert a quote to an order. It reads `shipping_date` and `shipping_message` from the quote and sets them on the order object before Magento persists the order.

---

### 3. portalpeople/magento-disableddates (Optional Dependency)

`DeliveryDateConfigProvider` reads from the `PortalPeople\DisabledDates` collection to populate the date picker's disabled dates. This dependency is **not declared in `composer.json`**. If the module is absent, the disabled dates feature will fail.

`UNKNOWN — Requires Clarification`: Does `DeliveryDateConfigProvider` guard against this module being absent?

---

### 4. magento-orderwebhook (Downstream Consumer)

The `magento-orderwebhook` module reads `shipping_date` and `shipping_message` from `sales_order` (via `OrderDataBuilder`) and includes them in the NGauge webhook payload. This module is a downstream consumer — no direct coupling, but data written here is consumed there.

`UNKNOWN — Requires Clarification`: Is this cross-module dependency documented in `magento-orderwebhook/docs/INTEGRATIONS.md`?

---

## Confirmed Facts

- Six plugins are registered in `src/etc/di.xml`.
- Observer registered in `src/etc/events.xml`.
- REST API registered in `src/etc/webapi.xml`.
- Dual save path exists: REST API + `ShippingInformationManagementPlugin` — both write to quote.
- Dual transfer path exists: observer + `QuoteToOrderPlugin` — both transfer quote → order.

---

## Unknowns

1. `UNKNOWN — Requires Clarification`: Is `portalpeople/magento-disableddates` a required or optional dependency?
2. `UNKNOWN — Requires Clarification`: Is the dual save path intentional? Which path is authoritative?
3. `UNKNOWN — Requires Clarification`: Does `PaymentInformationManagementPlugin` need to remain registered if it only logs?
4. `UNKNOWN — Requires Clarification`: Is there a documented cross-module integration contract with `magento-orderwebhook` for `shipping_date` and `shipping_message`?

---

## Evidence

- `/modules/magento-shippingfields/src/etc/di.xml`
- `/modules/magento-shippingfields/src/etc/events.xml`
- `/modules/magento-shippingfields/src/etc/webapi.xml`
- `/modules/magento-shippingfields/src/Plugin/ShippingInformationManagementPlugin.php`
- `/modules/magento-shippingfields/src/Plugin/QuoteRepositoryPlugin.php`
- `/modules/magento-shippingfields/src/Plugin/CartRepositoryPlugin.php`
- `/modules/magento-shippingfields/src/Plugin/OrderRepositoryPlugin.php`
- `/modules/magento-shippingfields/src/Plugin/QuoteToOrderPlugin.php`
- `/modules/magento-shippingfields/src/Plugin/PaymentInformationManagementPlugin.php`
- `/modules/magento-shippingfields/src/Observer/QuoteSubmitBefore.php`
- `/modules/magento-shippingfields/src/Model/Checkout/DeliveryDateConfigProvider.php`
- `/modules/magento-shippingfields/src/view/frontend/web/js/action/set-shipping-information-mixin.js`
