---
title: Sync, hold, ship and move stock
---

All paths below are relative to `https://api.toreca-cloud.com/partner/v1`. Complete [authorization and connection](/en/api/authorization) first. See the [API reference](/en/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.

:::warning
If a reloaded shipment’s `items[].commitmentId` is null or differs from the original commitment, stop shipping and returns and ask the shop administrator to check it. Even the correct original ID can then fail with `commitment_not_on_shipment`. Do not remove explicit prices or substitute another ID just to bypass the refusal.
:::

## 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](/en/api/scopes-and-errors) too.
