Skip to content

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 typeStock effectinventory_location_id
sellableAdds to sellable stockRequired
quality_controlOn hand, not sellableRequired
damagedOn hand, not sellableRequired
quarantinedOn hand, not sellableRequired
lostNone. Records received units as lost at that LocationRequired
repair, refurbish, liquidate, donate, discard, return_to_buyerNoneRejected

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:

FieldWho can read it
cancellation_reasonAny credential that can read the disposition. One of created_in_error, changed_disposition, duplicate, other; extensible
cancellation_reason_messageMerchants only
canceled_byMerchants 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_atstring

RFC3339 timestamp.

canceled_byobject

Who canceled the disposition. Merchant reads only.

cancellation_reasonenum

Why the disposition was canceled.

  • created_in_error
  • changed_disposition
  • duplicate
  • other
cancellation_reason_messagestring

Detail sent with the cancellation. Merchant reads only.

created_atstringRequired

RFC3339 timestamp.

created_byobjectRequired

Who created the disposition.

disposition_typeenumRequired

What happens to the received units.

  • 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_codeenum

Reason code for a failed merchandise disposition, when available.

  • inventory_effect_failed
  • inventory_item_unmapped
failure_messagestring

Explanation of a failed merchandise disposition, when available.

inventory_location_idstring

ID 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 stringRequired

IDs of the inventory movements the disposition wrote. Empty when it moved no stock.

inventory_receipt_idstring

ID of the inventory receipt the disposition recorded. Absent when it recorded none.

metadatamap of stringRequired

Stored caller-owned key-value data. See `MetadataInput` for key, value, and size rules.

occurred_atstringRequired

RFC3339 timestamp.

quantityintegerRequired

Whole-number quantity; fractional quantities are not supported.

reasonenumRequired

Why the disposition was made.

  • inspection_result
  • return_policy
  • warehouse_override
  • safety_requirement
  • other
reason_messagestring

Optional detail about `reason`, kept with the record.

replaced_by_return_disposition_idstring

ID of the disposition that took over this one. Present when a replacement canceled it.

replaces_return_disposition_idstring

ID of the `failed` or `canceled` disposition this one replaces. It takes over that disposition's unused capacity.

return_disposition_idstringRequired

Unique identifier for this return disposition, prefixed `retdsp_`.

return_idstringRequired
return_inspection_line_item_idstring

ID of the inspection line the disposition covers. Absent when it covers a receipt line.

return_line_item_idstring

ID of the Return line the units belong to.

return_receipt_line_item_idstring

ID of the receipt line the disposition covers. Absent when it covers an inspection line.

statusenumRequired

Whether inventory has applied the disposition.

  • 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

Current version of this resource's owned state. Send it as `expected_version` when changing the resource to reject a stale write.

JSON
{
  "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#

GET/v1/return-dispositions

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

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_afterstring

Inclusive lower bound on created_at.

created_beforestring

Exclusive upper bound on created_at.

disposition_typearray of enum

Filter 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.

  • 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.

idempotency_keystring

Filter 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_idstring

Filter by inventory location id.

occurred_afterstring

Inclusive lower bound on occurred_at.

occurred_beforestring

Exclusive upper bound on occurred_at.

page_sizeinteger

Maximum number of results to return, from 1 to 100. Defaults to 20.

page_tokenstring

Opaque 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.

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. 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

Successful response.

dataarray of objectRequired

Resource, collection, or operation result returned by this request.

metaobject

Additional information about this response.

next_page_tokenstring

Opaque token to send as `page_token` to retrieve the next page. Omitted when there is no next page.

request_idstringRequired

Identifier 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.

JSON
{
  "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#

GET/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_idstringRequired

Flint return disposition id.

Response · 200

Successful response.

dataobjectRequired

Resource, collection, or operation result returned by this request.

metaobject

Additional information about this response.

request_idstringRequired

Identifier 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.

JSON
{
  "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#

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

Requires 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_idstringRequired

Flint return disposition id.

Request body

expected_versioninteger

Optional. The disposition's current version; a stale value returns 409 VERSION_CONFLICT.

reasonenumRequired

Why it is being canceled.

  • created_in_error
  • changed_disposition
  • duplicate
  • other
reason_messagestring

Optional detail about `reason`, kept with the record.

Response · 200

Successful response.

Same response as Get return disposition.

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#

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

Requires 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_idstringRequired

Flint return disposition id.

Request body

expected_versioninteger

Optional. The disposition's current version; a stale value returns 409 VERSION_CONFLICT.

reasonenumRequired

Why the disposition is being run again.

  • dependency_recovered
  • mapping_corrected
  • operator_retry
  • other
reason_messagestring

Optional detail about `reason`, kept with the record.

Response · 200

Successful response.

Same response as Get return disposition.

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#

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

Requires 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_idstringRequired

Flint return id.

Request body

Send exactly one of these

The `Receipt line` variant of `CreateReturnDispositionRequest`.

disposition_typeenumRequired

What happens to the received units.

  • 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

ID of the Location whose stock the disposition changes. Required for `sellable`, `quality_control`, `damaged`, `quarantined`, and `lost`; rejected for the other types.

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

Why the disposition was made.

  • inspection_result
  • return_policy
  • warehouse_override
  • safety_requirement
  • other
reason_messagestring

Optional detail about `reason`, kept with the record.

replaces_return_disposition_idstring

ID of the `failed` or `canceled` disposition this one replaces. It takes over that disposition's unused capacity.

return_receipt_line_item_idstringRequired

ID of the receipt line the disposition covers. Absent when it covers an inspection line.

Response · 201

Successful response.

Same response as Get return disposition.

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?