Sync, hold, ship and move stock
All paths below are relative to https://api.toreca-cloud.com/partner/v1. Complete authorization and connection first. See the API reference for fields, limits and responses.
1. Sync stock
- Read sites and shelves with
GET /inventory/sites. - Call
GET /inventory/changeswithout a cursor. WhilehasMore: true, passnextCursoras the nextcursor. Upsertdatabytypeandid. - Save the final cursor and resume from it next time. A webhook is a change signal; read the same feed after receiving one.
This needs inventory:read. An allocated-only connection sees only the stock the shop set aside for it. holdable reports whether a unit could be held at read time. Another operation may change it afterwards, so only the write response confirms a successful hold.
Price-only updates do not enter the unit change feed. Read current values with POST /inventory/market-values and {"ids":["unit UUID"]}: up to 200 unique IDs. A visible unit without a price has marketValue: null; missing or out-of-view units are omitted.
2. Choose the sale-to-shipping flow
Both flows need inventory:read and inventory:write, and the approving member must still have the shop permission inventory.write. Reading hold, commitment and shipment details also needs both scopes.
| Situation | Flow |
|---|---|
| Hold one sold unit and ship it | holds → optional confirm → ship |
| List units in an oripa or sale, then combine customer delivery requests after wins or purchases | commitments → allocate → shipments → ship |
Hold and ship
Send POST /inventory/holds with requestId, inventoryItemId, purpose (oripa or sale), destinationLabel and reason. An optional externalRef stores your own reference.
| Operation | Result and limits |
|---|---|
| Create | reserved. Optional expiresAt must be in the future, at most 90 days ahead; omitted means no expiry |
POST /inventory/holds/{id}/extend |
Change expiry while reserved |
POST /inventory/holds/{id}/release |
Cancel a reserved hold. An awaiting-shipment hold cannot be released |
POST /inventory/holds/{id}/confirm, body {} |
Settle the purchase or win as awaiting_shipment. Expiry is removed; the partner can no longer release it |
POST /inventory/holds/{id}/ship |
Ship a reserved or awaiting_shipment hold as shipped |
Batch create uses /inventory/holds/batch, release uses /release-batch and shipping uses /ship-batch. Each accepts up to 100 entries; a refusal rolls back every new change in the batch. Read back with GET /inventory/holds/{id}.
List, allocate and request shipment
- Call
POST /inventory/commitmentswithrequestId,inventoryItemId,purpose,labeland optionalexternalRef. The unit stays on its shelf and becomeson_salein an oripa or sale. No shipment exists yet. - After a win or purchase, call
POST /inventory/commitments/{id}/allocate. OptionalallocationRefrecords your order or opening reference.allocatedmeans the shop holds it for that customer. - When the customer requests delivery, call
POST /inventory/shipmentswithrequestId,commitmentIds,destinationLabelandreason. It combines up to 200 allocated commitments, which becomeshipping. - At dispatch, call
POST /inventory/shipments/{id}/ship. Put the carrier number intrackingNumber.
Batch listing, allocation and release use /inventory/commitments/batch, /allocate-batch and /release-batch. They accept up to 200 entries and succeed together or roll back together.
Before shipping, POST /inventory/shipments/{id}/cancel restores units to allocated. Release a listing or allocation with /inventory/commitments/{id}/release; cancel an open shipment first. setAside: true retains the stock allocation to this connection after release. Releasing a lost unit leaves it lost; it does not become available.
When a dispatched parcel physically returns, use POST /inventory/shipments/{id}/returns. Units return to their original shelves and receive new allocated commitments for the customer. In the response, commitmentId is the original ID and commitment.id is the new ID; update your references.
3. Shipping prices
Amounts are integers in the currency’s minor unit: whole yen for JPY. Values from 0 to 10,000,000,000 are accepted.
- For a held unit, send
saleAmountMinor. Omitted means the latest JPY market value; without either, shipping fails withsale_amount_required. - For a shipment,
itemssuppliescommitmentIdandsaleAmountMinorper line. Unnamed lines use their JPY market values. saleCurrencydefaults toJPY. It requires an amount for a hold, oritemsfor a shipment. Non-JPY shipments need an explicit amount for every line.
Do not replace a missing price with zero just to retry. Confirm your sale price before shipping the same target again.
4. Shelves, sites and checkouts
These need inventory:read, inventory:move and the member’s inventory.write permission. Reads need the same access and only expose documents created by your app.
| Operation | Input and result |
|---|---|
POST /inventory/items/{id}/move |
toLocationId and reason. Move within one site; already there returns moved: false |
POST /inventory/transfers |
requestId, toSiteId, inventoryItemIds, reason. Send up to 200 units from one site to another, in transit |
POST /inventory/transfers/{id}/receive |
toLocationId is a shelf at the destination. Optional inventoryItemIds; omitted receives all remaining in-transit units |
POST /inventory/transfers/{id}/return |
reason and optional inventoryItemIds. Return in-transit units to their original shelves; received units cannot use this operation |
POST /inventory/checkouts |
requestId, inventoryItemIds, destinationLabel, reason. Take up to 200 units out for a shoot, event or similar purpose |
POST /inventory/checkouts/{id}/return |
items with each inventoryItemId and toLocationId, plus reason. Put returned physical units on their shelves |
Checked-out units are removed, off shelves and unavailable for sale until returned. A checkout does not record a sale. Read transfers with GET /inventory/transfers/{id} and checkouts with GET /inventory/checkouts/{id}.
5. Retries and refusals
Save one UUID requestId per business creation and reuse the same ID and content after a network failure. Creation returns 201; replay returns 200 and the current object. Reusing an ID for different content fails with idempotency_conflict. Do not create a new ID just because you did not receive the response.
Unknown fields, blank reasons, duplicate IDs and oversized batches are refused. A reason is trimmed, must contain 1–2,000 characters and cannot contain invalid control characters. Do not send the unit’s version; the server reads it.
| Error | Action |
|---|---|
conflict |
Read the target again, check its current state, then retry the same operation |
receipt_not_confirmed |
Have the shop complete receipt confirmation first |
unit_unavailable / unit_not_allocated |
Sync stock and allocations again. Choosing a different unit is a new business creation |
hold_confirmed / hold_shipped |
The hold can no longer be released; ask the shop to check the document |
commitment_shipping |
Cancel the unshipped shipment before releasing the commitment |
shipment_shipped |
Cannot cancel after shipping. Record a return only after the physical units return |
*_blocked / *_refused |
Have the shop check status, loss, shelf or site issues; do not treat refusal as success |
Errors may include affected inventoryItemIds, holdIds, commitmentIds or requestId. See scopes and errors too.

