Shipping and delivery

A listing reaches the buyer in one of a few ways, and who moves it depends on the listing. mongrl prices it; your checkout offers the choices and shows the quote.

Who moves it

Every listing has fulfilment:

• seller: the seller ships it or hands it over. The ways they offer are in the listing’s delivery.
• marketplace: the marketplace’s team delivers it, typically because it’s stored at their showroom or warehouse (custody: stored, site).

The delivery methods

delivery.method	Offered when	Price
shipping	Seller listings with delivery.shipping, and every marketplace listing.	The seller’s shipping.price, or the marketplace’s shipping table (below). No price means “we’ll send a quote”.
pickup	Seller listings with delivery.pickup: the buyer picks it up from the seller.	Free
buyer_arranged	Seller listings with delivery.buyer_arranged: the buyer sends their own courier.	Free
collect	Marketplace listings stored at a site where site.buyer_pickup is true: the buyer collects it there.	Free

When a listing offers only one method you can leave method out. Offer the choices from the listing, then quote with the buyer’s pick.

The shipping table

Listings the marketplace moves are priced from its table, in GET /v1/marketplace → shipping:

• sizes: size classes, e.g. small parcel, armchair, sofa. Each listing has a shipping_size.
• zones: where buyers are, by countries and optional postal_prefixes. Each zone has a delivery_time to show buyers, e.g. “2–5 working days”.
• options: delivery services, e.g. standard and white glove, with an about text. Send the buyer’s pick as delivery.option (the first when left out).
• delivery: prices by option, size and zone. A missing price means a quote.
• collection: what it costs to collect a listing that’s still at the seller’s, by size and the seller’s zone. mongrl adds it to the shipping line by itself.

You don’t need to work prices out: send the address and option in the quote and show what comes back. Use the table only for hints such as “delivery from €49” or the delivery time.

The address needs at least country (and postal_code where zones use prefixes) to be priced. Without it the quote says shipping_address_needed.

Booking a delivery time

Some marketplaces let buyers choose when the delivery comes (shipping.booking: weekdays, time windows, how far ahead). It applies to paid orders that the marketplace ships to a zone it books.

GET /v1/me/orders/{id}/delivery-booking

{
  "booked": null,
  "changeable": true,
  "slots": [
    { "date": "2026-10-23", "window": "am", "label": "08–12", "full": false },
    { "date": "2026-10-23", "window": "pm", "label": "13–17", "full": true }
  ]
}

• 409 means this order has no time to book (not paid yet, collected, or the carrier arranges it). Show nothing.
• Show slots grouped by date; full ones can’t be chosen.
• Book with PUT /v1/me/orders/{id}/delivery-booking and { "date": "2026-10-23", "window": "am" }.
• changeable turns false once it’s too close to change. The booked time is in booked.

Storage fees (sellers)

When a seller asks the marketplace to store their listing (wants_storage when publishing), storage can cost a monthly fee by size after free_storage_weeks. It’s taken from the seller’s payout when it sells and shown on the order as payout.storage_fee. Show sellers shipping.storage_fees and the free weeks before they choose storage.