Return dispositions
A return disposition authorizes the final outcome for received merchandise. It records a physical fact and grants no refund or resolution authority.
Create a disposition with POST /v1/returns/{return_id}/dispositions. Read dispositions with GET /v1/return-dispositions?return_id= and GET /v1/return-dispositions/{return_disposition_id}, or expand return_dispositions on GET /v1/returns/{return_id}. Dispositions are written under their Return and read from their own top-level list.
These routes use the commerce.returns.operations.write scope, shared with receipts and inspections. POST /v1/returns/{return_id}/process combines this work with decisions and resolutions, so it requires all three scopes: commerce.returns.write, commerce.returns.operations.write, and commerce.returns.resolutions.write. The Receiving and inspecting guide walks one parcel through receipt, inspection, and disposition.
Disposition types#
A disposition targets either a receipt line or an inspection line, never both. Four of the eleven types change stock levels at the inventory_location_id you name.
| Disposition type | Stock effect | inventory_location_id |
|---|---|---|
sellable | Adds to sellable stock | Required |
quality_control | On hand, not sellable | Required |
damaged | On hand, not sellable | Required |
quarantined | On hand, not sellable | Required |
lost | None. Records received units as lost at that Location | Required |
repair, refurbish, liquidate, donate, discard, return_to_buyer | None | Rejected |
lost takes a location but moves no stock; it records where the loss was booked. The last row rejects inventory_location_id rather than ignoring it, so sending one fails the request.
Retry and replacement#
A failed disposition exposes retry, which preserves the disposition and effect identities so stock cannot move twice. When the type, destination, quantity, or source has changed, create a new disposition naming replaces_return_disposition_id instead. Only a failed or canceled disposition can be replaced, and replacement transfers only its unused capacity. Both retry and replacement are refused once an inventory effect starts processing.
Why a disposition was canceled#
POST /v1/return-dispositions/{return_disposition_id}/cancel cancels a pending or failed disposition. It requires a reason and accepts a reason_message. The canceled disposition keeps them:
| Field | Who can read it |
|---|---|
cancellation_reason | Any credential that can read the disposition. One of created_in_error, changed_disposition, duplicate, other; extensible |
cancellation_reason_message | Merchants only |
canceled_by | Merchants only. The actor who canceled it, with an actor_type and an actor_id when one exists |
reason and reason_message keep their meaning from creation: why the disposition was made, from inspection_result, return_policy, warehouse_override, safety_requirement, or other. They don't change when the disposition is canceled. The return_disposition.updated webhook sends the disposition, so it carries the cancellation fields.
A failed disposition that a replacement takes over also becomes canceled, with replaced_by_return_disposition_id set, and has no cancellation_reason. The reasons sent with /retry apply to an action that can repeat, so they aren't fields on the disposition; read them from GET /v1/returns/{return_id}/activities. See Return activities.
The Return disposition object#
A decision about how returned merchandise will be handled.
Returned by GET /v1/return-dispositions/{return_disposition_id} and carried by the endpoints below.
Attributes
canceled_atstringRFC3339 timestamp.
canceled_byobjectWho canceled the disposition. Merchant reads only.
actor_idstringID of the actor, when one exists. Merchant reads only.
actor_typeenumRequiredWhat kind of actor acted.
buyermerchantintegrationsystem
cancellation_reasonenumWhy the disposition was canceled.
created_in_errorchanged_dispositionduplicateother
cancellation_reason_messagestringDetail sent with the cancellation. Merchant reads only.
created_atstringRequiredRFC3339 timestamp.
created_byobjectRequiredWho created the disposition.
actor_idstringID of the actor, when one exists. Merchant reads only.
actor_typeenumRequiredWhat kind of actor acted.
buyermerchantintegrationsystem
disposition_typeenumRequiredWhat happens to the received units.
sellablequality_controldamagedquarantinedrepairrefurbishliquidatedonatediscardreturn_to_buyerlost
external_reference_idstringCaller-owned identifier for this resource in an external system.
failure_codeenumReason code for a failed merchandise disposition, when available.
inventory_effect_failedinventory_item_unmapped
failure_messagestringExplanation of a failed merchandise disposition, when available.
inventory_location_idstringID of the Location whose stock the disposition changes. Required for `sellable`, `quality_control`, `damaged`, `quarantined`, and `lost`; rejected for the other types.
inventory_movement_idsarray of stringRequiredIDs of the inventory movements the disposition wrote. Empty when it moved no stock.
inventory_receipt_idstringID of the inventory receipt the disposition recorded. Absent when it recorded none.
metadatamap of stringRequiredStored caller-owned key-value data. See `MetadataInput` for key, value, and size rules.
occurred_atstringRequiredRFC3339 timestamp.
quantityintegerRequiredWhole-number quantity; fractional quantities are not supported.
reasonenumRequiredWhy the disposition was made.
inspection_resultreturn_policywarehouse_overridesafety_requirementother
reason_messagestringOptional detail about `reason`, kept with the record.
replaced_by_return_disposition_idstringID of the disposition that took over this one. Present when a replacement canceled it.
replaces_return_disposition_idstringID of the `failed` or `canceled` disposition this one replaces. It takes over that disposition's unused capacity.
return_disposition_idstringRequiredUnique identifier for this return disposition, prefixed `retdsp_`.
return_idstringRequiredreturn_inspection_line_item_idstringID of the inspection line the disposition covers. Absent when it covers a receipt line.
return_line_item_idstringID of the Return line the units belong to.
return_receipt_line_item_idstringID of the receipt line the disposition covers. Absent when it covers an inspection line.
statusenumRequiredWhether inventory has applied the disposition.
pendingsucceededfailedcanceled
supported_actionsarray of enumRequiredActions that can succeed now. Empty unless the parent Return is open. cancel is listed only before the inventory effect starts.
cancelretry
updated_atstringRequiredRFC3339 timestamp.
versionintegerRequiredCurrent version of this resource's owned state. Send it as `expected_version` when changing the resource to reject a stale write.
{
"created_at": "2026-09-08T14:20:00Z",
"created_by": {
"actor_type": "integration"
},
"disposition_type": "sellable",
"inventory_location_id": "loc_01K1P6G4M7H2N8Q9R3S5T6V7WX",
"inventory_movement_ids": [],
"metadata": {},
"occurred_at": "2026-09-08T14:20:00Z",
"quantity": 1,
"reason": "return_policy",
"return_disposition_id": "retdsp_01KEZF7C00RHPH8RFSZF2DERBF",
"return_id": "ret_01KEZF7C00VDTZH2NK73DBK2HZ",
"return_line_item_id": "retli_01KEZF7C001NHF6JPD83VD0MRK",
"return_receipt_line_item_id": "retrcli_01KEZF7C00BCEA2ZKN4H8WYWXE",
"status": "pending",
"supported_actions": [
"cancel"
],
"updated_at": "2026-09-08T14:20:00Z",
"version": 1
}List return dispositions#
/v1/return-dispositionsRequires scope commerce.returns.operations.write or commerce.returns.policies.write or commerce.returns.read or commerce.returns.reasons.write or commerce.returns.resolutions.write or commerce.returns.write
Rate limit: read
List merchandise dispositions. Omitting return_id lists dispositions across every Return for the merchant. Default order: created_at descending, then return_disposition_id descending.
Query parameters
created_afterstringInclusive lower bound on created_at.
created_beforestringExclusive upper bound on created_at.
disposition_typearray of enumFilter by disposition type. Values are trimmed and deduplicated in first-seen order; empty or unknown entries are rejected. Values within this filter are ORed; separate filters are ANDed.
sellablequality_controldamagedquarantinedrepairrefurbishliquidatedonatediscardreturn_to_buyerlost
external_reference_idstringExact-match filter on the caller-owned external reference ID.
idempotency_keystringFilter by the original Idempotency-Key, after trimming surrounding whitespace. Matching is exact and case-sensitive. Returns current authorized resources, not the recorded response. A pending resource does not prove that the operation succeeded, and an empty list does not prove that it had no effect.
inventory_location_idstringFilter by inventory location id.
occurred_afterstringInclusive lower bound on occurred_at.
occurred_beforestringExclusive upper bound on occurred_at.
page_sizeintegerMaximum number of results to return, from 1 to 100. Defaults to 20.
page_tokenstringOpaque next_page_token from the previous response. Omit on the first request. You may change `page_size` between pages. Reuse it with the same endpoint, filters, sort, and request context. Do not parse or construct tokens. An invalid, expired, or mismatched token returns a validation error.
querystringSearch by return disposition ID or external reference ID.
replaces_return_disposition_idstringFilter by replaces return disposition id.
return_idstringFilter by return id.
return_inspection_line_item_idstringFilter by return inspection line item id.
return_line_item_idstringFilter by return line item id.
return_receipt_line_item_idstringFilter by return receipt line item id.
statusarray of enumFilter by status. Values are trimmed and deduplicated in first-seen order; empty or unknown entries are rejected. Values within this filter are ORed; separate filters are ANDed.
pendingsucceededfailedcanceled
updated_afterstringInclusive lower bound on updated_at.
updated_beforestringExclusive upper bound on updated_at.
Response · 200
Successful response.
dataarray of objectRequiredResource, collection, or operation result returned by this request.
canceled_atstringRFC3339 timestamp.
canceled_byobjectWho canceled the disposition. Merchant reads only.
cancellation_reasonenumWhy the disposition was canceled.
created_in_errorchanged_dispositionduplicateother
cancellation_reason_messagestringDetail sent with the cancellation. Merchant reads only.
created_atstringRequiredRFC3339 timestamp.
created_byobjectRequiredWho created the disposition.
disposition_typeenumRequiredWhat happens to the received units.
sellablequality_controldamagedquarantinedrepairrefurbishliquidatedonatediscardreturn_to_buyerlost
external_reference_idstringCaller-owned identifier for this resource in an external system.
failure_codeenumReason code for a failed merchandise disposition, when available.
inventory_effect_failedinventory_item_unmapped
failure_messagestringExplanation of a failed merchandise disposition, when available.
inventory_location_idstringID of the Location whose stock the disposition changes. Required for `sellable`, `quality_control`, `damaged`, `quarantined`, and `lost`; rejected for the other types.
inventory_movement_idsarray of stringRequiredIDs of the inventory movements the disposition wrote. Empty when it moved no stock.
inventory_receipt_idstringID of the inventory receipt the disposition recorded. Absent when it recorded none.
metadatamap of stringRequiredStored caller-owned key-value data. See `MetadataInput` for key, value, and size rules.
occurred_atstringRequiredRFC3339 timestamp.
quantityintegerRequiredWhole-number quantity; fractional quantities are not supported.
reasonenumRequiredWhy the disposition was made.
inspection_resultreturn_policywarehouse_overridesafety_requirementother
reason_messagestringOptional detail about `reason`, kept with the record.
replaced_by_return_disposition_idstringID of the disposition that took over this one. Present when a replacement canceled it.
replaces_return_disposition_idstringID of the `failed` or `canceled` disposition this one replaces. It takes over that disposition's unused capacity.
return_disposition_idstringRequiredUnique identifier for this return disposition, prefixed `retdsp_`.
return_idstringRequiredreturn_inspection_line_item_idstringID of the inspection line the disposition covers. Absent when it covers a receipt line.
return_line_item_idstringID of the Return line the units belong to.
return_receipt_line_item_idstringID of the receipt line the disposition covers. Absent when it covers an inspection line.
statusenumRequiredWhether inventory has applied the disposition.
pendingsucceededfailedcanceled
supported_actionsarray of enumRequiredActions that can succeed now. Empty unless the parent Return is open. cancel is listed only before the inventory effect starts.
cancelretry
updated_atstringRequiredRFC3339 timestamp.
versionintegerRequiredCurrent version of this resource's owned state. Send it as `expected_version` when changing the resource to reject a stale write.
metaobjectAdditional information about this response.
api_versionstringAPI version used to produce this response.
idempotency_replayedbooleanWhether this response replays a stored result for the supplied Idempotency-Key.
trace_idstringTrace identifier to include when contacting Flint about this request.
warningsarray of objectConditions that need attention even though the request succeeded.
next_page_tokenstringOpaque token to send as `page_token` to retrieve the next page. Omitted when there is no next page.
request_idstringRequiredIdentifier of this API request, used to correlate logs and support requests.
curl https://api.withflintpay.com/v1/return-dispositions \
-H "Flint-Version: 2026-09-07" \
-H "Authorization: Bearer YOUR_API_KEY"Successful response.
{
"data": [
{
"created_at": "2026-09-08T14:20:00Z",
"created_by": {
"actor_type": "integration"
},
"disposition_type": "sellable",
"inventory_location_id": "loc_01K1P6G4M7H2N8Q9R3S5T6V7WX",
"inventory_movement_ids": [],
"metadata": {},
"occurred_at": "2026-09-08T14:20:00Z",
"quantity": 1,
"reason": "return_policy",
"return_disposition_id": "retdsp_01KEZF7C00RHPH8RFSZF2DERBF",
"return_id": "ret_01KEZF7C00VDTZH2NK73DBK2HZ",
"return_line_item_id": "retli_01KEZF7C001NHF6JPD83VD0MRK",
"return_receipt_line_item_id": "retrcli_01KEZF7C00BCEA2ZKN4H8WYWXE",
"status": "pending",
"supported_actions": [
"cancel"
],
"updated_at": "2026-09-08T14:20:00Z",
"version": 1
}
],
"meta": {
"api_version": "2026-09-07"
},
"request_id": "req_01KWM6WAHG3N9Q8T2V5XRZ7C4D"
}Get return disposition#
/v1/return-dispositions/{return_disposition_id}Requires scope commerce.returns.operations.write or commerce.returns.policies.write or commerce.returns.read or commerce.returns.reasons.write or commerce.returns.resolutions.write or commerce.returns.write
Rate limit: read
Retrieve one disposition with its type, destination, quantity, status, and any linked inventory effect.
Path parameters
return_disposition_idstringRequiredFlint return disposition id.
Response · 200
Successful response.
dataobjectRequiredResource, collection, or operation result returned by this request.
canceled_atstringRFC3339 timestamp.
canceled_byobjectWho canceled the disposition. Merchant reads only.
cancellation_reasonenumWhy the disposition was canceled.
created_in_errorchanged_dispositionduplicateother
cancellation_reason_messagestringDetail sent with the cancellation. Merchant reads only.
created_atstringRequiredRFC3339 timestamp.
created_byobjectRequiredWho created the disposition.
disposition_typeenumRequiredWhat happens to the received units.
sellablequality_controldamagedquarantinedrepairrefurbishliquidatedonatediscardreturn_to_buyerlost
external_reference_idstringCaller-owned identifier for this resource in an external system.
failure_codeenumReason code for a failed merchandise disposition, when available.
inventory_effect_failedinventory_item_unmapped
failure_messagestringExplanation of a failed merchandise disposition, when available.
inventory_location_idstringID of the Location whose stock the disposition changes. Required for `sellable`, `quality_control`, `damaged`, `quarantined`, and `lost`; rejected for the other types.
inventory_movement_idsarray of stringRequiredIDs of the inventory movements the disposition wrote. Empty when it moved no stock.
inventory_receipt_idstringID of the inventory receipt the disposition recorded. Absent when it recorded none.
metadatamap of stringRequiredStored caller-owned key-value data. See `MetadataInput` for key, value, and size rules.
occurred_atstringRequiredRFC3339 timestamp.
quantityintegerRequiredWhole-number quantity; fractional quantities are not supported.
reasonenumRequiredWhy the disposition was made.
inspection_resultreturn_policywarehouse_overridesafety_requirementother
reason_messagestringOptional detail about `reason`, kept with the record.
replaced_by_return_disposition_idstringID of the disposition that took over this one. Present when a replacement canceled it.
replaces_return_disposition_idstringID of the `failed` or `canceled` disposition this one replaces. It takes over that disposition's unused capacity.
return_disposition_idstringRequiredUnique identifier for this return disposition, prefixed `retdsp_`.
return_idstringRequiredreturn_inspection_line_item_idstringID of the inspection line the disposition covers. Absent when it covers a receipt line.
return_line_item_idstringID of the Return line the units belong to.
return_receipt_line_item_idstringID of the receipt line the disposition covers. Absent when it covers an inspection line.
statusenumRequiredWhether inventory has applied the disposition.
pendingsucceededfailedcanceled
supported_actionsarray of enumRequiredActions that can succeed now. Empty unless the parent Return is open. cancel is listed only before the inventory effect starts.
cancelretry
updated_atstringRequiredRFC3339 timestamp.
versionintegerRequiredCurrent version of this resource's owned state. Send it as `expected_version` when changing the resource to reject a stale write.
metaobjectAdditional information about this response.
api_versionstringAPI version used to produce this response.
idempotency_replayedbooleanWhether this response replays a stored result for the supplied Idempotency-Key.
trace_idstringTrace identifier to include when contacting Flint about this request.
warningsarray of objectConditions that need attention even though the request succeeded.
request_idstringRequiredIdentifier of this API request, used to correlate logs and support requests.
curl https://api.withflintpay.com/v1/return-dispositions/retdsp_01KEZF7C007H87J66PH2EEK1VW \
-H "Flint-Version: 2026-09-07" \
-H "Authorization: Bearer YOUR_API_KEY"Successful response.
{
"data": {
"created_at": "2026-09-08T14:20:00Z",
"created_by": {
"actor_type": "integration"
},
"disposition_type": "sellable",
"inventory_location_id": "loc_01K1P6G4M7H2N8Q9R3S5T6V7WX",
"inventory_movement_ids": [],
"metadata": {},
"occurred_at": "2026-09-08T14:20:00Z",
"quantity": 1,
"reason": "return_policy",
"return_disposition_id": "retdsp_01KEZF7C00RHPH8RFSZF2DERBF",
"return_id": "ret_01KEZF7C00VDTZH2NK73DBK2HZ",
"return_line_item_id": "retli_01KEZF7C001NHF6JPD83VD0MRK",
"return_receipt_line_item_id": "retrcli_01KEZF7C00BCEA2ZKN4H8WYWXE",
"status": "pending",
"supported_actions": [
"cancel"
],
"updated_at": "2026-09-08T14:20:00Z",
"version": 1
},
"meta": {
"api_version": "2026-09-07"
},
"request_id": "req_01KWM6WAHG3N9Q8T2V5XRZ7C4D"
}Cancel return disposition#
/v1/return-dispositions/{return_disposition_id}/cancelIdempotentRequires scope commerce.returns.operations.write
Rate limit: write
Cancel a disposition that has not started its inventory effect. Cancellation is refused once the effect is processing.
Path parameters
return_disposition_idstringRequiredFlint return disposition id.
Request body
expected_versionintegerOptional. The disposition's current version; a stale value returns 409 VERSION_CONFLICT.
reasonenumRequiredWhy it is being canceled.
created_in_errorchanged_dispositionduplicateother
reason_messagestringOptional detail about `reason`, kept with the record.
curl -X POST https://api.withflintpay.com/v1/return-dispositions/retdsp_01KEZF7C007H87J66PH2EEK1VW/cancel \
-H "Flint-Version: 2026-09-07" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: a-unique-key" \
-d '{
"expected_version": 1,
"reason": "created_in_error"
}'Retry return disposition#
/v1/return-dispositions/{return_disposition_id}/retryIdempotentRequires scope commerce.returns.operations.write
Rate limit: write
Retry a failed disposition with the same immutable intent. Disposition and effect identities are preserved, so a retry does not move stock twice.
Path parameters
return_disposition_idstringRequiredFlint return disposition id.
Request body
expected_versionintegerOptional. The disposition's current version; a stale value returns 409 VERSION_CONFLICT.
reasonenumRequiredWhy the disposition is being run again.
dependency_recoveredmapping_correctedoperator_retryother
reason_messagestringOptional detail about `reason`, kept with the record.
curl -X POST https://api.withflintpay.com/v1/return-dispositions/retdsp_01KEZF7C007H87J66PH2EEK1VW/retry \
-H "Flint-Version: 2026-09-07" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: a-unique-key" \
-d '{
"expected_version": 2,
"reason": "mapping_corrected"
}'Create return disposition#
/v1/returns/{return_id}/dispositionsKey requiredRequires scope commerce.returns.operations.write
Rate limit: write
Record an auditable merchandise disposition from either a receipt line or an inspection line. Read dispositions with `GET /v1/return-dispositions?return_id=` or expand `return_dispositions` on `GET /v1/returns/{return_id}`.
Path parameters
return_idstringRequiredFlint return id.
Request body
Send exactly one of these
The `Receipt line` variant of `CreateReturnDispositionRequest`.
disposition_typeenumRequiredWhat happens to the received units.
sellablequality_controldamagedquarantinedrepairrefurbishliquidatedonatediscardreturn_to_buyerlost
external_reference_idstringCaller-owned identifier for this resource in an external system.
inventory_location_idstringID of the Location whose stock the disposition changes. Required for `sellable`, `quality_control`, `damaged`, `quarantined`, and `lost`; rejected for the other types.
metadatamap of stringCaller-owned metadata. Values can't be empty strings. Keys starting with flint_ are reserved for Flint, are not returned, and cannot be written through the public API.
occurred_atstringRequiredRFC3339 timestamp.
quantityintegerRequiredWhole-number quantity; fractional quantities are not supported.
reasonenumRequiredWhy the disposition was made.
inspection_resultreturn_policywarehouse_overridesafety_requirementother
reason_messagestringOptional detail about `reason`, kept with the record.
replaces_return_disposition_idstringID of the `failed` or `canceled` disposition this one replaces. It takes over that disposition's unused capacity.
return_receipt_line_item_idstringRequiredID of the receipt line the disposition covers. Absent when it covers an inspection line.
The `Inspection line` variant of `CreateReturnDispositionRequest`.
disposition_typeenumRequiredWhat happens to the received units.
sellablequality_controldamagedquarantinedrepairrefurbishliquidatedonatediscardreturn_to_buyerlost
external_reference_idstringCaller-owned identifier for this resource in an external system.
inventory_location_idstringID of the Location whose stock the disposition changes. Required for `sellable`, `quality_control`, `damaged`, `quarantined`, and `lost`; rejected for the other types.
metadatamap of stringCaller-owned metadata. Values can't be empty strings. Keys starting with flint_ are reserved for Flint, are not returned, and cannot be written through the public API.
occurred_atstringRequiredRFC3339 timestamp.
quantityintegerRequiredWhole-number quantity; fractional quantities are not supported.
reasonenumRequiredWhy the disposition was made.
inspection_resultreturn_policywarehouse_overridesafety_requirementother
reason_messagestringOptional detail about `reason`, kept with the record.
replaces_return_disposition_idstringID of the `failed` or `canceled` disposition this one replaces. It takes over that disposition's unused capacity.
return_inspection_line_item_idstringRequiredID of the inspection line the disposition covers. Absent when it covers a receipt line.
curl -X POST https://api.withflintpay.com/v1/returns/ret_01KEZF7C00PG93650ZKVQNGF7X/dispositions \
-H "Flint-Version: 2026-09-07" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: a-unique-key" \
-d '{
"disposition_type": "sellable",
"inventory_location_id": "loc_01K1P6G4M7H2N8Q9R3S5T6V7WX",
"occurred_at": "2026-09-08T14:20:00Z",
"quantity": 1,
"reason": "return_policy",
"return_receipt_line_item_id": "retrcli_01KEZF7C00BCEA2ZKN4H8WYWXE"
}'Was this helpful?
