This tutorial walks you through the orosy Buyer API end to end: search for a product, add it to a cart, place a test order, and follow it all the way to confirmed reservation.
orosy_demo_...). Don't have one yet? Sign up on the buyer portal, get approved (usually quick), and issue your own key. The portal UI is in Japanese — the English guide walks you through every step.curl runs, you can start.Running the business side? If you'd rather understand the whole picture without code, we have a service overview. Write to wholesale_shop_api@orosy.com.
First, confirm you can reach the API. This is the one endpoint that needs no authentication.
curl https://wholesale-api.orosy.com/v1/health
{"status":"ok","stage":"prod","time":"2026-08-10T15:00:30.962Z"}
If status: ok comes back, you're ready.
Search across multiple suppliers and roughly 200,000 products with a single query. Beyond keywords, you can filter by price band (min_price / max_price), stock (min_stock), and category.
curl -H "Authorization: Bearer orosy_demo_xxxxxxxx" \
"https://wholesale-api.orosy.com/v1/products?q=マグカップ&per_page=2"
{
"total": 128,
"items": [
{
"product_id": "de300001-0000-4000-8000-000000000001",
"title": "Demo Ceramic Mug 350ml (sample item)",
"brand": "",
"delivery_group": "demo-warehouse",
"min_buyer_price": 800,
"min_retail_price": 1200,
"variation_count": 1,
"images": ["https://wholesale-media.orosy.com/img/…"]
},
…
]
}
"Mug" alone returns 128 hits. Both buyer_price (wholesale price) and retail_price (suggested retail) come back, so you can pick while watching your margin.
Next, fetch the product detail and note the variation_id (the per-color, per-size ID) you'll use when ordering:
curl -H "Authorization: Bearer orosy_demo_xxxxxxxx" \
"https://wholesale-api.orosy.com/v1/products/de300001-0000-4000-8000-000000000001"
{
"title": "Demo Ceramic Mug 350ml (sample item)",
"variations": [
{
"variation_id": "de300002-0000-4000-8000-000000000002",
"jan": "4900000000001",
"variant_label": "White 350ml (sample)",
"buyer_price": 800,
"retail_price": 1200,
"order_unit": "1",
"stock_level": "in_stock",
"stock_observed_at": "2026-06-23 21:03:59+00"
}
]
}
You get the JAN code, the order unit (order_unit), the stock state, and the time it was observed.
Even when products come from different suppliers, there is one cart.
curl -X PUT -H "Authorization: Bearer orosy_demo_xxxxxxxx" \
-H "Content-Type: application/json" \
-d '{"variation_id": "de300002-0000-4000-8000-000000000002", "qty": 2}' \
"https://wholesale-api.orosy.com/v1/cart/items"
Use GET /v1/cart to see the contents and the estimate:
curl -H "Authorization: Bearer orosy_demo_xxxxxxxx" \
"https://wholesale-api.orosy.com/v1/cart"
{
"items": [ { "variation_id": "de3000…", "qty": 2, "buyer_price": 800, … } ],
"groups": [
{
"group_code": "demo-warehouse",
"subtotal": 1600,
"supplier_fee": 800,
"free_threshold": 10000,
"messages": ["Add ¥8,400 more to this group for free supplier shipping (currently ¥800)."]
}
],
"estimate": {
"subtotal_standard": 2400,
"tax_standard": 240,
"shipping_fee": 800,
"total": 2640,
"currency": "JPY"
}
}
Before you order, you can see the total with shipping, the free-supplier-shipping threshold, and tax (8% / 10% per line) already worked out. The response even carries the "Add ¥8,400 more to get free supplier shipping" message, ready to drop straight onto your screen.
Specify a shipping address and confirm the order. Orders placed with a demo key are test orders, so run it without worry.
curl -X POST -H "Authorization: Bearer orosy_demo_xxxxxxxx" \
-H "Content-Type: application/json" \
-d '{
"ship_to": {
"postal_code": "530-0001",
"state": "大阪府",
"city": "大阪市北区",
"line1": "梅田1-2-2",
"recipient": "orosy テスト太郎",
"phone": "06-0000-0000"
},
"note": "はじめてのテスト注文"
}' \
"https://wholesale-api.orosy.com/v1/orders"
HTTP 201
{
"order_id": "de300003-0000-4000-8000-000000000003",
"status": "pending_confirmation",
"breakdown": { "total": 2640, "tax_standard": 240, "shipping_fee": 800, … },
"payment": { "status": "requires_capture" },
"items": [ { "item_no": 1, "qty": 2, "confirmed_qty": null, … } ]
}
Worth knowing:
409 PRICE_CHANGED and won't confirm on its own. If the new price is fine, add "accept_price_change": true and retry (the design keeps you from unknowingly buying at a higher price).Idempotency-Key header. A resend with the same key returns the original order as-is (even without the header, a same-cart double submit is deduplicated server-side).pending_confirmation (waiting for the reservation). confirmed_qty is still null.In real operation, once you order, orosy buys from the supplier and the order moves through "reservation confirmed → shipped → delivered." With a demo key, you can replay this transition yourself in a simulator.
# Move the order to a state where every item's reservation is confirmed
curl -X POST -H "Authorization: Bearer orosy_demo_xxxxxxxx" \
-H "Content-Type: application/json" \
-d '{"action": "confirm_full"}' \
"https://wholesale-api.orosy.com/v1/orders/de300003-…/simulate"
# Check the state
curl -H "Authorization: Bearer orosy_demo_xxxxxxxx" \
"https://wholesale-api.orosy.com/v1/orders/de300003-…"
{
"status": "confirmed",
"confirmed_total": 2640,
"payment": { "status": "succeeded" },
"items": [ { "item_no": 1, "qty": 2, "confirmed_qty": 2 } ],
"confirmed_at": "2026-07-03 05:12:56+00"
}
pending_confirmation → confirmed, confirmed_qty: null → 2, and the payment moved to succeeded.
You can also try confirm_partial (only some stock reserved) and cancel. The point of the simulator is to let you confirm what happens to billing when part of an order is out of stock (you're billed only for what arrives; if everything is out of stock, billing is zero) in code, before you go live.
What you just did:
confirm_partial → see the "Partial out-of-stock and billing" guideStuck? wholesale_shop_api@orosy.com