Fulfillment & money flow

How fulfillment + shipping money flows through the system once an order is paid. Covers all three fulfillment methods (shipping carrier, same_day courier, meetup in-person) and every cancel/refund path.

The four layers (recap)

The order machine fires normalized events; webhook handlers stamp payments.provider_status_raw / fulfillments.provider_status_raw so the raw provider truth is always preserved alongside cüte's normalized read.

When is the Melhor Envio label bought?

When the seller clicks "Print label", NOT on payment_confirmed.

payment_confirmed
  → fulfillments.status = awaiting_seller
  → buyer's shipping fee held (buyer protection) alongside item price
  → NO label purchased yet

seller clicks "Print label" on the order card
  → cüte calls ME: addToCart → checkout (buys label from ME wallet)
  → generateLabel + printLabel
  → fulfillments.gatewayShipmentId set, fulfillments.labelUrl set
  → fulfillments.status = label_generated
  → PDF opens for the seller
  → orders.shippedAt is STILL null — printing != shipping

seller drops the parcel at a ME service point
  → ME scans it
  → ME webhook order.posted → cüte fires `seller_shipped` event
  → orders.shippedAt = now
  → fulfillments.status = posted
  → buyer sees "In transit"

Why printing != shipping: if we set shippedAt = now the moment seller prints, the notShipped deadline guard would stop protecting the buyer. A seller who prints but never drops off would keep the money held indefinitely. Tying shippedAt to the carrier's scan keeps the 5-business-day deadline cron honest.

Why not on payment_confirmed?

1. Cüte funds its ME wallet from float. If 100 paid orders sit unshipped, that's R$ 100×label-cost locked.
2. Cancellations between payment + ship are common (seller out of stock, item damaged, buyer changed mind). Buying the label early means wasting ME wallet money on refunds — and ME does NOT always refund cancelled labels.
3. Industry standard: Mercado Livre, Etsy, Shopify all buy at ship time.

Happy path — shipping

Happy path — same_day (Lalamove / Uber Direct)

Happy path — meetup

Money flow — what the buyer pays vs. what gets refunded

Buyer's total at checkout =   item price + buyer protection fee + shipping/delivery fee (0 for meetup)

The Pagar.me split at capture:

All cancel + refund cases

Meetup / same_day variant: there's no carrier label to consume. The "delivery fee" line on cancellations is:

• For meetup: 0 anyway
• For same_day: refundable only if the courier was never dispatched. Once dispatched (fulfillments.status = courier_dispatched or later), Lalamove charges Cüte for the courier's run regardless — refund the buyer minus the courier cost (admin decision).

What does orders.payout_status mean at each stage?

Deadlines & timers

Who can do what, when

Failure modes worth knowing

• Cüte's ME wallet is empty when seller clicks ship → seller_shipped fails, order stays at active, fulfillments.status stays awaiting_seller. Seller sees error toast. Cüte ops needs to top up the ME wallet, then seller retries.
• ME generates label but order.posted webhook never arrives → fulfillments.status stays label_generated (set at purchase time); orders.shippedAt stays null. The seller_shipped event (fired by order.posted) is what advances both. The notShipped ship-deadline cron still applies — if it fires before ME catches up, the order cancels and the buyer is refunded. Admin can override manually.
• Seller marks shipped but the parcel never moves at ME → 5-biz-day deadline is from payment_confirmed, not from ship. If seller ships on day 4, deadline still fires on day 5 by the cron — which would auto-cancel a shipped order. The cron is gated by notShipped guard, so this is fine.
• Buyer never confirms after delivery → 2-day timer fires auto_accept_timeout (gated by noActiveDispute). If the dispute region is active, payout stays blocked until the dispute closes.
• Buyer disputes during the acceptance window → dispute_opened flips order to disputed, payout_status = blocked. Auto-accept is disabled. Cron skips.