# Changelog > Changes to the Melonn API, newest first. ### General Information - **Change Type:** `No-breaking` - **Summary:** Seller products accept two new optional fields to configure the minimum shelf life, in days, of perishable products. #### Affected Endpoints ``` POST /seller-products PUT /seller-products/:sku ``` #### New fields - `inbound_minimum_shelf_life` (integer, days, >= 1): minimum remaining shelf life a unit must have to be received into a Melonn warehouse. - `storage_minimum_shelf_life` (integer, days, >= 1): minimum remaining shelf life a unit must keep while stored to remain available for orders. Both are optional. `null` is not accepted. On update, omitted fields keep their stored value. #### Validation When both values are set, `inbound_minimum_shelf_life` must be greater than or equal to `storage_minimum_shelf_life`. On update, a field you do not send is compared using its stored value. Otherwise the request returns `400`: ```json { "message": "Inbound minimum shelf life must be greater than or equal to the storage minimum shelf life", "statusCode": 400, "errorCode": "INBOUND_MINIMUM_SHELF_LIFE_BELOW_STORAGE" } ``` #### Additional Notes - **Compatibility/Impact:** ✅ **100% backward compatible.** Pure addition to the request bodies: no field was removed or renamed. ### General Information - **Change Type:** `No-breaking` - **Summary:** List Seller Suppliers now returns each supplier's unpacking configuration per warehouse. This entry also corrects the documentation of the three seller supplier endpoints to match their actual behavior. #### Affected Endpoints ``` GET /seller-suppliers POST /seller-suppliers PUT /seller-suppliers/:id ``` #### List Seller Suppliers — `warehouse_configurations` Each supplier with **at least one** unpacking configuration now includes `warehouse_configurations`, ordered by `warehouse_id`. Each item carries `id`, `seller_supplier_id`, `warehouse_id`, `unpacking_type` and `validation_type`. Suppliers without configurations are unchanged: the key is **absent**, not an empty array. Treat a missing key as "no configuration". The warehouse default (`DEFERRED` / `FREE`) applies. #### Documentation corrections No behavior changed in this section. The documentation now matches what the API already does. - **List Seller Suppliers:** the pagination object is `meta_data` and includes `total_count`. It was documented as `meta`. `per_page` accepts up to 100. - **Update Seller Supplier:** the path parameter accepts your own `external_id` as well as the Melonn `id`. It is matched against `external_id` first. - **Update Seller Supplier:** each warehouse configuration you send is written in full. An omitted `unpacking_type` or `validation_type` is reset to its default rather than kept. Always send both. - **Create / Update Seller Supplier:** sending `warehouse_configurations` without a negotiated agreement with Melonn returns `403`, not `422`. `422` is reserved for invalid configurations. #### Additional Notes - **Compatibility/Impact:** ✅ **100% backward compatible.** Pure addition to the list response: no key was removed or renamed. ##### Added - **Create Seller Supplier** (`POST /seller-suppliers`): create suppliers from your integration, optionally with an unpacking configuration per warehouse (`warehouse_configurations`). - **Update Seller Supplier** (`PUT /seller-suppliers/{id}`): update supplier fields, warehouse configurations, or both. Send only what changes. - `external_id` on suppliers: your own identifier, unique per seller. Creating a supplier with an existing `external_id` returns `409` with the id of the existing supplier. - **List Seller Suppliers**: new optional filter `external_id`. - **Get Supplier Order**: new `attachments` array with the order's documents and reception photos, each with a signed download URL valid for 1 hour. ##### Changed - `unpacking_type` and `validation_type` can only be changed from their defaults (`DEFERRED` / `FREE`) under a negotiated agreement with Melonn. Otherwise the request returns `422`. ##### Deprecated - Supplier fields `returns_address_l1`, `returns_address_l2`, `returns_city`, `returns_region` and `returns_country`: no longer required, ignored if sent, and no longer returned by **List Seller Suppliers**. ### Changed: `required[]` relaxed on Create Supplier Order, `active` added to Business ### General Information - **Change Type:** `No-breaking` - **Summary:** Ten fields are no longer required when creating a supplier order, six of them are now deprecated and discarded, and each business delivery location now reports whether it is the active one. #### Affected Endpoints ``` POST /cle/public-api/supplier-orders GET /cle/public-api/supplier-orders GET /cle/public-api/supplier-orders/:internal_order_number GET /cle/public-api/business ``` #### Create Supplier Order — fewer required fields `required[]` is now just `seller_supplier_id`, `destination_warehouse_code`, `external_order_number` and `line_items`. These ten left it: `tracking_number`, `comments`, `return_address_l1`, `return_address_l2`, `return_city`, `return_region`, `return_country`, `return_postal_code`, `courier_company_id`, `shipped_packages`. **Nothing to do if you already send them.** All ten remain declared and accepted, so existing requests keep working byte for byte. There is no sunset date and no version in which they become an error. The six `return_\*` fields are **deprecated**: accepted and discarded rather than stored. Sending them never fails the request. `shipped_packages` is absent-or-non-empty — omitting it is valid, an empty array is still rejected. #### Supplier order responses — deprecated keys are omitted For orders created **after** this change, the six `return_\*` keys are **absent** from the detail and list responses — not `null`. Orders created before it still return their stored value. If your integration reads those fields, treat a missing key as "no return address" rather than assuming presence. #### Business — `active` per delivery location Each entry in `delivery_locations` now carries `active` (boolean or null). A business can hold several locations while only one is active, and this field is what distinguishes them. `null` means it was never set. Pure addition: no existing key was removed or renamed. #### Additional Notes - **Compatibility/Impact:** ✅ **100% backward compatible.** The contract only relaxes and adds. No request that works today stops working. - The response change is an omission of deprecated fields, so clients that already tolerate their absence need no update. ### New: for Sell Order API ### General Information - **Change Type:** `No-breaking` - **Summary:** Enter a new access point to obtain delivery documents #### Affected Endpoints ``` POST /sell-orders/:external_order_number/delivery-documents ``` #### Additional Notes - **Compatibility/Impact:** ✅ **100% backward compatible** - Does not affect existing query ### New: Supplier Order States ### General Information - **Change Type:** `No-breaking` - **Summary:** Updating the status of suppliers orders and their life cycle. #### Affected Endpoints ``` GET /supplier-orders GET /supplier-orders/:internal_order_number ``` ### New: for Courier companies API ### General Information - **Change Type:** `No-breaking` - **Summary:** Enter a new access point to obtain courier companies. #### Affected Endpoints ``` POST /courier-companies ``` #### Additional Notes - **Compatibility/Impact:** ✅ **100% backward compatible** - Does not affect existing query #### 1 - New: Supplier Orders API ##### General Information | Field | Value | | --- | --- | | **Change Type** | No-breaking | | **Summary** | Expose new endpoints for list, get, create and cancel supplier orders | ##### Affected Endpoints ``` GET /cle/public-api/supplier-orders/ GET /cle/public-api/supplier-orders/:internal_order_number POST /cle/public-api/supplier-orders/ POST /cle/public-api/supplier-orders/:internal_order_number/cancel GET /cle/public-api/seller-suppliers/ ``` ##### Additional Notes **Compatibility/Impact:** ✅ 100% backward compatible - Does not affect existing query * * * #### 2 - New: Webhook Events Added ##### General Information | Field | Value | | --- | --- | | **Change Type** | No-breaking | | **Summary** | The following events are added to the list of events for webhook configuration. | ##### Events - Supplier Order - Created - Supplier Order - Cancelled - Supplier Order - Closed - Supplier Order Package - Unpacked ##### Additional Notes **Compatibility/Impact:** ✅ 100% backward compatible - Does not affect existing webhook configurations ### 1 - New: Enhanced Get Return Order Details endpoint ### General Information - **Change Type**: No-breaking - **Summary**: Added new fields to line\_items\_summary response to include received quantity information for unpacked return orders #### Affected Endpoints ``` GET /return-orders/{internalOrderNumber} ``` **New Response Fields:** - `qty_received_ok`: Quantity of items received in good condition - `qty_received_ok_restocked`: Quantity of items received in good condition that were restocked - `qty_received_ok_not_restocked`: Quantity of items received in good condition that were not restocked - `qty_received_defective`: Quantity of items received in defective condition For composite products these fields are available inside the `content` array. The `content` field is now optional (can be `undefined` instead of empty array when product is not composite). #### Additional Notes **Compatibility/Impact: ✅ 100% backward compatible** - New fields are optional and only present when return order has been unpacked, ### 2 - New: webhook events added ### General Information - **Change Type**: No-breaking - **Summary:** The following events are added to the list of events for webhook configuration. - `Buyer Return Order - Canceled` - `Buyer Return Order - Unpacked` #### Additional Notes - `Buyer Return Order - Canceled`: Triggered when a return order is canceled. A return order can only be canceled if it is in "Created" or "TransportServiceRequested" state. Event: `BUYER_RETURN_ORDER/CANCELED` - `Buyer Return Order - Unpacked`: Triggered when the return order items have been unpacked and verified at the warehouse. ### 1 - New: V2 for Buyer return orders API ### General Information - **Change Type:** `No-breaking` - **Summary:** expose new endpoint for list and cancel buyer return orders #### Affected Endpoints ``` GET /buyer-return-orders/v2/ GET /buyer-return-orders/v2/:internal_order_number POST /buyer-return-orders/v2/:internal_order_number/cancel ``` #### Additional Notes - **Compatibility/Impact:** ✅ **100% backward compatible** - Does not affect existing query ### 2 - New: webhook events added #### General Information - **Change Type:** `No-breaking` - **Summary:** The following events are added to the list of events for webhook configuration. 1. Buyer Return Order - Created 2. Buyer Return Order - Received at Warehouse 3. Buyer Return Order - Label Generated ### 1 - New: get promise data from Sell Order API ### General Information - **Change Type:** `No-breaking` - **Summary:** Optional parameter `fields=sell_order_promises` is added to the GET endpoint for sell orders to provide delivery promise information #### Affected Endpoints ``` GET /sell-orders/:external_order_number ``` #### Migration ##### Steps to follow: 1. **No migration required** - The change is completely optional and backward compatible 2. **To get promises:** Add `?fields=sell_order_promises` to existing query #### Quick Examples ##### Request (without promises → with promises) **Without promises:** ``` GET /sell-orders/TEST_ORDER_001 ``` **With promises:** ``` GET /sell-orders/TEST_ORDER_001?fields=sell_order_promises ``` ##### Response (new fields added) **Additional fields in current response:** ```json { "sell_order_promise_info": { "promise_source": "melonn_internal", "external_promise_info": { "promise_type": "DELIVERY", "promise_value": { "max": "2025-05-20 01:30:00" } }, "pack_ready_to_sort_promise_min": "2025-12-17T08:00:00.000Z", "pack_ready_to_sort_promise_max": "2025-12-17T18:00:00.000Z" }, "sell_order_attempt": [{ "current": true, "ready_to_ship_promise_min": "2025-12-17T08:00:00.000Z", "ready_to_ship_promise_max": "2025-12-17T18:00:00.000Z", "delivery_promise_min": "2025-12-20T08:00:00.000Z", "delivery_promise_max": "2025-12-20T18:00:00.000Z" }] } ``` #### Additional Notes - **Compatibility/Impact:** ✅ **100% backward compatible** - Does not affect existing query - **Available fields:** - `sell_order_promise_info`: Information about packaging and processing promises - `sell_order_attempt`: Information about shipping and delivery promises - **Recommended usage:** Include the parameter only when promise information is needed to optimize performance ### 2 - New: webhook events added #### General Information - **Change Type:** `No-breaking` - **Summary:** The following events are added to the list of events for webhook configuration. 1. Orden de venta - Cancelada 2. Orden de venta - Entregada al comprador 3. Orden de venta - Items Reservados 4. Orden de venta - Recogida por el comprador 5. Orden de venta - Recibida válida 6. Orden de venta - En tránsito