# POST /partner/dispatch/shipments/{shipment_id}/units/release

Retirer des unités d'une commande B2B encore ouverte, avec un motif. Droit dispatch:write.

Source : https://docs.sealtrust.io/reference/post-partner-dispatch-shipments-id-units-release/

---

Vous retirez des unités d'une commande encore ouverte, par exemple une unité
abîmée ou mise par erreur dans le carton. La ligne n'est pas effacée : elle est
close, avec la date, l'auteur et le motif. Le parcours complet est dans le guide [Rattacher chaque unité à sa commande](/expedition-b2b/).

## Autorisation

Clef d'API dans l'en-tête `Authorization`, au format `Bearer`, avec le droit
`dispatch:write`. Une clef sans ce droit reçoit un 403 dont le message nomme le
droit manquant. L'offre de la marque de la clef doit comprendre l'accès API, et
la marque de l'expédition doit être sur l'offre Conformité + Identité.

```http
Authorization: Bearer votre_clef
```

## Plafond d'appels

Le même que les autres routes partenaires : un compteur par clef et un compteur
pour la somme des clefs de votre marque, 120 appels par fenêtre de 60 secondes
par défaut. Chaque appel qui écrit prélève 1 unité du quota journalier de la
clef, quel que soit le nombre d'unités qu'il porte.

## Corps de la requête

| Nom | Type | Obligatoire | Description |
| --- | --- | --- | --- |
| `units` | `array` de `string` | oui | De 1 à 1000 unités, sous les mêmes formes que pour l'ajout. |
| `reason` | `string` | oui | Le motif, 1 à 200 caractères. |

## Requête d'exemple

```bash
curl -i -X POST "https://api.sealtrust.io/v1/partner/dispatch/shipments/318/units/release" \
  -H "Authorization: Bearer st_live_0000000000000000000000000000000000000000000000" \
  -H "Content-Type: application/json" \
  -d '{"units": ["K2M8Q0R4T6V1"], "reason": "damaged box"}'
```

## Réponse d'exemple

Code HTTP 200, la même forme que l'ajout. Chaque unité répond `released`,
`not_in_shipment` (elle n'est pas dans cette commande), `unknown_unit` ou
`unreadable`.

## Erreurs

| Code | Condition | Que faire |
| --- | --- | --- |
| 401 | Clef absente, mal formée ou inconnue. | Envoyez `Authorization: Bearer <votre clef>` avec la clef entière. |
| 403 | La clef n'a pas le droit `dispatch:write`. Message `Missing required scopes: dispatch:write`. | Créez une clef qui porte ce droit. |
| 403 | La marque est sur l'offre Conformité. `detail.code` vaut `OFFER_EXCLUDES_IDENTITY` et `detail.feature` vaut `dispatch`. Rien n'est enregistré. | Passez à l'offre Conformité + Identité. Réessayer ne changera rien. |
| 429 | Plafond de débit ou quota journalier atteint. | Attendez le nombre de secondes de `Retry-After`, ou minuit en temps universel pour le quota. |
| 404 | Aucune expédition de votre marque ne porte cet identifiant. Une expédition d'une autre marque répond exactement la même chose. | Vérifiez l'`id` rendu à la création. |
| 409 | L'expédition est close ou annulée. `detail.code` vaut `shipment_not_open`. | Une expédition close ne change plus. Créez une nouvelle commande. |