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

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.

POST/inventory/shipments/{id}/returns
Authorization
AuthorizationOAuth2 access token · headerrequired

Authorization 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.

Scopes:inventory:readinventory:write
Path parameters
idstring<uuid>required
Request body
requiredapplication/json
requestIdstring<uuid>required
commitmentIdsstring<uuid>[]required
min items 1 · max items 200
reasonstringrequired
min length 1 · max length 2000
Responses
200

Success

returnsobject[]required
Show properties
Array of object
commitmentIdstring<uuid>required
commitmentCommitmentrequired
Show properties
idstring<uuid>required
createdAtstring<date-time>required
updatedAtstring<date-time>required
inventoryItemIdstring<uuid>required
assetNumberstringrequired
purposestringrequired
Allowed:oripasale
labelstringrequired
externalRefstring | nullrequired
Show properties
One of:
string
string
null
null
statusstringrequired
Allowed:on_saleallocatedshippingblockedshippedreleasedended
allocatedAtstring<date-time> | nullrequired
Show properties
One of:
string<date-time>
string<date-time>
null
null
allocationRefstring | nullrequired
Show properties
One of:
string
string
null
null
shipmentIdstring<uuid> | nullrequired
Show properties
One of:
string<uuid>
string<uuid>
null
null
closedAtstring<date-time> | nullrequired
Show properties
One of:
string<date-time>
string<date-time>
null
null
400

invalid_request: a parameter is invalid.

errorstringrequired

The error code

scopestring

With insufficient_scope, the missing scope

requestIdstring<uuid>
inventoryItemIdsstring<uuid>[]
holdIdsstring<uuid>[]
commitmentIdsstring<uuid>[]
401

invalid_token: the token is missing, expired, or for another resource.

errorstringrequired

The error code

scopestring

With insufficient_scope, the missing scope

requestIdstring<uuid>
inventoryItemIdsstring<uuid>[]
holdIdsstring<uuid>[]
commitmentIdsstring<uuid>[]
403

One of insufficient_scope, connection_revoked, client_disabled or forbidden.

errorstringrequired

The error code

scopestring

With insufficient_scope, the missing scope

requestIdstring<uuid>
inventoryItemIdsstring<uuid>[]
holdIdsstring<uuid>[]
commitmentIdsstring<uuid>[]
404

not_found

errorstringrequired

The error code

scopestring

With insufficient_scope, the missing scope

requestIdstring<uuid>
inventoryItemIdsstring<uuid>[]
holdIdsstring<uuid>[]
commitmentIdsstring<uuid>[]
409

Conflict, reused requestId or receipt not confirmed

errorstringrequired

The error code

scopestring

With insufficient_scope, the missing scope

requestIdstring<uuid>
inventoryItemIdsstring<uuid>[]
holdIdsstring<uuid>[]
commitmentIdsstring<uuid>[]
422

The state, target or value refuses the operation. Inspect error and affected IDs.

errorstringrequired

The error code

scopestring

With insufficient_scope, the missing scope

requestIdstring<uuid>
inventoryItemIdsstring<uuid>[]
holdIdsstring<uuid>[]
commitmentIdsstring<uuid>[]
Try it
Server
Authorization
Parameters
Bodyapplication/json
Request
curl -X POST 'https://api.toreca-cloud.com/partner/v1/inventory/shipments/497f6eca-6276-4993-bfeb-53cbbbba6f08/returns' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "requestId": "d385ab22-0f51-4b97-9ecd-b8ff3fd4fcb6",
  "commitmentIds": [
    "497f6eca-6276-4993-bfeb-53cbbbba6f08"
  ],
  "reason": "string"
}'
Response
{
  "returns": [
    {
      "commitmentId": "4e1ecf7c-8127-4207-92b0-010ff43ff54d",
      "commitment": {
        "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
        "createdAt": "2019-08-24T14:15:22Z",
        "updatedAt": "2019-08-24T14:15:22Z",
        "inventoryItemId": "ef1bc09e-447a-46aa-a9d9-d86e3d490831",
        "assetNumber": "string",
        "purpose": "oripa",
        "label": "string",
        "externalRef": "string",
        "status": "on_sale",
        "allocatedAt": "2019-08-24T14:15:22Z",
        "allocationRef": "string",
        "shipmentId": "47efd5a2-af91-4417-950a-7f546cd1b5cf",
        "closedAt": "2019-08-24T14:15:22Z"
      }
    }
  ]
}

Was this page helpful?