Changelog - Melonn API

New: minimum shelf life fields on Seller Products

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:

{
    "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.

Changed: List Seller Suppliers returns warehouse configurations

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.

New: Create and Update Seller Supplier

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

New: Supplier Orders API

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

New: Enhanced Get Return Order Details endpoint

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.

New: V2 for Buyer return orders API

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.

Buyer Return Order - Created
Buyer Return Order - Received at Warehouse
Buyer Return Order - Label Generated

New: get promise data from Sell Order API

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:

No migration required - The change is completely optional and backward compatible
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:

{
  "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.

Orden de venta - Cancelada
Orden de venta - Entregada al comprador
Orden de venta - Items Reservados
Orden de venta - Recogida por el comprador
Orden de venta - Recibida válida
Orden de venta - En tránsito

​General Information

​Affected Endpoints

​New fields

​Validation

​Additional Notes

​General Information

​Affected Endpoints

​List Seller Suppliers — warehouse_configurations

​Documentation corrections

​Additional Notes

Added

Changed

Deprecated

​Changed: required[] relaxed on Create Supplier Order, active added to Business

​General Information

​Affected Endpoints

​Create Supplier Order — fewer required fields

​Supplier order responses — deprecated keys are omitted

​Business — active per delivery location

​Additional Notes

​New: for Sell Order API

​General Information

​Affected Endpoints

​Additional Notes

​New: Supplier Order States

​General Information

​Affected Endpoints

​New: for Courier companies API

​General Information

​Affected Endpoints

​Additional Notes

​1 - New: Supplier Orders API

General Information

Affected Endpoints

Additional Notes

​2 - New: Webhook Events Added

General Information

Events

Additional Notes

​1 - New: Enhanced Get Return Order Details endpoint

​General Information

​Affected Endpoints

​Additional Notes

​2 - New: webhook events added

​General Information

​Additional Notes

​1 - New: V2 for Buyer return orders API

​General Information

​Affected Endpoints

​Additional Notes

​2 - New: webhook events added

​General Information

​1 - New: get promise data from Sell Order API

​General Information

​Affected Endpoints

​Migration

Steps to follow:

​Quick Examples

Request (without promises → with promises)

Response (new fields added)

​Additional Notes

​2 - New: webhook events added

​General Information

General Information

Affected Endpoints

New fields

Validation

Additional Notes

General Information

Affected Endpoints

List Seller Suppliers — `warehouse_configurations`

Documentation corrections

Additional Notes

Changed: `required[]` relaxed on Create Supplier Order, `active` added to Business

General Information

Affected Endpoints

Create Supplier Order — fewer required fields

Supplier order responses — deprecated keys are omitted

Business — `active` per delivery location

Additional Notes

New: for Sell Order API

General Information

Affected Endpoints

Additional Notes

New: Supplier Order States

General Information

Affected Endpoints

New: for Courier companies API

General Information

Affected Endpoints

Additional Notes

1 - New: Supplier Orders API

2 - New: Webhook Events Added

1 - New: Enhanced Get Return Order Details endpoint

General Information

Affected Endpoints

Additional Notes

2 - New: webhook events added

General Information

Additional Notes

1 - New: V2 for Buyer return orders API

General Information

Affected Endpoints

Additional Notes

2 - New: webhook events added

General Information

1 - New: get promise data from Sell Order API

General Information

Affected Endpoints

Migration

Quick Examples

Additional Notes

2 - New: webhook events added

General Information