Link Record to FBA Loss Event
POST/api/amazon/unified/fba-loss-events/:lossEvent/links
Links a record to a loss event by hand — a reimbursement or a found ledger row the automatic matcher could not place (for example a payment approved more than 120 days after the loss). Settlement lines are tied to payments automatically and cannot be linked by hand. Requires the integrations update permission.
integrations:writeGrant this scope to your token under Settings → Developer → Personal Access Tokens.
Body:
type(string, required) — reimbursement or ledger (a found ledger row).id(integer, required) — the record ID.quantity(integer, optional, min 1) — units to link; defaults to all the record's unlinked units (for a found row, no more than the loss still has missing).
Rules:
- Linking the same record to the same event again adds to the linked quantity rather than replacing it.
- A payment must be for the same FNSKU as the loss, and the loss must have room for its units (units not already found, paid for or replaced).
- A reversal (clawback) or a money-only top-up adjusts an earlier payment, so that payment must already be linked to this loss. A top-up, a reversal without units, and a reversal of a top-up are linked as money only (no units), and a money-only row can be linked only once.
- A found row must be a positive F or N ledger row on the event's Amazon account, for the same FNSKU as the event, and the event must be an inventory-ledger loss.
- Linking a record you previously removed from this event clears that removal, so automatic linking treats the pair normally again.
Returns the event with its refreshed timeline. 422 when:
typeis anything else (for example settlement) — "type must be reimbursement or ledger. Settlement lines are tied to payments automatically."- the reimbursement is not on the event's Amazon account — "Reimbursement not found on this Amazon account."
- the payment's FNSKU differs from the loss — "A payment can only be linked to a loss of the same FNSKU."
- a reversal or top-up whose original payment is not linked to this loss — "This row adjusts an earlier payment, which is not linked to this loss. Link that payment first."
- a money-only row that is already linked — "This row carries money only and is already linked."
- the reimbursement's units are already linked — "Reimbursement quantity already allocated (12 of 12)."
- the loss has too little room — "The loss has room for 2 more unit(s) from this payment."
- the ledger row is not a found row on the account — "Only a found (F or N) ledger row on this Amazon account can be linked by hand."
- the FNSKU or event source does not match for a found row — "A found row can only offset an inventory-ledger loss of the same FNSKU."
- the row or the loss has no units left — "Nothing left to link: the found row has 0 unit(s) free and the loss 3 unit(s) missing."
Errors other than the
typeone are reported underid.
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.