Skip to content
flintDocs

Return inspections

A return inspection states what an operator observed about received merchandise. It records a physical fact and grants no refund or resolution authority.

Create an inspection with POST /v1/returns/{return_id}/inspections. Read inspections with GET /v1/return-inspections?return_id= and GET /v1/return-inspections/{return_inspection_id}, or expand return_inspections on GET /v1/returns/{return_id}. Inspections 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 dispositions. 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.

An inspection names the return_receipt_id it is checking and the inspection_location_id it happened at. Filter GET /v1/return-inspections by inspection_location_id.

Corrections#

An inspection is an immutable observation. To correct one, create a replacement carrying supersedes_return_inspection_id and a correction_reason. The original stays readable with an observation status of superseded. Correct an inspection before a disposition consumes it. The /decide route only settles review_required, so a superseding inspection is also how you correct an accepted or rejected call.

Inspection lines#

Each line answers three separate questions, and all three are required:

  • condition grades the item: new, unopened, opened, used, damaged, defective, incomplete, undetermined. Choose undetermined when the item's condition could not be assessed.
  • finding_codes records what was discovered: matches_expected_item, wrong_item, damaged, defective, used, missing_parts, empty_package, counterfeit_suspected, other.
  • acceptance_status is the call: accepted, rejected, or review_required.

Several words appear in both condition and finding_codes and mean different things there, so read the field name alongside the value.

Acceptance#

Accepted quantity satisfies after_inspection release timing. Under manual receipt disposition, it becomes dispositionable. Under automatic receipt disposition, acceptance creates a successful sellable disposition and returns it in generated_dispositions.

review_required defers the call instead. It raises an inspection_review_required blocker that holds the Return open until POST /v1/return-inspections/{return_inspection_id}/line-items/{return_inspection_line_item_id}/decide settles it with an acceptance_status and an acceptance_decision_reason of inspection_result, return_policy, manual_review, or other.

The Return inspection object#

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

Attributes

correction_reasonenum
  • entry_error
  • duplicate_observation
  • source_correction
  • reconciliation_correction
  • other
correction_reason_messagestring
created_atstringRequired

RFC3339 timestamp.

external_actor_idstring

Your identifier for the actor who recorded the event. Don't put secrets in this field.

external_reference_idstring

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

generated_dispositionsarray of objectRequired
inspected_atstringRequired

RFC3339 timestamp.

inspection_location_idstringRequired

Location where the returned merchandise was inspected. Must match the receipt receiving_location_id.

line_itemsarray of objectRequired
return_idstringRequired
return_inspection_idstringRequired
return_receipt_idstringRequired
source_systemobject or nullRequired
statusenumRequired
  • current
  • superseded
superseded_atstring

RFC3339 timestamp.

superseded_by_return_inspection_idstring
supersedes_return_inspection_idstring

List return inspections#

GET/v1/return-inspections

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 inspection observations. Omitting return_id lists inspections across every Return for the merchant.

Query parameters

acceptance_statusarray of enum

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

  • accepted
  • rejected
  • review_required
created_afterstring

Inclusive lower bound on created_at.

created_beforestring

Exclusive upper bound on created_at.

external_reference_idstring

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

inspected_afterstring

Inclusive lower bound on inspected_at.

inspected_beforestring

Exclusive upper bound on inspected_at.

inspection_location_idstring

Filter by inspection location id.

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 inspection ID or external reference ID.

return_idstring

Filter by return id.

return_line_item_idstring

Filter by return line item id.

return_receipt_idstring

Filter by return receipt id.

source_system_typearray of enum

Filter by source system 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.

  • manual
  • pos
  • wms
  • erp
  • other
  • flint
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.

  • current
  • superseded

Response · 200

dataarray of objectRequired
metaobject
next_page_tokenstring
request_idstring
curl https://api.withflintpay.com/v1/return-inspections \
  -H "Flint-Version: 2026-09-07" \
  -H "Authorization: Bearer YOUR_API_KEY"

Get return inspection#

GET/v1/return-inspections/{return_inspection_id}

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

Retrieve one inspection with its line items, findings, and current or superseded observation status.

Path parameters

return_inspection_idstringRequired

Flint return inspection id.

Response · 200

dataobjectRequired
metaobject
request_idstring
curl https://api.withflintpay.com/v1/return-inspections/{return_inspection_id} \
  -H "Flint-Version: 2026-09-07" \
  -H "Authorization: Bearer YOUR_API_KEY"

Decide return inspection line item#

POST/v1/return-inspections/{return_inspection_id}/line-items/{return_inspection_line_item_id}/decideIdempotent

Requires scope commerce.returns.operations.write

Record the accept or reject outcome for inspected quantity. expected_version compares against the parent Return version, not the inspection version. Accepted quantity becomes dispositionable and satisfies after_inspection release timing.

Path parameters

return_inspection_idstringRequired

Flint return inspection id.

return_inspection_line_item_idstringRequired

Flint return inspection line item id.

Request body

acceptance_decision_reasonenumRequired
  • inspection_result
  • return_policy
  • manual_review
  • other
acceptance_decision_reason_messagestring
acceptance_statusenumRequired
  • accepted
  • rejected
  • review_required
expected_versioninteger

Optional version of the parent Return. A stale value returns RETURN_VERSION_CONFLICT with the current Return version.

Response · 200

Same response as Get return inspection.

curl -X POST https://api.withflintpay.com/v1/return-inspections/{return_inspection_id}/line-items/{return_inspection_line_item_id}/decide \
  -H "Flint-Version: 2026-09-07" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: a-unique-key" \
  -d '{
    "acceptance_decision_reason": "inspection_result",
    "acceptance_status": "accepted"
  }'

Create return inspection#

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

Requires scope commerce.returns.operations.write

Record an immutable inspection observation. Corrections supersede an earlier inspection instead of editing physical history. Read inspections with `GET /v1/return-inspections?return_id=` or expand `return_inspections` on `GET /v1/returns/{return_id}`.

Path parameters

return_idstringRequired

Flint return id.

Request body

correction_reasonenum
  • entry_error
  • duplicate_observation
  • source_correction
  • reconciliation_correction
  • other
correction_reason_messagestring
external_actor_idstring

Your identifier for the actor who recorded the event. Don't put secrets in this field.

external_reference_idstring

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

inspected_atstringRequired

When the event occurred, at most 5 minutes in the future.

inspection_location_idstringRequired

Location where the returned merchandise was inspected. Must match the receipt receiving_location_id.

line_itemsarray of objectRequired
return_receipt_idstringRequired
source_systemobject
supersedes_return_inspection_idstring

Response · 201

Same response as Get return inspection.

curl -X POST https://api.withflintpay.com/v1/returns/ret_01K0P7W6A4N9F3J2T8Q5R1C6XM/inspections \
  -H "Flint-Version: 2026-09-07" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: a-unique-key" \
  -d '{
    "inspected_at": "",
    "inspection_location_id": "",
    "line_items": [
      {
        "acceptance_status": "accepted",
        "condition": "new",
        "quantity": 0,
        "return_receipt_line_item_id": ""
      }
    ],
    "return_receipt_id": ""
  }'

Was this helpful?