Skip to content
トレカクラウド
Esc
↑↓navigate↵open⌘Jpreview
Copy & AI tools

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

  1. Read sites and shelves with GET /inventory/sites.
  2. Call GET /inventory/changes without a cursor. While hasMore: true, pass nextCursor as the next cursor. Upsert data by type and id.
  3. 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

  1. Call POST /inventory/commitments with requestId, inventoryItemId, purpose, label and optional externalRef. The unit stays on its shelf and becomes on_sale in an oripa or sale. No shipment exists yet.
  2. After a win or purchase, call POST /inventory/commitments/{id}/allocate. Optional allocationRef records your order or opening reference. allocated means the shop holds it for that customer.
  3. When the customer requests delivery, call POST /inventory/shipments with requestId, commitmentIds, destinationLabel and reason. It combines up to 200 allocated commitments, which become shipping.
  4. At dispatch, call POST /inventory/shipments/{id}/ship. Put the carrier number in trackingNumber.

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 with sale_amount_required.
  • For a shipment, items supplies commitmentId and saleAmountMinor per line. Unnamed lines use their JPY market values.
  • saleCurrency defaults to JPY. It requires an amount for a hold, or items for 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.

Last updated on

Was this page helpful?