Partial out-of-stock and billing

In wholesale sourcing, "part of what you ordered was out of stock" happens all the time. orosy bills only for what is reserved (what actually arrives). This guide confirms that behavior in the test environment.

The rule

At order time, billing is not yet fixed (status: pending_confirmation).
Only what the supplier confirms as reserved is billed, as confirmed_total.
If everything is out of stock, billing is zero. There is no "charge more up front and refund later."

See it for yourself (demo key)

Replay a case where you order 2 units and only 1 can be reserved.

1. Order 2 units. The order-time estimate is ¥2,640 total (goods ¥800 × 2 + tax + shipping ¥800).

2. Simulate "only 1 could be reserved":

curl -X POST -H "Authorization: Bearer orosy_demo_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"action": "confirm_partial", "items": [{"item_no": 1, "confirmed_qty": 1}]}' \
  "https://wholesale-api.orosy.com/v1/orders/<order_id>/simulate"

3. Check the order:

{
  "status": "partially_confirmed",
  "breakdown":           { "total": 2640, … },   // the order-time amount
  "confirmed_total": 1760,                        // what you are actually billed
  "confirmed_breakdown": {
    "subtotal_standard": 1600,
    "tax_standard": 160,
    "shipping_fee": 800,
    "total": 1760
  },
  "items": [ { "qty": 2, "confirmed_qty": 1 } ],
  "payment": { "status": "succeeded" }
}

How to read it

Order-time estimate ¥2,640 → amount actually billed ¥1,760.

Field	At order time	After confirmation
Status	`pending_confirmation`	`partially_confirmed`
Items	2 units (¥800 × 2)	only 1 reserved (`confirmed_qty: 1`)
Amount billed	¥2,640 (estimate)	¥1,760 (1 reserved unit + tax + shipping)

confirmed_breakdown is authoritative for billing; the order-time breakdown is kept as-is, so you can reconcile the difference in your accounting.
Shipping stayed the same in our measurement (delivery happens regardless of the reserved quantity).
If you do not want to allow partial reservation: the current API has no parameter on the order request to disable it (the order response's allow_partial shows the setting).

Implementation tips

After ordering, poll GET /v1/orders/{order_id} and update your inventory and sales screens based on whether status moved to confirmed / partially_confirmed / cancelled.
To reconcile what you bill your own customers against what orosy bills you for sourcing, use confirmed_qty and confirmed_breakdown.
The qualified invoice is issued against the confirmed amount too (GET /v1/me/orders/{order_id}/invoice; see the API reference for details).