Receive Shipment
POST/api/amazon/:integrationInstance/removal-shipments/:removalShipment/receive
Record receipt of a removal shipment. Splits returned units into new (resellable), discarded (damaged), and optionally blemished. items[].blemished_configurations is an array where each entry represents ONE blemished unit. The shipment must belong to the supplied integration instance (404 otherwise).
This endpoint currently requires session authentication; Personal Access Token scope support is in progress.
Validation:
receipt_date— required, dateitems— required, min:1items[].quantity_new— required integer >= 0items[].quantity_discarded— required integer >= 0items[].cogs_per_unit— required numeric >= 0items[].product_id— required, exists:products,iditems[].removal_shipment_id— nullable integeritems[].quantity_blemished— nullable integer >= 0items[].blemished_configurations— nullable array
items[].product_id may be null ONLY for a discard-only receipt of an FNSKU marked as an unknown item (quantity_new and quantity_blemished must be 0, quantity_discarded > 0). Otherwise product_id is required.
A receipt larger than what is still pending on the shipment (what Amazon shipped minus what is already received, discarded or reconciled) is refused with 422 saying how many are left.
Request
Responses
- 200
- 401
- 403
- 404
- 422
- 429
OK
Response Headers
Unauthenticated — the bearer token is missing, revoked, expired, or malformed. Never retry automatically; fix the credential. See the Errors guide.
Forbidden — the token lacks a required scope, the endpoint is not available to API tokens, or the user behind the token lacks the permission. A human must adjust the token scopes or user permissions; do not retry.
Not found — no record with the given identifier (or the route does not exist). Verify the ID before retrying.
Unprocessable Entity
Response Headers
Rate limited — platform limit is 1,000 requests/min; individual tokens may carry lower limits. Honor the Retry-After header before retrying. See the Rate Limits guide.