Delivery flow
Learn how quotes become paid transfers and how to track their state.
A quote and a transfer are separate resources. The quote discovers available products and prices; the transfer commits to one product and charges the merchant balance.
Quote a delivery
Call POST /options with:
- An active pickup
warehouseId - The destination coordinates and address
- A parcel size:
SMALL,MEDIUM, orLARGE - Fragile and perishable flags
- The
DOOR_TO_DOORdelivery type
The response contains a quote id and a products object. Each key in products is a valid productKey for transfer creation.
Persist the exact pair
Keep the quote id and selected product key together. A product key is meaningful only within the quote that returned it.
Create and pay
Call POST /transfer using the quote ID as matchmakingId, the selected productKey, and recipient details.
The operation performs the following work atomically:
- Validates that the quote exists and is still pending.
- Resolves the selected product and payable amount.
- Creates the transfer, parcel, delivery metadata, and tracking steps.
- Subtracts the amount from the merchant balance.
- Marks the quote as completed.
A completed quote cannot be used again. If the request succeeds but your client loses the response, do not blindly retry with the same quote. Query your internal records or contact Melo support before creating a new quote.
Track state
Call GET /transfer/{transferId} to retrieve the current state:
| State | Meaning |
|---|---|
inProgress | The delivery is active. |
completed | The delivery reached its final successful state. |
failed | The delivery ended unsuccessfully. |
The response also contains the public trackingCode, pickup and destination details, the selected delivery option, and payment timing metadata when available.
Recommended integration behavior
- Store Melo's transfer ID with your own order ID.
- Store the tracking code for customer-facing support.
- Poll with backoff rather than on every page view.
- Treat network timeouts as an unknown outcome, especially for transfer creation.
- Log Melo error
typevalues, but redact credentials and personal data.