---
search:
  tags:
    - Inventory
    - POST
seo:
  description: >-
    Name up to 200 shipped commitments whose units physically… Reference for the
    POST /inventory/shipments/{id}/returns endpoint in the Toreca Cloud Partner
    API.
sidebar:
  label: Record a returned shipment
  badge: POST
title: Record a returned shipment
type: openapi-operation
---
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`

**Request body** (`application/json`, required)

- `requestId` (string<uuid>, required)
- `commitmentIds` (string<uuid>[], required)
- `reason` (string, required)

Request body example:

```json
{
  "requestId": "d385ab22-0f51-4b97-9ecd-b8ff3fd4fcb6",
  "commitmentIds": [
    "497f6eca-6276-4993-bfeb-53cbbbba6f08"
  ],
  "reason": "string"
}
```

**Responses**

- `200` — Success
- `400` — \`invalid\_request\`: a parameter is invalid.
- `401` — \`invalid\_token\`: the token is missing, expired, or for another resource.
- `403` — One of \`insufficient\_scope\`, \`connection\_revoked\`, \`client\_disabled\` or \`forbidden\`.
- `404` — \`not\_found\`
- `409` — Conflict, reused requestId or receipt not confirmed
- `422` — The state, target or value refuses the operation. Inspect error and affected IDs.

Response example, 200:

```json
{
  "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"
      }
    }
  ]
}
```
