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 that the unit never arrived	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. Replacement transfers only unused capacity, and both retry and replacement are refused once an inventory effect starts processing.

The Return disposition object#

Every field on a return disposition, as returned by retrieve and carried by the endpoints below.

Attributes

canceled_atstring

RFC3339 timestamp.

created_atstringRequired

RFC3339 timestamp.

created_byobjectRequired

disposition_typeenumRequired

sellable
quality_control
damaged
quarantined
repair
refurbish
liquidate
donate
discard
return_to_buyer
lost

external_reference_idstring

Caller-owned identifier for this resource in an external system.

failure_codestring

Reason code for a failed merchandise disposition, when available.

failure_messagestring

Explanation of a failed merchandise disposition, when available.

inventory_location_idstring

inventory_movement_idsarray of stringRequired

inventory_receipt_idstring

metadatamap of stringRequired

occurred_atstringRequired

RFC3339 timestamp.

quantityintegerRequired

Whole-number quantity; fractional quantities are not supported.

reasonenumRequired

inspection_result
return_policy
warehouse_override
safety_requirement
other

reason_messagestring

replaced_by_return_disposition_idstring

replaces_return_disposition_idstring

return_disposition_idstringRequired

return_idstringRequired

return_inspection_line_item_idstring

return_line_item_idstring

return_receipt_line_item_idstring

statusenumRequired

pending
succeeded
failed
canceled

supported_actionsarray of enumRequired

Actions that can succeed now. Empty unless the parent Return is open. cancel is listed only before the inventory effect starts.

cancel
retry

updated_atstringRequired

RFC3339 timestamp.

versionintegerRequired

List return dispositions#

GET/v1/return-dispositions

Requires scope commerce.return_policies.write or commerce.return_reasons.write or commerce.returns.operations.write or commerce.returns.read or commerce.returns.resolutions.write or commerce.returns.write

List merchandise dispositions. Omitting return_id lists dispositions across every Return for the merchant.

Query parameters

created_afterstring

Inclusive lower bound on created_at.

created_beforestring

Exclusive upper bound on created_at.

disposition_typearray of enum

Filter by disposition type. Accepts repeated keys, comma-separated values, or mixtures. 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.

sellable
quality_control
damaged
quarantined
repair
refurbish
liquidate
donate
discard
return_to_buyer
lost

external_reference_idstring

Exact-match filter on the caller-owned external reference ID.

inventory_location_idstring

Filter by inventory location id.

occurred_afterstring

Inclusive lower bound on occurred_at.

occurred_beforestring

Exclusive upper bound on occurred_at.

page_sizeinteger

Page size. Defaults to 20 and is capped at 100.

page_tokenstring

Opaque cursor returned by the previous page.

querystring

Search by return disposition ID or external reference ID.

replaces_return_disposition_idstring

Filter by replaces return disposition id.

return_idstring

Filter by return id.

return_inspection_line_item_idstring

Filter by return inspection line item id.

return_line_item_idstring

Filter by return line item id.

return_receipt_line_item_idstring

Filter by return receipt line item id.

statusarray of enum

Filter by status. Accepts repeated keys, comma-separated values, or mixtures. 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.

pending
succeeded
failed
canceled

updated_afterstring

Inclusive lower bound on updated_at.

updated_beforestring

Exclusive upper bound on updated_at.

Response · 200

dataarray of objectRequired

metaobject

next_page_tokenstring

request_idstring

curl https://api.withflintpay.com/v1/return-dispositions \
  -H "Flint-Version: 2026-09-07" \
  -H "Authorization: Bearer YOUR_API_KEY"

Get return disposition#

GET/v1/return-dispositions/{return_disposition_id}

Retrieve one disposition with its type, destination, quantity, status, and any linked inventory effect.

Path parameters

return_disposition_idstringRequired

Flint return disposition id.

Response · 200

dataobjectRequired

metaobject

request_idstring

curl https://api.withflintpay.com/v1/return-dispositions/retdsp_01K0P7W6A4N9F3J2T8Q5R1C6XM \
  -H "Flint-Version: 2026-09-07" \
  -H "Authorization: Bearer YOUR_API_KEY"

Cancel return disposition#

POST/v1/return-dispositions/{return_disposition_id}/cancelIdempotent

Requires scope commerce.returns.operations.write

Cancel a disposition that has not started its inventory effect. Cancellation is refused once the effect is processing.

Path parameters

return_disposition_idstringRequired

Flint return disposition id.

Request body

expected_versioninteger

reasonenumRequired

created_in_error
changed_disposition
duplicate
other

reason_messagestring

Response · 200

Same response as Get return disposition.

curl -X POST https://api.withflintpay.com/v1/return-dispositions/retdsp_01K0P7W6A4N9F3J2T8Q5R1C6XM/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 '{
    "reason": "created_in_error"
  }'

Retry return disposition#

POST/v1/return-dispositions/{return_disposition_id}/retryIdempotent

Requires scope commerce.returns.operations.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_idstringRequired

Flint return disposition id.

Request body

expected_versioninteger

reasonenumRequired

dependency_recovered
mapping_corrected
operator_retry
other

reason_messagestring

Response · 200

Same response as Get return disposition.

curl -X POST https://api.withflintpay.com/v1/return-dispositions/retdsp_01K0P7W6A4N9F3J2T8Q5R1C6XM/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 '{
    "reason": "dependency_recovered"
  }'

Create return disposition#

POST/v1/returns/{return_id}/dispositionsKey required

Requires scope commerce.returns.operations.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_idstringRequired

Flint return id.

Request body

Send exactly one of these

disposition_typeenumRequired

sellable
quality_control
damaged
quarantined
repair
refurbish
liquidate
donate
discard
return_to_buyer
lost

external_reference_idstring

Caller-owned identifier for this resource in an external system.

inventory_location_idstring

metadatamap of string

Caller-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_atstringRequired

RFC3339 timestamp.

quantityintegerRequired

Whole-number quantity; fractional quantities are not supported.

reasonenumRequired

inspection_result
return_policy
warehouse_override
safety_requirement
other

reason_messagestring

replaces_return_disposition_idstring

return_receipt_line_item_idstringRequired

disposition_typeenumRequired

sellable
quality_control
damaged
quarantined
repair
refurbish
liquidate
donate
discard
return_to_buyer
lost

external_reference_idstring

Caller-owned identifier for this resource in an external system.

inventory_location_idstring

metadatamap of string

Caller-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_atstringRequired

RFC3339 timestamp.

quantityintegerRequired

Whole-number quantity; fractional quantities are not supported.

reasonenumRequired

inspection_result
return_policy
warehouse_override
safety_requirement
other

reason_messagestring

replaces_return_disposition_idstring

return_inspection_line_item_idstringRequired

Response · 201

Same response as Get return disposition.

curl -X POST https://api.withflintpay.com/v1/returns/ret_01K0P7W6A4N9F3J2T8Q5R1C6XM/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",
    "occurred_at": "",
    "quantity": 0,
    "reason": "inspection_result"
  }'

Was this helpful?