Record a returned shipment
Name up to 200 shipped commitments whose units physically returned. Returns them to their original shelves and creates new allocated commitments for the customer. Each response commitmentId is the original ID; commitment.id is the new one. Repeating the same requestId returns the existing result. In addition to inventory:read, this needs its operation scope and the approving member’s inventory.write permission.
/inventory/shipments/{id}/returnsAuthorizationOAuth2 access token · headerrequiredAuthorization code flow (PKCE S256 required). Send resource=https://api.toreca-cloud.com/partner/v1 with the authorization, token and refresh requests. Access tokens last 15 minutes; refresh tokens last 90 days and rotate on every refresh.
inventory:readinventory:writeidstring<uuid>requiredapplication/jsonrequestIdstring<uuid>requiredcommitmentIdsstring<uuid>[]requiredreasonstringrequiredSuccess
returnsobject[]requiredShow propertiesHide properties
objectcommitmentIdstring<uuid>requiredcommitmentCommitmentrequiredShow propertiesHide properties
idstring<uuid>requiredcreatedAtstring<date-time>requiredupdatedAtstring<date-time>requiredinventoryItemIdstring<uuid>requiredassetNumberstringrequiredpurposestringrequiredoripasalelabelstringrequiredexternalRefstring | nullrequiredShow propertiesHide properties
stringnullstatusstringrequiredon_saleallocatedshippingblockedshippedreleasedendedallocatedAtstring<date-time> | nullrequiredShow propertiesHide properties
string<date-time>nullallocationRefstring | nullrequiredShow propertiesHide properties
stringnullshipmentIdstring<uuid> | nullrequiredShow propertiesHide properties
string<uuid>nullclosedAtstring<date-time> | nullrequiredShow propertiesHide properties
string<date-time>nullinvalid_request: a parameter is invalid.
errorstringrequiredThe error code
scopestringWith insufficient_scope, the missing scope
requestIdstring<uuid>inventoryItemIdsstring<uuid>[]holdIdsstring<uuid>[]commitmentIdsstring<uuid>[]invalid_token: the token is missing, expired, or for another resource.
errorstringrequiredThe error code
scopestringWith insufficient_scope, the missing scope
requestIdstring<uuid>inventoryItemIdsstring<uuid>[]holdIdsstring<uuid>[]commitmentIdsstring<uuid>[]One of insufficient_scope, connection_revoked, client_disabled or forbidden.
errorstringrequiredThe error code
scopestringWith insufficient_scope, the missing scope
requestIdstring<uuid>inventoryItemIdsstring<uuid>[]holdIdsstring<uuid>[]commitmentIdsstring<uuid>[]not_found
errorstringrequiredThe error code
scopestringWith insufficient_scope, the missing scope
requestIdstring<uuid>inventoryItemIdsstring<uuid>[]holdIdsstring<uuid>[]commitmentIdsstring<uuid>[]Conflict, reused requestId or receipt not confirmed
errorstringrequiredThe error code
scopestringWith insufficient_scope, the missing scope
requestIdstring<uuid>inventoryItemIdsstring<uuid>[]holdIdsstring<uuid>[]commitmentIdsstring<uuid>[]The state, target or value refuses the operation. Inspect error and affected IDs.
errorstringrequiredThe error code
scopestringWith insufficient_scope, the missing scope
requestIdstring<uuid>inventoryItemIdsstring<uuid>[]holdIdsstring<uuid>[]commitmentIdsstring<uuid>[]
