# POST /distributor-portal/shipments/{shipment_id}/receive

Confirm the reception of a shipment, optionally scanning cartons or units.

Source: https://docs.sealtrust.io/en/reference/post-distributor-portal-shipments-id-receive/

---

You confirm you received a shipment. The call records a reception event with
the date and your identity; scanning cartons or units is optional, a
confirmation with no scan at all is just as valid.

You can confirm the same shipment in several passes (part of it received
today, the rest tomorrow): each call adds its own confirmation, none replaces
another. A code already recorded by an earlier confirmation of the SAME
shipment is silently ignored if scanned again — re-scanning the same carton
twice, by mistake or by a replayed call, never counts it twice. A shipment
accepts at most 500 confirmation calls in total; past that, the call is
refused rather than letting the table grow without bound.

## Authorization

Session of a distributor contact account. See
[`GET /distributor-portal/me`](/en/reference/get-distributor-portal-me/). Same
isolation rule as the read: another distributor's shipment answers 404.

## Rate limit

30 calls a minute, shared with the rest of the distributor portal. This is the
only call of the portal that writes.

## Path parameters

| Parameter | Type | Description |
| --- | --- | --- |
| `shipment_id` | `integer` | The shipment's id, path. |

## Request body

| Field | Type | Description |
| --- | --- | --- |
| `scanned_identifiers` | `array` of `string` | Carton or unit codes scanned. Optional, at most 1000. |
| `note` | `string` or `null` | Free remark, at most 500 characters. Optional. |

## Example request

```bash
curl -i -X POST "https://api.sealtrust.io/v1/distributor-portal/shipments/318/receive" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiJ9.0000000000000000000000000000.0000000000000000000000000000" \
  -H "Content-Type: application/json" \
  -d '{"scanned_identifiers": ["DSP000000123", "DSP000000124"], "note": "Carton slightly damaged"}'
```

## Example response

HTTP 201.

```json
{
  "reception_id": 7,
  "shipment_id": 318,
  "received_at": "2026-10-05T08:30:00Z",
  "received_by": "Camille Exemple",
  "scanned_count": 2
}
```

## Errors

| Code | Condition | What to do |
| --- | --- | --- |
| 400 | More than 1000 scanned codes in one call. | Spread the scans over several confirmations. |
| 400 | This shipment already holds 500 confirmations. | Contact support; this ceiling is not meant to be reached in ordinary use. |
| 401 | Token missing, unreadable or expired. | Sign in again. |
| 403 | Account with no active distributor access. | See [`GET /distributor-portal/me`](/en/reference/get-distributor-portal-me/). |
| 404 | Unknown shipment, or one of another distributor. | Check the `id` in [`GET /distributor-portal/shipments`](/en/reference/get-distributor-portal-shipments/). |
| 422 | Malformed body: an undeclared field (the schema refuses unknown fields), or `note` past 500 characters. | Send only `scanned_identifiers` and `note`. |
| 429 | Rate limit exceeded. | Wait the delay in `Retry-After`. |

## See also

- [`GET /distributor-portal/shipments/{shipment_id}`](/en/reference/get-distributor-portal-shipments-id/),
  read back the confirmations already recorded.