Return receipts

A return receipt states what reached a Flint Location. It records a physical fact and grants no refund or resolution authority.

Create a receipt with POST /v1/returns/{return_id}/receipts. Read receipts with GET /v1/return-receipts?return_id= and GET /v1/return-receipts/{return_receipt_id}, or expand return_receipts on GET /v1/returns/{return_id}. Receipts are written under their Return and read from their own top-level list.

These routes use the commerce.returns.operations.write scope, shared with inspections and dispositions. That separation lets a warehouse or WMS integration record custody without permission to move buyer funds. 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.

Corrections#

A receipt is an immutable observation. To correct one, create a replacement carrying supersedes_return_receipt_id and a correction_reason. The original stays readable with an observation status of superseded. A receipt cannot be corrected after an inspection or disposition consumes it.

Automatic receipt disposition consumes matched merchandise immediately. Use a policy revision with receipt_disposition_mode: manual when your workflow needs a receipt-correction window.

Receipt line shapes#

A receipt line takes one of three shapes, and the shape decides what its quantity is allowed to do next.

Shape	Send	Effect
Matched	`return_line_item_id`	Counts toward `received_quantity` and satisfies `after_receipt` release timing
Unverified	`unverified_item` with a name and SKU	Counts toward no line and releases no gate. Raises a `merchandise_exception` blocker until verified
Excess	quantity beyond what was approved	Counts as excess

Verify an unidentified line with POST /v1/return-receipts/{return_receipt_id}/line-items/{return_receipt_line_item_id}/verify once an operator establishes the identity. Unverified and excess quantity can only take a non-inventory outcome such as discard, donate, or return_to_buyer, because Flint does not know which inventory item to increase.

release_timing gates every resolution type, including exchanges and replacements. See Return resolutions for how receipts release it.

The Return receipt object#

Every field on a return receipt, 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

line_itemsarray of objectRequired

received_atstringRequired

RFC3339 timestamp.

receiving_location_idstringRequired

return_idstringRequired

return_receipt_idstringRequired

shipment_idstring

source_systemobject or nullRequired

statusenumRequired

current
superseded

superseded_atstring

RFC3339 timestamp.

superseded_by_return_receipt_idstring

supersedes_return_receipt_idstring

List return receipts#

GET/v1/return-receipts

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

Query parameters

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.

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

received_afterstring

Inclusive lower bound on received_at.

received_beforestring

Exclusive upper bound on received_at.

receiving_location_idstring

Filter by receiving location id.

return_idstring

Filter by return id.

return_line_item_idstring

Filter by return line item id.

shipment_idstring

Filter by shipment 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

verification_statusarray of enum

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

matched
unverified
excess

Response · 200

dataarray of objectRequired

metaobject

next_page_tokenstring

request_idstring

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

Get return receipt#

GET/v1/return-receipts/{return_receipt_id}

Retrieve one merchandise receipt with its line items and its current or superseded observation status.

Path parameters

return_receipt_idstringRequired

Flint return receipt id.

Response · 200

dataobjectRequired

metaobject

request_idstring

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

Verify return receipt line item#

POST/v1/return-receipts/{return_receipt_id}/line-items/{return_receipt_line_item_id}/verifyIdempotent

Requires scope commerce.returns.operations.write

Establish the Return line identity for receipt quantity that arrived without one. expected_version compares against the parent Return version, not the receipt version. Unverified quantity counts toward no line and releases no release timing gate until it is verified.

Path parameters

return_receipt_idstringRequired

Flint return receipt id.

return_receipt_line_item_idstringRequired

Flint return receipt line item id.

Request body

expected_versioninteger

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

return_line_item_idstringRequired

verification_reasonenumRequired

order_match_confirmed
sku_match_confirmed
inspection_confirmed
merchant_review
other

verification_reason_messagestring

Response · 200

Same response as Get return receipt.

curl -X POST https://api.withflintpay.com/v1/return-receipts/{return_receipt_id}/line-items/{return_receipt_line_item_id}/verify \
  -H "Flint-Version: 2026-09-07" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: a-unique-key" \
  -d '{
    "return_line_item_id": "",
    "verification_reason": "order_match_confirmed"
  }'

Create return receipt#

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

Requires scope commerce.returns.operations.write

Record an immutable merchandise receipt observation. Corrections supersede an earlier receipt instead of editing physical history. Read receipts with `GET /v1/return-receipts?return_id=` or expand `return_receipts` 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.

line_itemsarray of one ofRequired

received_atstringRequired

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

receiving_location_idstringRequired

shipment_idstring

source_systemobject

supersedes_return_receipt_idstring

Response · 201

Same response as Get return receipt.

curl -X POST https://api.withflintpay.com/v1/returns/ret_01K0P7W6A4N9F3J2T8Q5R1C6XM/receipts \
  -H "Flint-Version: 2026-09-07" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: a-unique-key" \
  -d '{
    "line_items": [
      {
        "quantity": 0
      }
    ],
    "received_at": "",
    "receiving_location_id": ""
  }'

Was this helpful?